doc: add mac installation guide

Change-Id: I177fa345a0758fd6ba1305007b02d7ae49e25c86
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Signed-off-by: Rodrigo Caballero <rodrigo.caballero.abraham@intel.com>

doc/quick_start/installation_linux.rst

@@ -1,29 +1,36 @@
-.. _installing_zephyr:
+.. _installing_zephyr_linux:
 
-Development Environment Setup
+Development Environment Setup on Linux
-#############################
+######################################
 
-This section describes how to build the kernel in a development system
+This section describes how to build the kernel in a development system.
-and how to access the project source code.
+
+This guide was tested by compiling and running the Zephyr Kernel's sample
+applications on the following Linux distributions:
+
+* Ubuntu 14.04 LTS 64 bit
+* Fedora 22 64 bit
+
+Where needed, alternative instructions are listed for Ubuntu and Fedora.
 
 .. _linux_development_system:
 
 Installing the Host's Operating System
-======================================
+**************************************
 
 Building the project's software components including the kernel has been tested
 on Ubuntu and  Fedora systems. Instructions for installing these OSes are beyond
 the scope of this document.
 
 Configuring Network and Proxies
-===============================
+*******************************
 
 Building the kernel requires the command-line tools of git, ssh, wget,
 curl. Verify that each service can be run as both user and root and that access
 to the Internet and is not impeded by a firewall.
 
 Update Your Operating System
-============================
+****************************
 
 Before proceeding with the build, ensure your OS is up to date. On Ubuntu:
 
@@ -40,7 +47,7 @@ On Fedora:
 .. _required_software:
 
 Installing Requirements and Dependencies
-========================================
+****************************************
 
 Install the following with either apt-get or dnf.
 
@@ -62,5 +69,3 @@ Install the required packages in a Fedora host system with:
    $ sudo dnf group install "Development Tools"
    $ sudo dnf install git make gcc glib-devel.i686 glib2-devel.i686 \
      glibc-static libstdc++-static glibc-devel.i686
-
-

doc/quick_start/installation_mac.rst

@@ -0,0 +1,155 @@
+.. _installing_zephyr_mac:
+
+Development Environment Setup on Mac OS
+#######################################
+
+This section describes how to build the kernel in a development system.
+
+This guide was tested by compiling and running the Zephyr Kernel's sample
+applications on the following Mac OS version:
+
+* Mac OS X 10.11 (El Capitan)
+
+Update Your Operating System
+****************************
+
+Before proceeding with the build, ensure your OS is up to date.
+
+.. _mac_requirements:
+
+Installing Requirements and Dependencies
+****************************************
+
+To install the software components required to build the Zephyr kernel on a
+Mac, you will need to build a cross compiler for the target devices you wish to
+build for and install tools that the build system requires.
+
+First, install the :program:`Homebrew` (The missing package manager for
+OS X). Homebrew is a free and open-source software package management system
+that simplifies the installation of software on Apple's OS X operating
+system.
+
+To install :program:`Homebrew`, visit the site `<http://brew.sh/>`_ and follow the
+installation instructions on the site.
+
+To complete the Homebrew installation, you might be prompted to install some
+missing dependency. If so, follow please follow the instructions provided.
+
+After Homebrew was successfuly installed, install the following tools using the
+brew command line.
+
+.. code-block:: console
+
+   $ brew install gettext qemu help2man mpfr gmp coreutils wget
+
+   $ brew tap homebrew/dupes
+
+   $ brew install grep --default-names
+
+.. code-block:: console
+
+   $ brew install crosstool-ng
+
+Alternatively you can install the latest version of :program:`crosstool-ng`
+from source. Download the latest version from http://crosstool-ng.org. The
+latest version usually supports the latest released compilers.
+
+.. code-block:: console
+
+   $ wget
+   http://crosstool-ng.org/download/crosstool-ng/crosstool-ng-1.22.0.tar.bz2
+
+   $ tar xvf crosstool-ng-1.22.0.tar.bz2
+
+   $ cd crosstool-ng/
+
+   $ ./configure
+
+   $ make
+
+   $ make install
+
+
+Building the compiler requires a case-senstive file system. Therefore, use
+:program:`diskutil` to create an 8 GB blank sparse image making sure you select
+case-senstive file system (OS X Extended (Case-sensitive, Journaled) and
+mount it.
+
+Alternatively you can use the script below to create the image:
+
+.. code-block:: bash
+
+   #!/bin/bash ImageName=CrossToolNG ImageNameExt=${ImageName}.sparseimage
+   diskutil umount force /Volumes/${ImageName} && true rm -f ${ImageNameExt}
+   && true hdiutil create ${ImageName} -volname ${ImageName} -type SPARSE
+   -size 8g -fs HFSX hdiutil mount ${ImageNameExt} cd /Volumes/$ImageName
+
+
+When mounted, the file system of the image will be available under
+:file:`/Volumes`. Change to the mounted directory:
+
+.. code-block:: console
+
+   $ cd /Volumes/CrossToolNG
+
+   $ mkdir build
+
+   $ cd build
+
+In the Zephyr kernel source tree we provide two configurations for
+both ARM and X86 that can be used to pre-select the options needed
+for building the toolchain.
+The configuration files can be found in :file:`${ZEPHYR_BASE}/scripts/cross_compiler/`.
+
+.. code-block:: console
+
+   $ cp ${ZEPHYR_BASE}/scripts/cross_compiler/x86.config .config
+
+You can create a toolchain configuration or customize an existing configuration
+yourself using the configuration menus:
+
+.. code-block:: console
+
+   $ ct-ng menuconfig
+
+To build a kernel image for your desired architecture and platform, perform
+these steps:
+
+1. Select the architecture for which you are building the kernel.
+2. Select the target platform on which that kernel will run.
+3. Save the configuration.
+4. Build the toolchain with the saved configuration.
+5. Ensure that the build and installation directories are set correctly.
+6. Open the generated :file:`.config` file and verify the following (assuming
+   the sparse image was mounted under :file:`/Volumes/CrossToolNG`):
+
+
+.. code-block:: bash
+
+   ...
+   CT_LOCAL_TARBALLS_DIR="/Volumes/CrossToolNG/src"
+   # CT_SAVE_TARBALLS is not set
+   CT_WORK_DIR="${CT_TOP_DIR}/.build"
+   CT_PREFIX_DIR="/Volumes/CrossToolNG/x-tools/${CT_TARGET}"
+   CT_INSTALL_DIR="${CT_PREFIX_DIR}"
+   ...
+
+Now you are ready to build the toolchain:
+
+.. code-block:: console
+   $ ct-ng build
+
+The above process takes a while. When finished, the toolchain will be available
+under :file:`/Volumes/CrossToolNG/x-tools`.
+
+Repeat the step for all architectures you want to support in your environment.
+
+To use the toolchain with Zephyr, export the following environment variables
+and use the target location where the toolchain was installed, type:
+
+.. code-block:: console
+
+   $ export ZEPHYR_GCC_VARIANT=xtools
+
+   $ export ZEPHYR_SDK_INSTALL_DIR=/Volumes/CrossToolNG/x-tools
+

doc/quick_start/quick_start.rst

@@ -6,24 +6,24 @@ Quick Start Guide
 Use this guide to install the Zephyr development environment on your
 development system and to build the Zephyr Kernel on the supported platforms.
 
-Currently, the Zephyr Project supports Linux development systems only. This guide
+The following operating systems are supported:
-was tested by compiling and running the Zephyr Kernel's sample applications on
-the following Linux distributions:
 
-* Ubuntu 14.04 LTS 64 bit
+* Linux
-* Fedora 22 64 bit
+* Mac OS
 
-Follow the steps appropriate for your development system's :abbr:`OS (Operating System)`.
+Follow the steps appropriate for your development system's
-Where needed, alternative instructions are listed for Ubuntu and Fedora.
+:abbr:`OS (Operating System)`.
-Use these procedures to create a new development environment.
+
-Given that the file hierarchy may change from one release to another,
+Use these procedures to create a new development environment. Given that the
-these instructions might not work properly in an existing development environment.
+file hierarchy may change from one release to another, these instructions
+might not work properly in an existing development environment.
 
 Perform the steps in the installation procedures in the order they appear.
 
 .. toctree::
    :maxdepth: 2
 
-   installation.rst
+   installation_linux.rst
+   installation_mac.rst
    local_development.rst
    application.rst