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>

source/contents.rst

@@ -14,6 +14,9 @@ Contents in Full
    maple-ide-install
    ide
    unix-toolchain
+   unix-toolchain-linux-setup
+   unix-toolchain-osx-setup
+   unix-toolchain-win-setup
    whats-new
 
 .. _index-maple-programming:

source/epilog.rst

@@ -6,3 +6,9 @@
 .. _forum: http://forums.leaflabs.com
 .. _contact: http://leaflabs.com/contact/
 .. _contact us directly: http://leaflabs.com/contact/
+.. _Python: http://python.org/download/
+.. _PySerial: http://pyserial.sourceforge.net/
+.. _OpenMoko: http://openmoko.com/
+.. _Git: http://git-scm.com/
+.. _dfu-util: http://wiki.openmoko.org/wiki/Dfu-util
+.. _easy_install: http://packages.python.org/distribute/easy_install.html

source/unix-toolchain-linux-setup.rst

@@ -0,0 +1,186 @@
+.. highlight:: sh
+
+.. _unix-toolchain-linux-setup:
+
+Unix Toolchain Linux Setup
+==========================
+
+This page contains instructions for setting up a Linux computer for
+use with the :ref:`Unix toolchain <unix-toolchain>`.
+
+These instructions have been tested successfully on:
+
+- Ubuntu 10.04 and 12.04 (32- and 64-bit)
+- Fedora 17 (64-bit)
+
+Generic instructions for other distributions are also provided. Please
+`contact`_ us with any updates for distros not already covered!
+
+.. contents:: Contents
+   :local:
+
+Collect and Install Tools
+-------------------------
+
+First, you'll need some tools.
+
+.. 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.
+
+**Debian-based distributions (Debian, Ubuntu, Mint, etc.)**:
+
+  Install mandatory and optional tools with ::
+
+    $ sudo apt-get install build-essential git-core screen dfu-util python python-serial
+
+  On *64-bit distros only*, you will also need to install some 32-bit
+  libraries needed by the LeafLabs-supported :ref:`ARM GCC toolchain
+  <arm-gcc>` with ::
+
+    # 64-bit systems only!
+    $ sudo apt-get install ia32-libs
+
+  You may also need to remove `brltty <http://mielke.cc/brltty/>`_
+  with ::
+
+    # Optional
+    $ sudo apt-get remove brltty
+
+  Brltty provides braille access to the console.  It has been reported
+  to cause conflicts with Maple.
+
+**Red Hat-based distributions (RHEL, Fedora, Centos, etc.)**:
+
+  Install mandatory and optional tools with ::
+
+    $ sudo yum install screen git python pyserial dfu-util make
+
+  On *64-bit distros only*, you will also need to install 32-bit
+  libraries needed by the LeafLabs-supported :ref:`ARM GCC toolchain
+  <arm-gcc>` with ::
+
+    # 64-bit systems only!
+    $ sudo yum install glibc.i686
+
+  You may also need to remove `brltty <http://mielke.cc/brltty/>`_
+  with one of these::
+
+    # Optional, 64-bit systems:
+    $ sudo yum erase brltty.x86_64
+
+    # Optional, 32-bit systems:
+    $ sudo yum erase brltty.i686
+
+  Brltty provides braille access to the console.  It has been
+  reported to cause conflicts with Maple.
+
+**Other Linux distributions**:
+
+  On other distributions, you'll need to figure this out for yourself
+  (please `contact`_ us if you have instructions for distros not
+  covered here!).
+
+  Mandatory tools:
+
+  * `Git`_ is a distributed version control system. We use it to track
+    our source code.
+
+  * `dfu-util`_ is a tool from the `OpenMoko`_ project. It is used to
+    upload programs to the Maple over USB.
+
+  * `Make <http://www.gnu.org/software/make/>`_ is used to direct
+    compilation.
+
+  * `Python`_ is a programming language. Our reset script, which sends
+    control signals to the board which cause it to to reset and enter
+    the :ref:`bootloader <bootloader>`, is written in Python (and
+    works with Python 2 or 3). Most Linux distributions these days
+    include Python by default.
+
+  * `PySerial`_ is a Python library for interacting with serial port
+    devices. It's needed by our reset script. PySerial can also be
+    installed with `easy_install`_.
+
+  Optional tools:
+
+  * `screen <http://www.gnu.org/s/screen/>`_ is a screen manager used
+    here to connect to serial port devices.  (Some popular
+    alternatives are `Minicom
+    <http://alioth.debian.org/projects/minicom/>`_ and `Kermit
+    <http://www.kermitproject.org/>`_).
+
+Fetch ``libmaple`` and Compiler Toolchain
+-----------------------------------------
+
+First, make a Git clone of :ref:`libmaple`::
+
+  $ cd ~
+  $ git clone git://github.com/leaflabs/libmaple.git libmaple
+
+Next, download the `Linux ARM GCC toolchain
+<http://static.leaflabs.com/pub/codesourcery/gcc-arm-none-eabi-latest-linux32.tar.gz>`_
+you'll use to build your programs. Extract the archive into a
+directory named :file:`arm`. Put the resulting :file:`arm/bin`
+subdirectory somewhere in your ``PATH``. For example, if you have
+`wget <http://www.gnu.org/software/wget/>`_ installed, you can run::
+
+  $ cd ~/libmaple
+  $ wget http://static.leaflabs.com/pub/codesourcery/gcc-arm-none-eabi-latest-linux32.tar.gz
+  $ tar xvf gcc-arm-none-eabi-latest-linux32.tar.gz
+  $ export PATH=$PATH:~/libmaple/arm/bin
+
+You can check that this worked by entering ``arm-none-`` and hitting
+tab to auto-complete; your shell should show a bunch of results. After
+you're done, you'll probably want to update your shell startup script
+so the :file:`arm/bin` directory stays in your ``PATH``.
+
+.. _toolchain-udev:
+
+Install udev Rules
+------------------
+
+From the libmaple directory, copy our udev rules [#fudev]_ to
+``/etc/udev/rules.d``::
+
+  $ sudo cp support/scripts/45-maple.rules /etc/udev/rules.d/45-maple.rules
+
+Then restart udev.
+
+**Debian-based distros**:
+
+  Make sure you are in the plugdev group (e.g. by running ``$ groups``
+  and seeing if the output includes "plugdev").  If not, add yourself
+  to plugdev with ::
+
+    $ sudo usermod -a -G plugdev $USER
+
+  then log back out and log back in.
+
+  After that's done, restart udev::
+
+    $ sudo restart udev
+
+**Red Hat-based distros**:
+
+  ::
+
+    $ udevadm control --reload-rules
+
+After restarting ``udev``, you'll need to unplug and re-plug your
+Maple.
+
+So far, so good?
+----------------
+
+Great! Move on by :ref:`compiling a sample program <toolchain-test>`.
+
+.. rubric:: Footnotes
+
+.. [#fudev] As a security precaution on Linux, unknown USB devices can
+   only be accessed by root. This udev script identifies the Maple
+   based on its vendor and product IDs, mounts it to
+   :file:`/dev/maple`, and (for Debian-based distros) grants
+   read/write permissions to the ``plugdev`` group.
+

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.