Unix toolchain docs improvements.

Folded information in the README about the library Makefile target
into docs/source/unix-toolchain.rst.  Added a pointer to the JTAG
HOWTO page on the wiki.  Made some other miscellaneous cleanups,
updates and improvements.

1 files changed, 167 insertions, 139 deletions

diff --git a/source/unix-toolchain.rst b/source/unix-toolchain.rst
index d49b642..a173146 100644
--- a/source/unix-toolchain.rst
+++ b/source/unix-toolchain.rst
@@ -7,20 +7,21 @@
 ===========================
 
 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
+(``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.
 
 You'll need a Maple board, a Mini-B USB cable, a functional computer,
-and root 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
-`make <http://www.gnu.org/software/make/>`_ is recommended. For
-generic installation/setup issues, the :ref:`IDE installation
-<maple-ide-install>` and :ref:`troubleshooting` pages may be
-helpful. If all else fails, try our `forum`_, or `contact us
-directly`_\ !
+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.
+
+For generic installation and setup issues, see the :ref:`IDE
+installation <maple-ide-install>` and :ref:`troubleshooting` pages. If
+all else fails, try our `forum`_, or `contact us 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
@@ -54,36 +55,40 @@ First I'll give the commands to run, then explain::
   $ sudo aptitude install build-essential git-core wget screen dfu-util \
                           openocd python python-serial
 
-You'll want to install a bunch of developer "basics" like
-:command:`make`, :command:`tar`, etc.  A good catch-all for these
-tools is the "build-essential" meta-package on most Debian platforms:
-installing this fake package will pull in dozens of useful tools
-without bogging your system down too much. ``git-core`` is the name of
-the git package; `Git <http://git-scm.com/>`_ is a distributed code
-versioning system we use to track changes in our source
-code. :command:`wget` is a simple tool to download files over http
-from the command line, and is optional (you could pull in the required
-downloads using a browser). :command:`screen` is a really cool virtual
-terminal program; in the context of Maple, we use it to connect to
-serial port devices.
-
-:command:`dfu-util` is a tool from the `OpenMoko`_ project that we use
-to upload programs to the Maple over USB.
+You'll want to install a bunch of developer "basics" like ``make``,
+``tar``, etc.  A good catch-all for these tools is the
+``build-essential`` meta-package on most Debian platforms: installing
+this fake package will pull in dozens of useful tools without bogging
+your system down too much.
+
+`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. 
+
+``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).
+
+``screen`` is a screen manager; in the context of Maple, we use it to
+connect to serial port devices.
+
+``dfu-util`` is a tool from the `OpenMoko`_ project that we use to
+upload programs to the Maple over USB.
 
 .. _OpenMoko: http://openmoko.com/
 
-:command:`openocd` is a `JTAG
+``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). (optional)
+read out register status, etc). It's also optional.
 
 Lastly, 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 (the ``python-serial``
-package; this could also be installed with `easy_install
-<http://peak.telecommunity.com/DevCenter/EasyInstall>`_).
+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>`_.
 
 **2. Fetch libmaple and Compiler Toolchain** ::
 
@@ -100,10 +105,10 @@ 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 (bash 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.
+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.
 
 After you're done, you'll probably want to update your shell startup
 script so :file:`~/libmaple/arm/bin` stays in your ``PATH``.
@@ -118,12 +123,12 @@ From the libmaple directory, ::
   $ sudo cp support/scripts/45-maple.rules /etc/udev/rules.d/45-maple.rules
   $ sudo /etc/init.d/udev restart
 
-As a security precaution on linux, unknown USB devices can only be
-accessed by the superuser. This udev script identifies the Maple based
-on its vendor and product IDs, mounts it to :file:`/dev/maple`, and
-grants read/write permissions to the ``plugdev`` group. After
-restarting :command:`udev` you'll need to fully unplug or power cycle
-any Maples connected to the computer.
+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 grants
+read/write permissions to the ``plugdev`` group. After restarting
+``udev`` you'll need to fully unplug or power cycle any Maples
+connected to the computer.
 
 **So far, so good?**
 
@@ -140,38 +145,40 @@ 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 `Maple IDE
-<http://leaflabs.com/docs/maple-ide/>`_ to develop programs.
+<http://leaflabs.com/docs/maple-ide/>`_ to write programs.
 
 **1. Collect and Install Tools**
 
-You will need the following tools\ [#fmacports]_ to get started:
+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. It's a free download,
- but requires registration (gross, we know).
+ 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
+ distributed versioning system called Git. A `Mac installer
  <http://code.google.com/p/git-osx-installer/downloads/list?can=3>`_
  is available.
 
- 3. :command:`dfu-util`: A tool from `OpenMoko`_ that we use to upload
- programs to the Maple over USB. If you're feeling masochistic, there
- are instructions for `building dfu-util from source
+ 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>`_.
 
- However, if you've got better things to do, you can steal a dfu-util
- binary from a program called `Openmoko Flasher
+ 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 .app into your :file:`/Applications` folder (or wherever you
- like). Let's pretend you saved the .app to the directory
+ the OpenMoko application into your :file:`/Applications` folder (or
+ wherever you like). Let's pretend you saved the .app to the directory
 
    :file:`/Applications/OpenMoko Flasher.app`
 
- Then the :command:`dfu-util` binary resides in
+ Then the ``dfu-util`` binary resides in
 
    :file:`/Applications/OpenMoko Flasher.app/Contents/Mac OS/dfu-util`
 
@@ -188,8 +195,9 @@ You will need the following tools\ [#fmacports]_ to get started:
    .app, but you're on your own.
 
  To make sure this worked, try plugging in your Maple, making sure
- it's in bootloader mode (you can do this by pressing RESET, then
- quickly pressing BUT and holding it for several seconds), then
+ 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 ::
 
    $ dfu-util -l
@@ -212,8 +220,8 @@ You will need the following tools\ [#fmacports]_ to get started:
    $ python setup.py build
    $ sudo python setup.py install
 
- The package is also available via :command:`easy_install`, so if
- you're comfortable using that, you could also install it with ::
+ The package is also available via ``easy_install``, so if you're
+ comfortable using that, you could also install it with ::
 
    $ easy_install pyserial
 
@@ -288,20 +296,20 @@ Woo! It worked. The ``dec`` field at the end gives the total program
 size in bytes. The long listing of object files above the ``Final
 Size`` helps to identify bloated code.  As you write larger projects,
 you may find that they use too much space. If that happens, the
-file-by-file listing will help you track down the fatties porking up
-your program.
+file-by-file listing will help you track down the culprits.
 
 .. _toolchain-upload:
 
 Upload a program
 ----------------
 
-Ok, let's blow away the little example program and upload the
-interactive test session to your Maple.  This will let you interact
-textually with the Maple via USB-serial. If you're on Linux, then
-before executing :command:`make install`, you'll want to have the udev
-rules setup :ref:`as described above <toolchain-udev>`.  Plug in your Maple
-using the mini-b USB cable; then run ::
+Let's blow away the little example program and upload the interactive
+test session to your Maple.  This will let you interact with the Maple
+over a :ref:`USB serial port <usb>`. If you're on Linux, then before
+executing ``make install``, you'll want to have the udev rules setup
+:ref:`as described above <toolchain-udev>`.
+
+Plug in your Maple using the Mini-B USB cable; then run ::
 
   $ cd ~/libmaple
   $ cp examples/test-session.cpp main.cpp
@@ -312,91 +320,106 @@ using the mini-b USB cable; then run ::
 A number of things can go wrong at this stage.  Simple debugging steps
 include using :ref:`perpetual bootloader mode
 <troubleshooting-perpetual-bootloader>`, restarting the Maple a couple
-times, :command:`make clean`, etc. If nothing works, the `forum`_ is
-your friend.
+times, ``make clean``, etc. If nothing works, the `forum`_ is your
+friend.
 
 .. _toolchain-serialusb:
 
-Communicate over USB-serial interface
+Communicate over USB-Serial interface
 -------------------------------------
 
-Okay, now that we've flashed the interactive test session to the
-Maple, let's test it out. The device for the maple should look
-something like :file:`/dev/ttyACMXXX` on Linux or
-:file:`/dev/tty.usbmodemXXX` on OS X, but it might have a slightly
-different name on your system. To open up a session, run ::
+Now let's try out the interactive test session.  The serial port
+device file should look something like :file:`/dev/ttyACMXXX` on Linux
+or :file:`/dev/tty.usbmodemXXX` on OS X, but ``XXX`` will vary
+depending on your system.  Try using one of these to find out which it
+is::
+
+  # Linux
+  $ ls /dev/ttyACM*
+
+  # OS X
+  $ ls /dev/tty.usbmodem*
+
+To open up a session, run ::
 
   $ screen /dev/ttyXXX
 
-If the interactive test program built and uploaded correctly, you
-should be able to connect without any errors reported by
-:command:`screen`. Type ``h`` or hit the space bar to get a response;
-there are a number of commands which demonstrate Maple peripheral
-features. As of October 2010, the HardwareSerial library is blocking,
-so using any commands which would write to the USART Serial ports will
-cause the program to hang. To exit the screen session, type :kbd:`C-a
-C-\\` (control-a, followed by control-backslash) on Mac, or :kbd:`C-a
-k` (control-a k) on Linux, and type ``y`` when prompted if you're
-sure.
+If the interactive test program built and uploaded correctly,
+``screen`` won't report any errors, and will present you an empty
+terminal.  Your board is now waiting for you to send it a command.
+Type ``h`` to print a list of commands which demonstrate various
+features; type any command's letter to run it.
+
+To exit the screen session, type :kbd:`C-a C-\\` (control-a, followed
+by control-backslash) on Mac, or :kbd:`C-a k` (control-a k) on Linux,
+and type ``y`` when prompted if you're sure.
 
 .. note:: 
 
-   Using :command:`screen` in this way sometimes messes up your
-   terminal session on OS X.  If your shell starts acting up after you
-   exit screen, you should be able to fix it with ::
+   Using ``screen`` sometimes messes up your terminal session on OS X.
+   If your shell starts acting funny after you exit ``screen``, you
+   should be able to fix it with ::
 
        $ reset && clear
 
+   If that doesn't work, just close the Terminal window and open up a
+   new one.
+
 .. _toolchain-projects:
 
 Starting your own projects
 --------------------------
 
-.. TODO fix the build-targets.mk mess, note the "library" target
-
 So everything worked, and you want to start your own project? Great!
-It's easy. Just set the environment variable ``LIB_MAPLE_HOME`` in
-your shell startup script to point to the libmaple repository you
-cloned (this tutorial assumes you put it in :file:`~/libmaple`). For
-example, if you use bash as your shell, just put this line in your
-:file:`~/.bashrc` or :file:`~/.bash_profile`::
-
-  export LIB_MAPLE_HOME=~/libmaple
-
-Now, in order to start your own projects, just grab a copy of the
-:file:`Makefile` and skeleton :file:`main.cpp` we provided in the
-libmaple repository, and you're good to go::
-
-  $ cd
-  $ mkdir my-awesome-project
-  $ cp ~/libmaple/Makefile ~/libmaple/build-targets.mk my-awesome-project
-  $ cp ~/libmaple/main.cpp.example my-awesome-project/main.cpp
-
-(TEMPORARY: The file :file:`build-targets.mk` is where the rule to
-build the object file for :file:`main.cpp` lives. If you have multiple
-source files, you'll probably need to look at it and edit as
-appropriate. We're sorry about that and will update the Makefile
-structure later to remove this pain point.) Then hack away! You can
-:command:`make`, :command:`make clean`, and :command:`make install`
-from your new directory :file:`my-awesome-project` just like you did
-in the libmaple repository.
-
-.. note::
-
-  We update the libmaple repository fairly frequently with bugfixes
-  and other improvements.  In order get access to these in your local
-  copy of the repository, you should periodically update it with::
-
-    $ cd $LIB_MAPLE_HOME
-    $ git pull
-
-  The `commits page
-  <http://github.com/leaflabs/libmaple/commits/master>`_ for the
-  github repository is a good place to watch for bleeding-edge
-  updates; our `blog <http://leaflabs.com/blog/>`_ is the place to
-  watch for major releases.  We keep releases of libmaple and the
-  Maple IDE in lockstep, so any IDE updates will have corresponding
-  library updates.
+There are two ways to go about it.  
+
+If your project is small, all you have to do is replace
+:file:`~/libmaple/main.cpp` with your own code, and you're free to use
+``make`` and ``make install`` in the same way you did when you first
+:ref:`uploaded a program <toolchain-upload>`.
+
+If you have a more complicated project, with its own Makefile and
+multiple source files, or if you're using an IDE that creates its own
+Makefile, you'll probably want to load libmaple from an archive (a
+build-time library, not a DLL).
+
+To create an archive, use the ``library`` Makefile target::
+
+  $ cd ~/libmaple
+  $ make library
+
+This will produce a build-time library in the file
+:file:`~/libmaple/build/libmaple.a`.  To use it, make sure that you
+link against that library, and that the libmaple sources are in your
+include path.  
+
+At a minimum, your include path should contain the directories
+:file:`~/libmaple/libmaple` and :file:`~/libmaple/wirish/`.  If you
+want to use one of the officially supported :ref:`libraries
+<libraries>`, those live under :file:`~/libmaple/libraries/`.  The
+main include file for the Wirish library is
+:file:`~/libmaple/wirish/wirish.h`.
+
+Getting Updates
+---------------
+
+We update libmaple fairly frequently with bugfixes and other
+improvements.  In order get access to these in your local copy of
+the repository, you should periodically update it with::
+
+  $ cd ~/libmaple
+  $ git pull
+
+We keep releases of libmaple and the Maple IDE in lockstep, so any
+IDE updates will have corresponding library updates.  Our `blog
+<http://leaflabs.com/blog/>`_ is the place to watch for major
+releases; an `RSS feed <http://leaflabs.com/blog/feed/>`_ is
+available.
+
+You can sign up for a free `Github <https://github.com/plans>`_
+account and `watch libmaple
+<https://github.com/leaflabs/libmaple/watchers>`_ to receive
+notifications about bleeding-edge development.
 
 .. _toolchain-openocd:
 
@@ -405,20 +428,25 @@ Debug with OpenOCD
 
 TODO. For now see `this great guide
 <http://fun-tech.se/stm32/OpenOCD/index.php>`_ from fun-tech.se, and
-the ``jtag`` Makefile target.
+the ``jtag`` Makefile target.  There is also a `JTAG How-To
+<http://wiki.leaflabs.com/index.php?title=Maple_JTAG_How_To>`_ page on
+our `wiki <http://wiki.leaflabs.com>`_ which you may find useful.
 
 .. _toolchain-exuberantly:
 
 Go forth exuberantly!
 ---------------------
 
-Let us know what you come up with! Use #leaflabs on Twitter, post in
-the `forum`_, track us down in the real world, whatever. We love
-projects!
+Let us know what you come up with! Use #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!
 
 .. rubric:: Footnotes
 
-.. [#fmacports] Some of these software packages might be available on
-   `MacPorts <http://www.macports.org/>`_. The author had some bad
+.. [#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 it since. Of course, your mileage may vary.
+   touched a package manager on OS X since. Of course, your mileage
+   may vary.