[WIP] Overhaul Unix toolchain quickstart.

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

5 files changed, 246 insertions, 143 deletions

diff --git a/source/_static/img/winxp-bashrc-notepad.png b/source/_static/img/winxp-bashrc-notepad.png
new file mode 100644
index 0000000..9395f2d
--- /dev/null
+++ b/source/_static/img/winxp-bashrc-notepad.png
diff --git a/source/_static/img/winxp-git-bash-screenshot.png b/source/_static/img/winxp-git-bash-screenshot.png
new file mode 100644
index 0000000..24d4a7a
--- /dev/null
+++ b/source/_static/img/winxp-git-bash-screenshot.png
diff --git a/source/_static/img/winxp-open-bashrc-with.png b/source/_static/img/winxp-open-bashrc-with.png
new file mode 100644
index 0000000..18b157f
--- /dev/null
+++ b/source/_static/img/winxp-open-bashrc-with.png
diff --git a/source/maple-ide-install.rst b/source/maple-ide-install.rst
index 4924bbb..371103d 100644
--- a/source/maple-ide-install.rst
+++ b/source/maple-ide-install.rst
@@ -67,6 +67,8 @@ First, extract all the files in the ZIP file to a suitable location on
 your system (like your Desktop folder).  Next, you have to install
 some drivers.  Sorry!
 
+.. _maple-ide-install-windows-drivers:
+
 .. note:: Note that while these instructions work on Windows XP,
    changes in Windows 7 mean that you won't be able to install the IDE
    without disabling driver signing on your computer.  We're working
diff --git a/source/unix-toolchain.rst b/source/unix-toolchain.rst
index 751ec18..a397cc1 100644
--- a/source/unix-toolchain.rst
+++ b/source/unix-toolchain.rst
@@ -6,22 +6,14 @@
  Unix Toolchain Quickstart
 ===========================
 
-This is a tutorial for using the Maple with a standard Unix toolchain
-(``make``, ``gcc``, etc.).  It's not necessary to do this in order to
-program the Maple; you can always :ref:`install the Maple IDE
-<maple-ide-install>` instead.  This document is intended for users who
-are comfortable using C or C++ and would like to use :ref:`libmaple`
-directly.
-
-We currently have instructions for 32- and 64-bit Linux and OS X Snow
-Leopard. If you're on another Unix platform, Windows, or an earlier
-version of OS X, we imagine you can translate/port these directions on
-your own. You might want to begin with these `stripped down
-distributions <http://static.leaflabs.com/pub/codesourcery/>`_ of the
-`CodeSourcery GCC compiler tools
-<http://www.codesourcery.com/sgpp/features.html>`_ (including Win32
-versions). If you do have success on other platforms, please post in
-the forums, so we can fold your tips into this document!
+This is a tutorial for using a standard Unix toolchain (``make``,
+``gcc``, etc.) with Maple.  It's intended for C and C++ programmers
+who want to use :ref:`libmaple` directly. If you're just beginning, we
+recommend installing :ref:`Maple IDE <maple-ide-install>` instead.
+
+If you have success on an operating system not covered here, please
+post in the `forum`_ (or email us at info@leaflabs.com), so we can
+update this document.
 
 .. contents:: Contents
    :local:
@@ -29,68 +21,83 @@ the forums, so we can fold your tips into this document!
 Requirements
 ------------
 
-You'll need a Maple board, a Mini-B USB cable, a functional computer,
-and root (or Administrator) access to that computer. This guide
-assumes you've had success with the IDE on your machine and that you
-are fairly comfortable with the Unix command line.  Some previous
-experience with editing your shell startup script (.bashrc, .tcshrc,
-etc.) and using `GCC <http://gcc.gnu.org/>`_ and `make
-<http://www.gnu.org/software/make/>`_ is recommended.
+You need a Maple board, a Mini-B USB cable, and root (or
+Administrator) access to your computer. We assume you've had success
+with the IDE on your machine (this is important on Windows, as this
+document doesn't cover :ref:`driver installation
+<maple-ide-install-windows-drivers>`).
 
-.. _toolchain-linux-setup:
+On Linux and OS X, some previous experience with editing your shell
+startup script (.bashrc, .tcshrc, etc.) and using `GCC
+<http://gcc.gnu.org/>`_ and `make
+<http://www.gnu.org/software/make/>`_ is recommended. (The Windows
+instructions are more detailed, since we assume most Windows users
+will be new to the Unix shell).
 
 Setup
 -----
 
+.. _toolchain-linux-setup:
+
 Linux
 ^^^^^
 
-These instructions are oriented towards Linux users using
-contemporary, 32-bit Debian- or Red Hat-based distributions.  If you
-use another Linux operating system and you have any tips to offer,
-please us at info@leaflabs.com or post in the `forum`_. Thanks!
-
 **1. Collect and Install Tools**
 
 First, you'll need some tools.
 
-On Debian-based distributions (including Ubuntu, etc.), do this with::
+On Debian-based distributions (including Ubuntu)::
 
   $ sudo aptitude install build-essential git-core wget screen dfu-util \
                           openocd python python-serial
 
-On Red Hat-based distributions (Fedora, etc.), do this with::
+On Red Hat-based distributions (including Fedora)::
 
   $ yum install screen wget git python pyserial dfu-util openocd make
 
-`Git <http://git-scm.com/>`_ is a distributed code versioning system
-we use to track changes in our source code; ``git-core`` is the
-corresponding package.
+On other distributions, you'll need to figure this out for yourself
+(let us know if you do!).
 
-``wget`` is a simple tool to download files over http from the command
-line; installing it is optional (you could pull in the required
-downloads using a browser).
+The following are **mandatory**:
 
-``screen`` is a screen manager; in the context of Maple, we use it to
-connect to serial port devices.
+* `Git <http://git-scm.com/>`_ is a distributed version control
+  system. We use it to track our source code.
 
-``dfu-util`` is a tool from the `OpenMoko`_ project that we use to
-upload programs to the Maple over USB.
+* `dfu-util <http://wiki.openmoko.org/wiki/Dfu-util>`_ is a tool from
+  the `OpenMoko`_ project. It is used to upload programs to the Maple
+  over USB.
 
-.. _OpenMoko: http://openmoko.com/
+* `make <http://www.gnu.org/software/make/>`_ is used to direct
+  compilation.
+
+* `Python <http://python.org>`_ 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. (Most Linux distributions these days include Python by
+  default).
 
-``openocd`` is a `JTAG
-<http://en.wikipedia.org/wiki/Joint_Test_Action_Group>`_ control
-program used in conjunction with an ARM JTAG device to do in circuit
-debugging (pause/resume program execution, upload and download code,
-read out register status, etc). It's also optional.
+* `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
+  <http://peak.telecommunity.com/DevCenter/EasyInstall>`_.
 
-Lastly, our reset script (which sends control signals over the
-USB-serial connection to restart and enter the bootloader) is written
-in `Python <http://python.org>`_, and requires the `PySerial
-<http://pyserial.sourceforge.net/>`_ library available in the
-``python-serial`` package.  This can also be installed with
-`easy_install <http://peak.telecommunity.com/DevCenter/EasyInstall>`_.
+The following are **optional**:
+
+* `wget <http://www.gnu.org/s/wget/>`_ is a tool for downloading files
+  from the command line. You could also pull in the required downloads
+  using a web browser.
+
+* `screen <http://www.gnu.org/s/screen/>`_ is a screen manager we use
+  to connect to serial port devices.  Some popular alternatives are
+  Minicom and Kermit.
+
+* `openocd <http://openocd.sourceforge.net/web/>`_ is a `JTAG
+  <http://en.wikipedia.org/wiki/Joint_Test_Action_Group>`_ control
+  program. It is used with an ARM JTAG device to do in-circuit
+  debugging (uploading new code, connecting to `GDB
+  <http://www.gnu.org/s/gdb/>`_, etc.).
+
+.. _OpenMoko: http://openmoko.com/
 
 **2. Fetch libmaple and Compiler Toolchain** ::
 
@@ -101,16 +108,15 @@ in `Python <http://python.org>`_, and requires the `PySerial
   $ tar xvzf gcc-arm-none-eabi-latest-linux32.tar.gz
   $ export PATH=$PATH:~/libmaple/arm/bin # or wherever these tools ended up
 
-This step is fairly straightforward: do a git clone of the `libmaple
-repository <https://github.com/leaflabs/libmaple>`_ to some directory,
-then download and extract the ARM compiler toolchain.
+In this step, you make a Git clone of the `libmaple repository
+<https://github.com/leaflabs/libmaple>`_, then download and extract
+the ARM compiler toolchain.
 
-The :file:`arm/bin/` directory will need to be added to ``PATH``; you
-can check that this worked by entering ``arm-none-`` and hitting tab
-to auto-complete (your shell should show a bunch of results).
+The directory :file:`arm/bin/` will need to be added to your ``PATH``;
+you can check that this worked by entering ``arm-none-`` and hitting
+tab to auto-complete (your shell should show a bunch of results).
 Regardless of where you put the toolchain, make sure to preserve its
-internal directory layout, as the binaries make relative path calls
-and references.
+internal directory layout.
 
 After you're done, you'll probably want to update your shell startup
 script so :file:`~/libmaple/arm/bin` stays in your ``PATH``.
@@ -149,108 +155,96 @@ Great! Test your setup by :ref:`compiling a sample program
 OS X
 ^^^^
 
-These instructions have been tested successfully on OS X 10.6.4. As
-stated previously, this document assumes a general level of Unix
-aptitude on the part of the reader; if you're uncomfortable using
-Terminal (or if you don't know what that means), then you should
-probably stick with using the :ref:`Maple IDE <ide>` to write
-programs.
+These instructions have been tested successfully on OS X 10.6.4.
 
 **1. Collect and Install Tools**
 
 You will need the following tools\ [#fpackman]_ to get started:
 
- 1. `XCode <http://developer.apple.com/technologies/xcode.html>`_: If
- you're reading this, you've probably already got this. Provides
- compilers and other basic tools of the trade.  While XCode was once
- free of charge, 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.
-
- 2. `Git <http://git-scm.com/>`_: 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.
+* `XCode <http://developer.apple.com/technologies/xcode.html>`_: If
+  you're reading this, you've probably already got this. Provides
+  compilers and other basic tools of the trade.  While XCode was once
+  free of charge, 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.
 
- 3. ``dfu-util``: A tool from `OpenMoko`_ that we use to upload
- programs to the Maple over USB.  If you prefer to compile from
- source, OpenMoko provides instructions for `building dfu-util
- <http://wiki.openmoko.org/wiki/Dfu-util#Mac>`_.
+* `Git <http://git-scm.com/>`_: 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.
 
- If you're in a hurry, you can steal a dfu-util binary from a program
- called `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 copy
- the OpenMoko application into your :file:`/Applications` folder (or
- wherever you like). Let's pretend you saved the .app to the directory
+* `dfu-util <http://wiki.openmoko.org/wiki/Dfu-util>`_: A tool from
+  `OpenMoko`_ that we use to upload programs to the Maple over USB.
 
-   :file:`/Applications/OpenMoko Flasher.app`
+  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>`_.
 
- Then the ``dfu-util`` binary resides in
+  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`
+      :file:`/Applications/OpenMoko Flasher.app/Contents/Mac OS/dfu-util`
 
- To get access to it from the command line, just make a symbolic link
- to the binary from some place on your ``PATH``::
+  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
+      $ ln -s /Applications/OpenMoko\ Flasher.app/Contents/Mac\ OS/dfu-util \
+              /somewhere/on/your/PATH/dfu-util
 
- .. note::
-   Just copying the binary somewhere doesn't work, as it relies on
-   dynamically linked libraries found elsewhere in the .app
-   bundle. It's possible to pull just the relevant pieces out of the
-   .app, but you're on your own.
+  .. note::
 
- To make sure this worked, try plugging in your Maple, making sure
- it's in :ref:`perpetual bootloader mode
- <troubleshooting-perpetual-bootloader>` (do this by pressing RESET,
- then quickly pressing BUT and holding it for several seconds), then
- running ::
+    Copying the binary won't work, as it relies on dynamically linked
+    libraries found elsewhere in the .app bundle.
 
-   $ dfu-util -l
+  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 ::
 
- If you see some lines that look like ::
+      $ dfu-util -l
 
-   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"
+  The output should look like this::
 
- then you're all set.
+      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"
 
- 4. 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
- <http://pyserial.sourceforge.net/>`_ library. Download the `latest
- version <http://pypi.python.org/pypi/pyserial>`_. After you download
- and untar, install it with ::
+* `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
+  untar 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
+      $ cd /path/to/pyserial-x.y
+      $ python setup.py build
+      $ sudo python setup.py install
 
- The package is also available via ``easy_install``, so if you're
- comfortable using that, you could also install it with ::
+  PySerial is also available via ``easy_install``, so if you're
+  comfortable using that, you could alternatively install it with ::
 
-   $ easy_install pyserial
+      $ easy_install pyserial
 
 **2. Fetch libmaple and Compiler Toolchain**
 
 You first need to clone libmaple::
 
   $ cd ~
-  $ git clone git://github.com/leaflabs/libmaple.git libmaple
+  $ git clone git://github.com/leaflabs/libmaple.git
 
-Then you need to get the cross-compilers we use to build a
-project. These are just modified versions of GCC; you can `download
-them for OS X here
-<http://static.leaflabs.com/pub/codesourcery/gcc-arm-none-eabi-latest-osx32.tar.gz>`_. Let's
-say you saved this file to
+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 GCC). Let's say you saved these as
 
   :file:`~/Downloads/gcc-blah-blah-osx32.tar.gz`
 
-You can then unpack the archive and let OS X know where the compilers
-live with ::
+You can unpack the archive and let the shell know where everything
+lives with ::
 
   $ cd ~/Downloads
   $ tar -xvzf gcc-blah-blah-osx32.tar.gz
@@ -262,7 +256,111 @@ script so :file:`~/libmaple/arm/bin` stays in your ``PATH``.
 
 **So far, so good?**
 
-Great! Go on to the next section, where you test everything out.
+Great! Test your setup by :ref:`compiling a sample program
+<toolchain-test>`.
+
+.. _toolchain-win-setup:
+
+Windows
+^^^^^^^
+
+These instructions have been tested successfully on Windows XP SP3.
+
+1. First, you'll need Git, a distributed versioning system we use to
+track our source code. Follow the steps in `this great guide from
+GitHub <http://help.github.com/win-set-up-git/>`_.
+
+2. `Install Python <http://python.org/download>`_.  Choose the latest
+**2.7.x version**; Python 3 will not work.
+
+3. `Install PySerial <http://pypi.python.org/pypi/pyserial>`_.  Choose
+the latest **pyserial-x.y-win32.exe version**; the "py3k" version will
+not work.
+
+4. Run Git Bash, and get :ref:`libmaple` by typing the following line
+and hitting return. (Do not type the "$".  We put these in to remind
+you that lines like this are for the Git Bash prompt). ::
+
+    $ git clone git://github.com/leaflabs/libmaple.git
+
+.. note:: Keep the Git Bash window open as you go.
+
+You now have the libmaple repository in the folder ``Documents and
+Settings\<Your Name>``.
+
+5. Download this `archive of the CodeSourcery compiler toolchain
+<http://static.leaflabs.com/pub/codesourcery/gcc-arm-none-eabi-latest-win32.tar.gz>`_.
+When the download finishes, move the file into the libmaple directory.
+
+6. Type these two lines into the Git Bash prompt to go to the libmaple
+folder and extract the archive::
+
+    $ cd libmaple
+    $ tar xzf gcc-arm-none-eabi-latest-win32.tar.gz
+
+This will create a folder named "arm" inside the libmaple folder.
+
+7. Now you'll configure your system to use these tools. Type the
+following lines into the Git Bash prompt.
+
+.. warning:: If you've installed Bash on your computer before starting
+   this guide, and have a ~/.bashrc already, these instructions will
+   overwrite it. If that is the case, we assume you know what you're
+   doing, and can modify the shell commands in this step appropriately
+   for your system.
+
+   If you're using Bash for the first time, don't worry about this
+   warning.
+
+::
+
+    $ cat >~/.bashrc <<EOF
+    > export PATH=\$PATH:~/libmaple/arm/bin/
+    > EOF
+
+.. note:: The "> " at the beginning of the second and third lines will
+   appear automatically.
+
+In case that's hard to read, the part of the first line between
+``cat`` and ``bashrc`` is these five characters: space ( ), right
+angle bracket (>), tilde (~), forward slash (/), and period (.).
+
+For reference, here's a screenshot of what your Git Bash window should
+look like at this point (the output after the ``git clone`` line will
+be slightly different):
+
+.. _toolchain-git-bash-screenshot:
+
+.. figure:: /_static/img/winxp-git-bash-screenshot.png
+   :align: center
+   :alt: Git Bash screenshot
+
+8. Let's check that you completed the previous step correctly.  If you
+did, there should be a file called ".bashrc" (the period is supposed
+to be there) in the folder ``Documents and Settings\<Your Name>\``.
+Open this file in Notepad by right clicking on it and selecting "Open
+With...", like so:
+
+.. figure:: /_static/img/winxp-open-bashrc-with.png
+   :align: center
+   :alt: Open .bashrc With
+
+Choose "Notepad" from the resulting pop-up window, and click "OK".
+The Notepad window should look like this:
+
+.. figure:: /_static/img/winxp-bashrc-notepad.png
+   :align: center
+   :alt: .bashrc in Notepad
+
+The little box at the end of the line is supposed to be there. Close
+the Notepad window (do not save any changes you may have made by
+accident).
+
+9. TODO download dfu-util.exe and put it in ``libmaple\arm\bin``.
+
+**So far, so good?**
+
+Great! Go on to the next section, where you'll compile a program.
 
 .. _toolchain-test:
 
@@ -270,8 +368,9 @@ Test compilation
 ----------------
 
 Get back into the libmaple directory (this tutorial assumes you put it
-in :file:`~/libmaple`) and test that you've installed all the compilation
-tools correctly::
+in :file:`~/libmaple`) and test that you've installed all the
+compilation tools correctly (Windows users: use ``cs-make`` instead of
+``make``)::
 
   $ cd ~/libmaple
   $ cp main.cpp.example main.cpp
@@ -281,7 +380,7 @@ tools correctly::
 .. note:: These instructions are for the Maple.  If you're compiling
    for another board, you'll need to set a ``BOARD`` environment
    variable appropriately.  For example, to compile for Maple Mini (in
-   the bash shell), ::
+   Bash), ::
 
        $ export BOARD=maple_mini
        $ make
@@ -350,8 +449,8 @@ friend.
 
 .. _toolchain-serialusb:
 
-Communicate over USB-Serial interface
--------------------------------------
+Communicate over USB-Serial
+---------------------------
 
 Now let's try out the interactive test session.  The serial port
 device file should look something like :file:`/dev/ttyACMXXX` on Linux
@@ -392,8 +491,8 @@ and type ``y`` when prompted if you're sure.
 
 .. _toolchain-projects:
 
-Starting your own projects
---------------------------
+Start your own project
+----------------------
 
 So everything worked, and you want to start your own project? Great!
 There are two ways to go about it.
@@ -425,8 +524,8 @@ want to use one of the officially supported :ref:`libraries
 main include file for the Wirish library is
 :file:`~/libmaple/wirish/wirish.h`.
 
-Getting Updates
----------------
+Get updates
+-----------
 
 We update libmaple fairly frequently with bugfixes and other
 improvements.  In order get access to these in your local copy of
@@ -462,11 +561,13 @@ our `wiki <http://wiki.leaflabs.com>`_ which you may find useful.
 Go forth exuberantly!
 ---------------------
 
-Let us know what you come up with! Use #leaflabs on `Twitter
-<http://twitter.com/leaflabs>`_, post in the `forum`_, join the the
+Let us know what you come up with! Mention `@leaflabs on Twitter
+<http://twitter.com/#!/leaflabs>`_, post in the `forum`_, join the the
 #leafblowers IRC channel on `freenode
 <http://freenode.net/irc_servers.shtml>`_, whatever. We love projects!
 
+.. _PySerial: http://pyserial.sourceforge.net/
+
 .. rubric:: Footnotes
 
 .. [#fpackman] Some of these software packages might be available on