diff --git a/README.macos b/README.macos
deleted file mode 100644
index 722bdc939..000000000
--- a/README.macos
+++ /dev/null
@@ -1,146 +0,0 @@
-**********************************
-* Compiling linphone on macos X  *
-**********************************
-
-You need:
- - Xcode (download from apple or using appstore application)
- - Java SE
- - Macports: http://www.macports.org/
-   Download and install macports using its user friendly installer.
-
-- In order to enable generation of bundle for multiple macos version and 32 bit processors, it is recommended to:
-	1) edit /opt/local/etc/macports/macports.conf to add the following line:
-		macosx_deployment_target 10.6
-	2) edit /opt/local/etc/macports/variants.conf to add the following line:
-		+universal
-
-- Install build time dependencies
- $ sudo port install automake autoconf libtool intltool wget cunit
-
-- Install some linphone dependencies with macports
- $ sudo port install antlr3 speex libvpx readline sqlite3 libsoup openldap libupnp
- $ sudo port install ffmpeg-devel -gpl2
-
-- Install gtk. It is recommended to use the quartz backend for better integration.
- $ sudo port install gtk2 +quartz +no_x11
- $ sudo port install gtk-osx-application -python27
- $ sudo port install hicolor-icon-theme
-
-The next pieces need to be compiled manually. To ensure compatibility with multiple mac os version it is recommended to do:
- $ export MACOSX_DEPLOYMENT_TARGET=10.6
- $ export CFLAGS="-arch i386 -arch x86_64 -mmacosx-version-min=10.5"
- $ export OBJCFLAGS="-arch i386 -arch x86_64 -mmacosx-version-min=10.5"
- $ export CXXFLAGS="-arch i386 -arch x86_64 -mmacosx-version-min=10.5"
- $ export LDFLAGS="-arch i386 -arch x86_64 -mmacosx-version-min=10.5 -Wl,-headerpad_max_install_names -Wl,-read_only_relocs -Wl,suppress"
-
-- (Optional) libvpx-1.2 has a bug on macos resulting in ugly video. It is recommended to upgrade it manually to 1.3 from source.
-  The libvpx build isn't able to produce dual architecture files. To workaround this, configure libvpx twice and use lipo to create a dual architecture
-  libvpx.a .
-
-- Install libantlr3c (library used by belle-sip for parsing)
- $ git clone -b linphone git://git.linphone.org/antlr3.git
- $ cd antlr3/runtime/C
- $ ./autogen.sh
- $ ./configure --disable-static --prefix=/opt/local && make
- $ sudo make install
-
-- Install polarssl (encryption library used by belle-sip)
- $ git clone git://git.linphone.org/polarssl.git -b linphone
- $ cd polarssl
- $ ./autogen.sh && ./configure --prefix=/opt/local && make
- $ sudo make install
-
-- Install belle-sip (sip stack)
- $ git clone git://git.linphone.org/belle-sip.git
- $ cd belle-sip
- $ ./autogen.sh && ./configure --prefix=/opt/local && make
- $ sudo make install
-
-- Install srtp (optional) for call encryption
- $ git clone git://git.linphone.org/srtp.git
- $ cd srtp && autoconf && ./configure --prefix=/opt/local && make libsrtp.a
- $ sudo make install
-
-- Install zrtpcpp (optional), for unbreakable call encryption
- $ sudo port install cmake
- $ git clone https://github.com/wernerd/ZRTPCPP.git
- $ cd ZRTPCPP
- $ cmake -DCORE_LIB=true -DSDES=false CMAKE_INSTALL_NAME_DIR=/usr/local/lib/ -DCMAKE_C_FLAGS="-arch i386 -arch x86_64 -mmacosx-version-min=10.5" -DCMAKE_CXX_FLAGS="-arch i386 -arch x86_64 --stdlib=libstdc++ -std=c++11 -lstdc++ -mmacosx-version-min=10.5"  -DCMAKE_C_COMPILER=`xcrun --find clang` -DCMAKE_CXX_COMPILER=`xcrun --find clang` .
-$ sudo make install
-
-
-- Install gsm codec (optional)
- $ git clone git://git.linphone.org/gsm.git
- $ cd gsm
- $ make CCFLAGS="$CFLAGS -c -O2 -DNeedFunctionPrototypes=1"
- $ sudo make install INSTALL_ROOT=/opt/local GSM_INSTALL_INC=/opt/local/include
-
-- Compile and install the tunnel library (optional, proprietary extension only)
-
- If you got the source code from git, run ./autogen.sh first.
- Then or otherwise, do:
-
- $ ./configure --prefix=/opt/local && make && sudo make install
-
-- Compile linphone
-
- If you got the source code from git, run ./autogen.sh first.
-
- Then or otherwise, do:
-
- $ PKG_CONFIG_PATH=/usr/local/lib/pkgconfig ./configure --prefix=/opt/local --with-readline=/opt/local --disable-x11 --with-srtp=/opt/local --with-gsm=/opt/local --enable-zrtp --disable-strict && make
-
- Install to /opt/local
-
- $ sudo make install
-
- Done.
-
-If you want to generate a portable bundle, then install gtk-mac-bundler.
-Use git:
- $ git clone https://github.com/jralls/gtk-mac-bundler.git
- $ cd gtk-mac-bundler && make install
- $ export PATH=$PATH:~/.local/bin
- #make this dummy charset.alias file for the bundler to be happy:
- $ sudo touch /opt/local/lib/charset.alias
-
-The bundler file in build/macos/linphone.bundle expects some plugins to be installed in /opt/local/lib/mediastreamer/plugins .
-If you don't need plugins, remove or comment out this line from the bundler file:
-  <binary >
-    ${prefix:ms2plugins}/lib/mediastreamer/plugins/*.*.so
-  </binary>
-
-Then run, inside linphone source tree:
- Run configure as told before but with "--enable-relativeprefix" appended.
- $ make
- $ make bundle
-
-The resulting bundle is located in linphone build directory, together with a zipped version.
-
-For a better appearance, you can install the gtk-quartz-engine (a gtk theme) that make gtk application more similar to other mac applications (but not perfect).
-
- $ git clone https://github.com/jralls/gtk-quartz-engine.git
- $ cd gtk-quartz-engine
- $ autoreconf -i
- $ ./configure --prefix=/opt/local CFLAGS="$CFLAGS -Wno-error" && make
- $ sudo make install
-
-Generate a new bundle to have it included.
-
-libiconv hack
-*************
-
-The Makefile.am rules used to generate the bundle fetch a libiconv.2.dylib from a linphone download page.
-This library adds some additional symbols so that dependencies requiring the iconv from /usr/lib and the ones requiring from the bundle are both satisfied.
-In case this library needs to generated, here are the commands:
- $ wget http://ftp.gnu.org/pub/gnu/libiconv/libiconv-1.14.tar.gz
- $ cd libiconv-1.14
- $ patch -p1 < ../linphone/build/macos/libiconv-macos.patch
- $ ./configure --prefix=/opt/local --disable-static 'CFLAGS=-arch i386 -arch x86_64 -mmacosx-version-min=10.5' 'LDFLAGS=-arch i386 -arch x86_64 -mmacosx-version-min=10.5'  CXXFLAGS="-arch i386 -arch x86_64 -mmacosx-version-min=10.5" && make
- $ make install DESTDIR=/tmp
-
-The resulted library can be found in /tmp/opt/local/lib
-
-
-
-
diff --git a/README.macos.md b/README.macos.md
new file mode 100644
index 000000000..8b3ecc0cb
--- /dev/null
+++ b/README.macos.md
@@ -0,0 +1,202 @@
+# Compiling Linphone on MacOS X
+
+## Dependencies
+
+* Xcode (download from apple or using appstore application)
+* Java SE
+* [HomeBrew](http://brew.sh) or [Macports](http://www.macports.org/).
+
+### Multiple MacOS version support
+
+In order to enable generation of bundle for multiple MacOS version and 32 bit processors, it is recommended to:
+
+1. Edit `/opt/local/etc/macports/macports.conf` to add the following line:
+
+ > macosx_deployment_target 10.6
+
+2. Edit `/opt/local/etc/macports/variants.conf` to add the following line:
+
+ > +universal
+
+### Build time dependencies
+
+#### Using MacPorts
+
+* Linphone core dependencies
+ ```sh
+ sudo port install automake autoconf libtool intltool wget cunit \
+ antlr3 speex libvpx readline sqlite3 libsoup openldap libupnp \
+ ffmpeg-devel -gpl2
+ ```
+
+* UI dependencies: install `GTK`. It is recommended to use the `quartz` backend for better integration.
+
+ ```sh
+ sudo port install gtk2 +quartz +no_x11
+ sudo port install gtk-osx-application -python27
+ sudo port install hicolor-icon-theme
+ ```
+
+ #### Using HomeBrew
+
+ ```sh
+brew install automake intltool libtool pkg-config coreutils \
+yasm nasm wget imagemagick gettext gtk+ speex ffmpeg pygtk
+brew link gettext --force
+
+# Yet gtk-mac-integration is not available in main repository
+wget https://raw.githubusercontent.com/guitorri/homebrew/794cb6f68dd92cffc60da86fc4b900bc9ce571ef/Library/Formula/gtk-mac-integration.rb
+sudo mv gtk-mac-integration.rb /usr/local/Library/Formula/
+brew install gtk-mac-integration
+ ```
+
+ ### Building Linphone
+
+The next pieces need to be compiled manually.
+
+* To ensure compatibility with multiple MacOS versions it is recommended to do:
+
+ ```sh
+ export MACOSX_DEPLOYMENT_TARGET=10.6
+ export CFLAGS="-arch i386 -arch x86_64 -mmacosx-version-min=10.5"
+ export OBJCFLAGS="-arch i386 -arch x86_64 -mmacosx-version-min=10.5"
+ export CXXFLAGS="-arch i386 -arch x86_64 -mmacosx-version-min=10.5"
+ export LDFLAGS="-arch i386 -arch x86_64 -mmacosx-version-min=10.5 -Wl,-headerpad_max_install_names -Wl,-read_only_relocs -Wl,suppress"
+ ```
+
+* Install libantlr3c (library used by belle-sip for parsing)
+
+ ```sh
+ git clone -b linphone git://git.linphone.org/antlr3.git
+ cd antlr3/runtime/C
+ ./autogen.sh
+ ./configure --disable-static --prefix=/opt/local && make
+ sudo make install
+ ```
+
+* Install polarssl (encryption library used by belle-sip)
+ ```sh
+ git clone git://git.linphone.org/polarssl.git -b linphone
+ cd polarssl
+ ./autogen.sh && ./configure --prefix=/opt/local && make
+ sudo make install
+ ```
+
+* Install belle-sip (sip stack)
+
+ ```sh
+ git clone git://git.linphone.org/belle-sip.git
+ cd belle-sip
+ ./autogen.sh && ./configure --prefix=/opt/local && make
+ sudo make install
+ ```
+
+* (Optional) Install srtp for call encryption
+
+ ```sh
+ git clone git://git.linphone.org/srtp.git
+ cd srtp && autoconf && ./configure --prefix=/opt/local && make libsrtp.a
+ sudo make install
+ ```
+
+* (Optional) Install zrtpcpp, for unbreakable call encryption
+
+ ```sh
+ sudo port install cmake
+ git clone https://github.com/wernerd/ZRTPCPP.git
+ cd ZRTPCPP
+ cmake -DCORE_LIB=true -DSDES=false CMAKE_INSTALL_NAME_DIR=/usr/local/lib/ -DCMAKE_C_FLAGS="-arch i386 -arch x86_64 -mmacosx-version-min=10.5" -DCMAKE_CXX_FLAGS="-arch i386 -arch x86_64 --stdlib=libstdc++ -std=c++11 -lstdc++ -mmacosx-version-min=10.5"  -DCMAKE_C_COMPILER=`xcrun --find clang` -DCMAKE_CXX_COMPILER=`xcrun --find clang` .
+ sudo make install
+ ```
+
+* (Optional) Install gsm codec
+
+ ```sh
+ git clone git://git.linphone.org/gsm.git
+ cd gsm
+ make CCFLAGS="$CFLAGS -c -O2 -DNeedFunctionPrototypes=1"
+ sudo make install INSTALL_ROOT=/opt/local GSM_INSTALL_INC=/opt/local/include
+ ```
+
+* (Optional) libvpx-1.2 has a bug on MacOS resulting in ugly video. It is recommended to upgrade it manually to 1.3 from source.
+The libvpx build isn't able to produce dual architecture files. To workaround this, configure libvpx twice and use lipo to create a dual architecture `libvpx.a`.
+
+* (Optional, proprietary extension only) Compile and install the tunnel library
+
+ If you got the source code from git, run `./autogen.sh` first.
+ Then or otherwise, do:
+
+ `./configure --prefix=/opt/local && make && sudo make install`
+
+* Compile Linphone
+
+ If you got the source code from git, run `./autogen.sh` first.
+
+ Then or otherwise, do:
+
+ `PKG_CONFIG_PATH=/usr/local/lib/pkgconfig ./configure --prefix=/opt/local --with-readline=/opt/local --disable-x11 --with-srtp=/opt/local --with-gsm=/opt/local --enable-zrtp --disable-strict && make`
+
+* Install on the system
+
+ `sudo make install`
+
+You are done.
+
+### Generate portable bundle
+
+If you want to generate a portable bundle, then install `gtk-mac-bundler`:
+
+ ```sh
+ git clone https://github.com/jralls/gtk-mac-bundler.git
+ cd gtk-mac-bundler && make install
+ export PATH=$PATH:~/.local/bin
+ #make this dummy charset.alias file for the bundler to be happy:
+ sudo touch /opt/local/lib/charset.alias
+ ```
+
+The bundler file in `build/MacOS/linphone.bundle` expects some plugins to be installed in `/opt/local/lib/mediastreamer/plugins`.
+If you don't need plugins, remove or comment out this line from the bundler file:
+
+```xml
+<binary>
+${prefix:ms2plugins}/lib/mediastreamer/plugins/*.*.so
+</binary>
+```
+
+Then run, inside Linphone source tree configure as told before but with `--enable-relativeprefix` appended.
+
+ `make && make bundle`
+
+The resulting bundle is located in Linphone build directory, together with a zipped version.
+
+* For a better appearance, you can install `gtk-quartz-engine` (a GTK theme) that makes GTK application more similar to other Mac applications (but not perfect).
+
+ ```sh
+ git clone https://github.com/jralls/gtk-quartz-engine.git
+ cd gtk-quartz-engine
+ autoreconf -i
+ ./configure --prefix=/opt/local CFLAGS="$CFLAGS -Wno-error" && make
+ sudo make install
+ ```
+
+Generate a new bundle to have it included.
+
+### libiconv hack
+
+The `Makefile.am` rules used to generate the bundle fetch a `libiconv.2.dylib` from a Linphone download page.
+This library adds some additional symbols so that dependencies requiring the `iconv` from `/usr/lib` and the ones requiring from the bundle are both satisfied.
+In case this library needs to generated, here are the commands:
+
+ ```sh
+ wget http://ftp.gnu.org/pub/gnu/libiconv/libiconv-1.14.tar.gz
+ cd libiconv-1.14
+ patch -p1 < ../linphone/build/MacOS/libiconv-MacOS.patch
+ ./configure --prefix=/opt/local --disable-static 'CFLAGS=-arch i386 -arch x86_64 -mmacosx-version-min=10.5' 'LDFLAGS=-arch i386 -arch x86_64 -mmacosx-version-min=10.5'  CXXFLAGS="-arch i386 -arch x86_64 -mmacosx-version-min=10.5" && make
+ make install DESTDIR=/tmp
+ ```
+
+The resulted library can be found in `/tmp/opt/local/lib`.
+
+
+
+