readme: refine structure; add info about mbedTLS.

README.md

@@ -2,11 +2,11 @@
 
 ## Intro
 
-[Shadowsocks-libev](http://shadowsocks.org) is a lightweight secured SOCKS5 
+[Shadowsocks-libev](http://shadowsocks.org) is a lightweight secured SOCKS5
 proxy for embedded devices and low-end boxes.
 
-It is a port of [Shadowsocks](https://github.com/shadowsocks/shadowsocks) 
-created by [@clowwindy](https://github.com/clowwindy), which is maintained by 
+It is a port of [Shadowsocks](https://github.com/shadowsocks/shadowsocks)
+created by [@clowwindy](https://github.com/clowwindy), which is maintained by
 [@madeye](https://github.com/madeye) and [@linusyang](https://github.com/linusyang).
 
 Current version: 2.4.3 | [Changelog](debian/changelog)
@@ -16,24 +16,76 @@ Travis CI: [![Travis CI](https://travis-ci.org/shadowsocks/shadowsocks-libev.svg
 ## Features
 
 Shadowsocks-libev is written in pure C and only depends on
-[libev](http://software.schmorp.de/pkg/libev.html) and 
+[libev](http://software.schmorp.de/pkg/libev.html) and
 [OpenSSL](http://www.openssl.org/) or [PolarSSL](https://polarssl.org/).
+The use of [mbedTLS](https://tls.mbed.org/) is added but still for testing, and
+it is not officially supported yet.
 
-In normal usage, the memory footprint is about 600KB and the CPU utilization is 
-no more than 5% on a low-end router (Buffalo WHR-G300N V2 with a 400MHz MIPS CPU, 
+In normal usage, the memory footprint is about 600KB and the CPU utilization is
+no more than 5% on a low-end router (Buffalo WHR-G300N V2 with a 400MHz MIPS CPU,
 32MB memory and 4MB flash).
 
+For a full list of feature comparison between different versions of shadowsocks,
+refer to the [Wiki page](https://github.com/shadowsocks/shadowsocks/wiki/Feature-Comparison-across-Different-Versions).
+
+
 ## Installation
 
-**Notes about PolarSSL**
+### Distribution-specific guide
+
+- [Debian & Ubuntu](#debian--ubuntu)
+    + [Install from repository](#install-from-repository)
+    + [Build deb package from source](#build-deb-package-from-source)
+    + [Configure and start the service](#configure-and-start-the-service)
+- [Fedora & RHEL](#fedora--rhel)
+    + [Install from repository](#install-from-repository-1)
+- [Archlinux](#archlinux)
+- [Directly build and install on UNIX-like system](#linux)
+- [FreeBSD](#freebsd)
+- [OpenWRT](#openwrt)
+- [OS X](#os-x)
+- [Windows](#windows)
+
+* * *
+
+### Pre-build configure guide
+
+For a complete list of avaliable configure-time option,
+try `configure --help`.
+
+#### Using alternative crypto library
+
+There are three crypto libraries available:
+
+- OpenSSL (**default**)
+- PolarSSL
+- mbedTLS (__NOT__ officially supported)
+
+##### PolarSSL
 
-* The default crypto library is OpenSSL. To build against PolarSSL,
-specify `--with-crypto-library=polarssl` and  `--with-polarssl=/path/to/polarssl`
-when running `./configure`.
-* PolarSSL __1.2.5 or newer__ is required. Currently, PolarSSL does __NOT__ support 
+To build against PolarSSL, specify `--with-crypto-library=polarssl`
+and `--with-polarssl=/path/to/polarssl` when running `./configure`.
+
+* PolarSSL __1.2.5 or newer__ is required. Currently, PolarSSL does __NOT__ support
 CAST5-CFB, DES-CFB, IDEA-CFB, RC2-CFB and SEED-CFB.
 * RC4 is only support by PolarSSL __1.3.0 or above__.
 
+##### mbedTLS
+To build against mbedTLS, specify `--with-crypto-library=mbedtls`
+and `--with-mbedtls=/path/to/mbedtls` when running `./configure`.
+
+Please not that we do **NOT** officially support mbedTLS right now,
+and you should use it at your own risk.
+
+Windows users will need extra work when compiling mbedTLS library,
+see [this issue](https://github.com/shadowsocks/shadowsocks-libev/issues/422) for detail info.
+
+#### Using shared library from system
+
+Please specify `--enable-system-shared-lib`. This will replace the bundled
+`libev`, `libsodium` and `libudns` with the corresponding libraries installed
+in the system during compilation and linking.
+
 ### Debian & Ubuntu
 
 #### Install from repository
@@ -82,7 +134,7 @@ Please follow the instructions on [Debian Backports](http://backports.debian.org
 This also means that you can only install those built packages on systems that have
 `init-system-helpers` installed.
 
-Otherwise, try to build and install directly from source. See the **Linux**
+Otherwise, try to build and install directly from source. See the [Linux](#linux)
 section below.
 
 ``` bash
@@ -145,11 +197,11 @@ sudo pacman -S shadowsocks-libev
 ```
 
 Please refer to downstream [PKGBUILD](https://projects.archlinux.org/svntogit/community.git/tree/trunk?h=packages/shadowsocks-libev)
-script for extra modifications.
+script for extra modifications and distribution-specific bugs.
 
 ### Linux
 
-For Unix-like systems, especially Debian-based systems, 
+For Unix-like systems, especially Debian-based systems,
 e.g. Ubuntu, Debian or Linux Mint, you can build the binary like this:
 
 ```bash
@@ -182,13 +234,16 @@ service shadowsocks_libev start
 
 ### OpenWRT
 
+**Note**: You may want to use [openwrt-shadowsocks](https://github.com/shadowsocks/openwrt-shadowsocks)
+, which is developed specifically for OpenWRT.
+
 ```bash
 # At OpenWRT build root
 pushd package
 git clone https://github.com/shadowsocks/shadowsocks-libev.git
 popd
 
-# Enable shadowsocks-libev in network category 
+# Enable shadowsocks-libev in network category
 make menuconfig
 
 # Optional
@@ -238,7 +293,7 @@ make lib WINDOWS=1
 make install DESTDIR="$HOME/prebuilt"
 ```
 
-Then, build the binary using the commands below, and all `.exe` files 
+Then, build the binary using the commands below, and all `.exe` files
 will be built at `$HOME/ss/bin`:
 
 #### OpenSSL
@@ -322,7 +377,7 @@ man pages of the applications, respectively.
 
 notes:
 
-    ss-redir provides a transparent proxy function and only works on the 
+    ss-redir provides a transparent proxy function and only works on the
     Linux platform with iptables.
 
 ```
@@ -334,7 +389,7 @@ The latest shadowsocks-libev has provided a *redir* mode. You can configure your
     # Create new chain
     root@Wrt:~# iptables -t nat -N SHADOWSOCKS
     root@Wrt:~# iptables -t mangle -N SHADOWSOCKS
-    
+
     # Ignore your shadowsocks server's addresses
     # It's very IMPORTANT, just be careful.
     root@Wrt:~# iptables -t nat -A SHADOWSOCKS -d 123.123.123.123 -j RETURN
@@ -358,7 +413,7 @@ The latest shadowsocks-libev has provided a *redir* mode. You can configure your
     root@Wrt:~# ip rule add fwmark 0x01/0x01 table 100
     root@Wrt:~# ip route add local 0.0.0.0/0 dev lo table 100
     root@Wrt:~# iptables -t mangle -A SHADOWSOCKS -p udp --dport 53 -j TPROXY --on-port 12345 --tproxy-mark 0x01/0x01
-    
+
     # Apply the rules
     root@Wrt:~# iptables -t nat -A PREROUTING -p tcp -j SHADOWSOCKS
     root@Wrt:~# iptables -t mangle -A PREROUTING -j SHADOWSOCKS