unix-toolchain: Break individual OS setup docs into separate files.

A monolithic quickstart is too unwieldy at this point. Move the
initial setup instructions into their own files to make it less
daunting and easier to read.

Signed-off-by: Marti Bolivar <mbolivar@leaflabs.com>

1 files changed, 131 insertions, 0 deletions

diff --git a/source/unix-toolchain-osx-setup.rst b/source/unix-toolchain-osx-setup.rst
new file mode 100644
index 0000000..3ed78af
--- /dev/null
+++ b/source/unix-toolchain-osx-setup.rst
@@ -0,0 +1,131 @@
+.. highlight:: sh
+
+.. _unix-toolchain-osx-setup:
+
+Unix Toolchain OS X Setup
+=========================
+
+This page contains instructions for setting up an OS X computer for
+use with the :ref:`Unix toolchain <unix-toolchain>`.
+
+These instructions have been tested successfully on OS X 10.6.4 and
+10.8.1.
+
+.. contents:: Contents
+   :local:
+
+Collect and Install Tools
+-------------------------
+
+First, you'll need some tools. [#fpackman]_
+
+* `XCode <http://developer.apple.com/technologies/xcode.html>`_:
+  Provides compilers and other basic tools of the trade.  XCode was
+  once free of charge, but Apple has since begun charging for it. If
+  you'd rather not pay, you can probably get by with just a `make
+  <http://www.gnu.org/software/make/>`_ binary, but you're on your
+  own.
+
+* `Git`_: All of our code is tracked by a distributed versioning
+  system called Git. A `Mac installer
+  <http://code.google.com/p/git-osx-installer/downloads/list?can=3>`_
+  is available.
+
+* `dfu-util`_: A tool from `OpenMoko`_ that we use to upload programs
+  to the Maple over USB.
+
+  .. warning:: Due to firmware bugs in our :ref:`bootloader
+     <bootloader>`, you must use recent versions of ``dfu-util``, or
+     uploads will not work.  ``dfu-util`` versions 0.6 and greater
+     should work.
+
+  If you prefer to compile from source, OpenMoko provides instructions
+  for `building dfu-util on OS X
+  <http://wiki.openmoko.org/wiki/Dfu-util#Mac>`_.
+
+  If you're in a hurry, you can use the dfu-util binary bundled with
+  `OpenMoko Flasher
+  <http://www.handheld-linux.com/wiki.php?page=OpenMoko%20Flasher>`_. To
+  do this, first `download OpenMoko Flasher
+  <http://projects.goldelico.com/p/omflasher/downloads/>`_, then move
+  it to your :file:`/Applications` folder (or wherever you
+  like). Let's say you save it as :file:`/Applications/OpenMoko
+  Flasher.app`.  Then the ``dfu-util`` binary resides in
+
+      :file:`/Applications/OpenMoko Flasher.app/Contents/Mac OS/dfu-util`
+
+  To run it from the command line, make a symbolic link to the binary
+  from some place on your ``PATH``::
+
+      $ ln -s /Applications/OpenMoko\ Flasher.app/Contents/Mac\ OS/dfu-util \
+              /somewhere/on/your/PATH/dfu-util
+
+  .. note::
+
+    Copying the binary won't work, as it relies on dynamically linked
+    libraries found elsewhere in the .app bundle.
+
+  To make sure this worked, plug in your Maple, put it into
+  :ref:`perpetual bootloader mode
+  <troubleshooting-perpetual-bootloader>` (press RESET, then quickly
+  press and hold BUT for several seconds), and run ::
+
+      $ dfu-util -l
+
+  The output should look like this::
+
+      Found DFU: [0x1eaf:0x0003] devnum=0, cfg=0, intf=0, alt=0, name="DFU Program RAM 0x20000C00"
+      Found DFU: [0x1eaf:0x0003] devnum=0, cfg=0, intf=0, alt=1, name="DFU Program FLASH 0x08005000"
+
+* `PySerial`_: our reset script (which sends control signals over the
+  USB-serial connection to restart and enter the bootloader) is
+  written in Python, and requires the PySerial library. Download and
+  extract the `latest version
+  <http://pypi.python.org/pypi/pyserial>`_, then install with ::
+
+      $ cd /path/to/pyserial-x.y
+      $ python setup.py build
+      $ sudo python setup.py install
+
+  PySerial is also available via `easy_install`_, so if you're
+  comfortable using that, you could alternatively install it with ::
+
+      $ easy_install pyserial
+
+Fetch ``libmaple`` and Compiler Toolchain
+-----------------------------------------
+
+First, make a `Git`_ clone of :ref:`libmaple`::
+
+  $ cd ~
+  $ git clone git://github.com/leaflabs/libmaple.git
+
+Next, `download the cross-compilers
+<http://static.leaflabs.com/pub/codesourcery/gcc-arm-none-eabi-latest-osx32.tar.gz>`_
+you'll use to build libmaple and your own programs. (These are just
+special-purpose versions of :ref:`GCC <arm-gcc>`).
+
+Let's say you saved these into
+:file:`~/Downloads/gcc-arm-none-eabi-latest-osx32.tar.gz`. Then unpack
+the archive and tell the shell about its contents with::
+
+  $ cd ~/Downloads
+  $ tar -xvf gcc-arm-none-eabi-latest-osx32.tar.gz
+  $ mv arm ~/libmaple/arm
+  $ export PATH=$PATH:~/libmaple/arm/bin
+
+After that's done, update your shell startup script so
+:file:`~/libmaple/arm/bin` stays in your ``PATH``.
+
+So far, so good?
+----------------
+
+Great! Move on by :ref:`compiling a sample program <toolchain-test>`.
+
+.. rubric:: Footnotes
+
+.. [#fpackman] Some of these software packages might be available on
+   `MacPorts <http://www.macports.org/>`_ or `Homebrew
+   <http://mxcl.github.com/homebrew/>`_. The author had some bad
+   experiences with MacPorts a few years ago, though, and hasn't
+   touched a package manager on OS X since. Your mileage may vary.