docs: add setup guide for macOS

docs/macos-setup.rst

@@ -0,0 +1,138 @@
+Step 0: Prerequisites
+=====================
+
+Getting MacPorts or homebrew
+----------------------------
+
+Whether you compile the toolchain from source or download binary toolchain, there are some dependencies which need to be installed on macOS first. These dependencies are installed with one of the package managers: homebrew or MacPorts. If you have these already, you can skip the following instructions.
+
+- Install XCode from Mac App Store
+- Open Terminal.app and run ``xcode-select --install``
+- Run ``sudo xcodebuild -license`` and agree to XCode license
+- Install MacPorts_ or homebrew_
+
+.. _homebrew: http://brew.sh/
+.. _MacPorts: https://www.macports.org/install.php
+
+
+Step 1: Download binary toolchain for the ESP32
+==================================================
+
+ESP32 toolchain for macOS is available for download from Espresif website:
+
+http://dl.espressif.com/dl/xtensa-esp32-elf-osx-1.22.0-59.tar.gz
+
+Download this file, then extract it to the location you prefer, for example::
+
+    mkdir -p ~/esp
+    cd ~/esp
+    tar -xzf ~/Downloads/xtensa-esp32-elf-osx-1.22.0-59.tar.gz
+
+The toolchain will be extracted into ``~/esp/xtensa-esp32-elf/`` directory.
+
+To use it, you will need to update your ``PATH`` environment variable in ``~/.profile`` file. To make ``xtensa-esp32-elf`` available for all terminal sessions, add the following line to your ``~/.profile`` file::
+
+    export PATH=$PATH:$HOME/esp/xtensa-esp32-elf/bin
+
+Alternatively, you may create an alias for the above command. This way you can get the toolchain only when you need it. To do this, add different line to your ``~/.profile`` file::
+
+    alias get_esp32="export PATH=$PATH:$HOME/esp/xtensa-esp32-elf/bin"
+
+Then when you need the toolchain you can type ``get_esp32`` on the command line and the toolchain will be added to your ``PATH``.
+
+Alternative Step 1: Compile the toolchain from source using crosstool-NG
+========================================================================
+
+- Install dependencies:
+
+  - with MacPorts::
+
+        sudo port install gsed gawk binutils gperf grep gettext ncurses
+
+  - with homebrew (*TODO: provide list of packages for homebrew*)
+
+Create a case-sensitive filesystem image::
+
+    hdiutil create ~/esp/crosstool.dmg -volname "ctng" -size 10g -fs "Case-sensitive HFS+"
+
+Mount it::
+
+    hdiutil mount ~/esp/crosstool.dmg
+
+Create a symlink to your work directory::
+
+    cd ~/esp
+    ln -s /Volumes/ctng crosstool-NG
+
+Download ``crosstool-NG`` and build it::
+
+    cd ~/esp
+    git clone -b xtensa-1.22.x https://github.com/espressif/crosstool-NG.git
+    cd crosstool-NG
+    ./bootstrap && ./configure && make install
+
+Build the toolchain::
+
+    ./ct-ng xtensa-esp32-elf
+    ./ct-ng build
+
+Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``. Follow instructions given in the previous section to add the toolchain to your ``PATH``.
+
+Step 2: Getting ESP-IDF from github
+===================================
+
+Open Terminal.app, navigate to the directory you want to clone ESP-IDF and clone it using ``git clone`` command::
+
+    cd ~/esp
+    git clone --recursive https://github.com/espressif/esp-idf.git
+
+
+ESP-IDF will be downloaded into ``~/esp/esp-idf``. 
+
+Note the ``--recursive`` option! If you have already cloned ESP-IDF without this option, run another command to get all the submodules::
+
+    cd ~/esp/esp-idf
+    git submodule update --init
+
+
+Step 3: Starting a project
+==========================
+
+ESP-IDF by itself does not build a binary to run on the ESP32. The binary "app" comes from a project in a different directory. Multiple projects can share the same ESP-IDF directory.
+
+The easiest way to start a project is to download the template project from GitHub::
+
+    cd ~/esp
+    git clone https://github.com/espressif/esp-idf-template.git myapp
+
+This will download ``esp-idf-template`` project into ``~/esp/esp32app`` directory.
+
+
+Step 4: Building and flashing the application
+=============================================
+
+In Terminal.app, go to the application directory which was obtained on the previous step::
+
+    cd ~/esp/esp-idf-template
+
+Type a command like this to set the path to ESP-IDF directory:: 
+
+    export IDF_PATH=~/esp/esp-idf
+
+At this point you may configure the serial port to be used for uploading. Run::
+
+    make menuconfig
+
+Then navigate to "Serial flasher config" submenu and change value of "Default serial port" to match the serial port you will use. Also take a moment to explore other options which are configurable in ``menuconfig``.
+
+Now you can build and flash the application. Run::
+
+    make flash
+
+This will compile the application and all the ESP-IDF components, generate bootloader, partition table, and application binaries, and flash these binaries to your development board.
+
+Further reading
+===============
+
+If you'd like to use the Eclipse IDE instead of running ``make``, check out the Eclipse setup guide in this directory.
+