aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMarti Bolivar <mbolivar@lozenge.(none)>2012-07-13 02:45:23 -0400
committerMarti Bolivar <mbolivar@leaflabs.com>2012-07-13 03:29:12 -0400
commit438dfb991fb1e7d9dba37449dd618ada2368aee2 (patch)
treee071be7bf093ad6a685d2ae482e7fb3a4b2a8c2e
parent3663a1e9c9ca94529d96a80622da508aba065bd5 (diff)
downloadlibrambutan-438dfb991fb1e7d9dba37449dd618ada2368aee2.tar.gz
librambutan-438dfb991fb1e7d9dba37449dd618ada2368aee2.zip
Finish redoing the Unix toolchain.
General: - Beef up "Start your own project" section, mention the example libmaple project page on the wiki. - Tune the "Get updates" page to encourage people to run libmaple master. - Fix the stupid JTAG section to acknowledge the fact that we don't officially support it. Mention the JTAG how-to on the wiki. Linux: - Better visual distinction for which instructions belong to which distributions. - Fixed instructions for 64-bit distributions. - Clean up libmaple/arm-none-eabi-* instructions and udev rules. OS X: - Minor language tweaks. Windows: - Mention (new at time of writing) libmaple script support/scripts/win-list-com-ports.py, which lists available serial ports. - Audit other sections for missing Windows-specific instructions, and add them. Signed-off-by: Marti Bolivar <mbolivar@leaflabs.com>
-rw-r--r--source/unix-toolchain.rst480
1 files changed, 280 insertions, 200 deletions
diff --git a/source/unix-toolchain.rst b/source/unix-toolchain.rst
index 4fc21ea..e3d2a30 100644
--- a/source/unix-toolchain.rst
+++ b/source/unix-toolchain.rst
@@ -17,6 +17,7 @@ update this document.
.. contents:: Contents
:local:
+ :depth: 2
Requirements
------------
@@ -27,12 +28,13 @@ 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>`).
-On Linux and OS X, some previous experience with editing your shell
-startup script (.bashrc, .tcshrc, etc.) and using `GCC
+On Linux and OS X, you need to know how to use a shell and edit your
+shell startup script (.bashrc, .tcshrc, etc.). (The Windows
+instructions are more detailed, since we assume many Windows users
+will be newer to the Unix shell). Some experience 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).
+<http://www.gnu.org/software/make/>`_ is recommended, but is not
+required.
Setup
-----
@@ -42,117 +44,156 @@ Setup
Linux
^^^^^
-**1. Collect and Install Tools**
+1. Collect and Install Tools
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
First, you'll need some tools.
-On Debian-based distributions (including Ubuntu)::
+.. 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.
- $ sudo aptitude install build-essential git-core wget screen dfu-util \
- openocd python python-serial
+**Debian-based distributions (Debian, Ubuntu, Mint, etc.)**:
-On Red Hat-based distributions (including Fedora)::
+ Install mandatory and optional tools with ::
- $ yum install screen wget git python pyserial dfu-util openocd make
+ $ sudo apt-get install build-essential git-core screen dfu-util python python-serial
-On other distributions, you'll need to figure this out for yourself
-(let us know if you do!).
+ 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 ::
-The following are **mandatory**:
+ # 64-bit systems only!
+ $ sudo apt-get install ia32-libs
-* `Git <http://git-scm.com/>`_ is a distributed version control
- system. We use it to track our source code.
+ You may also need to remove `brltty <http://mielke.cc/brltty/>`_
+ with ::
-* `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.
+ # Optional
+ $ sudo apt-get remove brltty
-.. 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.
+ Brltty provides braille access to the console. It has been reported
+ to cause conflicts with Maple.
-.. _OpenMoko: http://openmoko.com/
+**Red Hat-based distributions (RHEL, Fedora, Centos, etc.)**:
-* `make <http://www.gnu.org/software/make/>`_ is used to direct
- compilation.
+ Install mandatory and optional tools with ::
-* `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 (and works with Python 2 or 3). Most Linux distributions
- these days include Python by default.
+ $ sudo yum install screen git python pyserial dfu-util make
-* `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>`_.
+ 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 ::
-The following are **optional**:
+ # 64-bit systems only!
+ $ sudo yum install glibc.i686
-* `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.
+ You may also need to remove `brltty <http://mielke.cc/brltty/>`_
+ with one of these::
-* `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.
+ # Optional, 64-bit systems:
+ $ sudo yum erase brltty.x86_64
-* `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.).
+ # Optional, 32-bit systems:
+ $ sudo yum erase brltty.i686
-.. _OpenMoko: http://openmoko.com/
+ Brltty provides braille access to the console. It has been
+ reported to cause conflicts with Maple.
+
+**Other Linux distributions**:
-**2. Fetch libmaple and Compiler Toolchain** ::
+ 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 <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 (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
+ <http://peak.telecommunity.com/DevCenter/EasyInstall>`_.
+
+ 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/>`_).
+
+2. Fetch ``libmaple`` and Compiler Toolchain
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+First, make a Git clone of :ref:`libmaple`::
$ cd ~
$ git clone git://github.com/leaflabs/libmaple.git libmaple
- $ cd libmaple
- $ wget http://static.leaflabs.com/pub/codesourcery/gcc-arm-none-eabi-latest-linux32.tar.gz
- $ tar xvzf gcc-arm-none-eabi-latest-linux32.tar.gz
- $ export PATH=$PATH:~/libmaple/arm/bin # or wherever these tools ended up
-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.
+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 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::
-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.
+ $ 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
-After you're done, you'll probably want to update your shell startup
-script so :file:`~/libmaple/arm/bin` stays in 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. 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:
-**3. Install udev Rules**
+3. Install udev Rules
+~~~~~~~~~~~~~~~~~~~~~
-From the libmaple directory, copy our udev rules to ``/etc/udev/rules.d``::
+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
-On Debian, run ``$ groups``. Make sure the output includes "plugdev".
-If not, add yourself to that group. Then run ::
+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 it (e.g. ``$ sudo usermod -a -G plugdev <your-username>``, then
+ log out and log back in). Then run::
+
+ $ sudo restart udev
- $ sudo restart udev
+**Red Hat-based distros**:
-On Red Hat, run ::
+ ::
- $ udevadm control --reload-rules
+ $ udevadm control --reload-rules
-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 (on
-Debian-based distros) 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.
+After restarting ``udev``, you'll need to unplug and re-plug your
+Maple.
-**So far, so good?**
+So far, so good?
+~~~~~~~~~~~~~~~~
Great! Test your setup by :ref:`compiling a sample program
<toolchain-test>`.
@@ -164,24 +205,25 @@ OS X
These instructions have been tested successfully on OS X 10.6.4.
-**1. Collect and Install Tools**
+1. Collect and Install Tools
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-You will need the following tools\ [#fpackman]_ to get started:
+First, you'll need some tools. [#fpackman]_
-* `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.
+* `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 <http://git-scm.com/>`_: All of our code is tracked by a
- distributed versioning system called Git. A `Mac installer
+* `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 <http://wiki.openmoko.org/wiki/Dfu-util>`_: A tool from
- `OpenMoko`_ that we use to upload programs to the Maple over USB.
+* `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
@@ -229,8 +271,8 @@ You will need the following tools\ [#fpackman]_ to get started:
* `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 ::
+ extract the `latest version
+ <http://pypi.python.org/pypi/pyserial>`_, then install with ::
$ cd /path/to/pyserial-x.y
$ python setup.py build
@@ -241,9 +283,10 @@ You will need the following tools\ [#fpackman]_ to get started:
$ easy_install pyserial
-**2. Fetch libmaple and Compiler Toolchain**
+2. Fetch ``libmaple`` and Compiler Toolchain
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-You first need to clone libmaple::
+First, make a `Git`_ clone of :ref:`libmaple`::
$ cd ~
$ git clone git://github.com/leaflabs/libmaple.git
@@ -251,22 +294,22 @@ You first need to clone libmaple::
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
+special-purpose versions of :ref:`GCC <arm-gcc>`).
- :file:`~/Downloads/gcc-blah-blah-osx32.tar.gz`
-
-You can unpack the archive and let the shell know where everything
-lives with ::
+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 -xvzf gcc-blah-blah-osx32.tar.gz
+ $ tar -xvf gcc-arm-none-eabi-latest-osx32.tar.gz
$ mv arm ~/libmaple/arm
$ export PATH=$PATH:~/libmaple/arm/bin
-After that's done, you'll probably want to update your shell startup
-script so :file:`~/libmaple/arm/bin` stays in your ``PATH``.
+After that's done, update your shell startup script so
+:file:`~/libmaple/arm/bin` stays in your ``PATH``.
-**So far, so good?**
+So far, so good?
+~~~~~~~~~~~~~~~~
Great! Test your setup by :ref:`compiling a sample program
<toolchain-test>`.
@@ -278,33 +321,46 @@ 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/>`_.
+1. Collect and Install Tools
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You'll need a few software tools for compiling and uploading programs.
+
+* `Git`_, a versioning system we use for :ref:`libmaple`. Install Git
+ using the wonderful `Windows guide on GitHub
+ <https://help.github.com/articles/set-up-git#platform-windows>`_.
+
+ .. note:: These instructions use Git Bash, the command-line
+ interface to Git on Windows. You can use the GitHub for
+ Windows application instead, but we haven't tried.
+
+* `Install Python <http://python.org/download>`_. Choose the latest
+ **2.7.x version**; Python 3 might work, but it's not tested.
-2. `Install Python <http://python.org/download>`_. Choose the latest
-**2.7.x version**; Python 3 will not work.
+* `Install PySerial <http://pypi.python.org/pypi/pyserial>`_. Choose
+ the latest **pyserial-x.y-win32.exe version** (or the "py3k" version
+ if you installed Python 3).
-3. `Install PySerial <http://pypi.python.org/pypi/pyserial>`_. Choose
-the latest **pyserial-x.y-win32.exe version**; the "py3k" version will
-not work.
+2. Fetch ``libmaple`` and Compiler Toolchain
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-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). ::
+First, make a Git clone of :ref:`libmaple`. Do this by running Git
+Bash (which you installed in step 1), 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
+You now have the libmaple repository in the folder ``C:\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
+Next, download the `compilers and other tools
+<http://static.leaflabs.com/pub/codesourcery/gcc-arm-none-eabi-latest-win32.tar.gz>`_
+you'll use to build and upload your programs. When the download
+finishes, move the file into the libmaple repository's folder. Then
+type these two lines into the Git Bash prompt to go to the libmaple
folder and extract the archive::
$ cd libmaple
@@ -312,14 +368,13 @@ folder and extract the archive::
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.
+You'll now configure your system to use these tools. Type the
+following lines into Git Bash.
.. 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.
+ this guide, and have a .bashrc already, typing these lines will
+ overwrite it. If that's the case, we assume you know what you're
+ doing, and can modify your .bashrc appropriately.
If you're using Bash for the first time, don't worry about this
warning.
@@ -333,13 +388,13 @@ following lines into the Git Bash prompt.
.. 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 (.).
+ 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):
+look like at this point (the green prompts and output after the ``git
+clone`` line will be slightly different):
.. _toolchain-git-bash-screenshot:
@@ -347,10 +402,13 @@ be slightly different):
: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
+3. Check Your Setup
+~~~~~~~~~~~~~~~~~~~
+
+Let's check that you completed the previous step correctly. If you
+did, there will 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
@@ -365,12 +423,11 @@ The Notepad window should look like this:
: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``.
+the Notepad window (don't save any changes you may have accidentally
+made).
-**So far, so good?**
+So far, so good?
+~~~~~~~~~~~~~~~~
Great! Go on to the next section, where you'll compile a program.
@@ -380,10 +437,10 @@ 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 (Windows users: use ``cs-make`` instead of
-``make``)::
+in :file:`libmaple` under your home directory) and test that you've
+installed all the compilation tools correctly::
+ # Note: Use "cs-make" instead of "make" on Windows
$ cd ~/libmaple
$ cp main.cpp.example main.cpp
$ make clean
@@ -392,47 +449,35 @@ compilation tools correctly (Windows users: use ``cs-make`` instead of
.. 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
- Bash), ::
+ Bash), run::
- $ export BOARD=maple_mini
- $ make
+ $ export BOARD=maple_mini
+ $ make
- The ``BOARD`` for Maple RET6 edition is ``maple_RET6``. You can
- also use ::
+ You can also use the following, but you'll need to write the
+ ``BOARD=maple_mini`` part every time you call ``make`` (for ``make
+ install``, etc.)::
- $ BOARD=maple_mini make
+ $ BOARD=maple_mini make
- This will only set the environment variable for the duration of
- that single compile.
+ To get a list of all boards, run ::
-If it all works out, you should end up seeing something like this::
+ $ make list-boards
- find build -iname *.o | xargs arm-none-eabi-size -t
- text data bss dec hex filename
- 482 4 24 510 1fe build/wirish/comm/HardwareSerial.o
- 260 0 0 260 104 build/wirish/comm/HardwareSPI.o
- 60 0 0 60 3c build/wirish/wirish.o
+ To make this setting permanent, put the ``export BOARD=maple_mini``
+ line in your .bashrc.
- [...]
-
- 2196 0 1 2197 895 build/libmaple/usb/usb_lib/usb_core.o
- 1904 0 0 1904 770 build/libmaple/usb/usb_lib/usb_regs.o
- 56 0 0 56 38 build/libmaple/usb/usb_lib/usb_init.o
- 344 0 0 344 158 build/libmaple/usb/usb_hardware.o
- 6637 0 58 6695 1a27 build/main.o
- 21499 201 391 22091 564b (TOTALS)
+If all goes well, you should see a bunch of output, then something
+like this::
Final Size:
- arm-none-eabi-size build/maple.out
- text data bss dec hex filename
- 21824 200 552 22576 5830 build/maple.out
- Flash build
+ text data bss dec hex filename
+ 13164 1704 552 15420 3c3c build/maple.elf
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 culprits.
+bytes. The long table of object files above the ``Final Size`` shows
+similar information on a per-file basis. You can use it to help slim
+down programs that use too much space.
.. _toolchain-upload:
@@ -445,7 +490,7 @@ 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 ::
+Plug in your Maple using the Mini-B USB cable, then run ::
$ cd ~/libmaple
$ cp examples/test-session.cpp main.cpp
@@ -465,10 +510,10 @@ 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
-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::
+device file will look something like :file:`/dev/ttyACMXXX` on Linux,
+:file:`/dev/tty.usbmodemXXX` on OS X, or :file:`COMx` on Windows, but
+``XXX`` will vary depending on your system. Try using one of these to
+find out which it is::
# Linux
$ ls /dev/ttyACM*
@@ -476,18 +521,25 @@ is::
# OS X
$ ls /dev/tty.usbmodem*
-To open up a session, run ::
+ # Windows, works from libmaple directory
+ $ python support/scripts/win-list-com-ports.py
+
+To open up a session on Linux or OS X, run ::
$ screen /dev/ttyXXX
+(On Windows, you will need to use a separate program, such as Maple
+IDE's serial console or `PuTTY
+<http://www.chiark.greenend.org.uk/~sgtatham/putty/>`_.)
+
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,
+To exit the screen session, type :kbd:`C-a k` (control-a k) on Linux,
+or :kbd:`C-a C-\\` (Control-a, followed by Control-backslash) on OS X,
and type ``y`` when prompted if you're sure.
.. note::
@@ -529,25 +581,27 @@ This will produce a build-time library in the file
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`.
+There is also a page on `starting a project with the Unix toolchain
+<http://wiki.leaflabs.com/index.php?title=Starting_A_Project_%28No_IDE%29>`_
+on the `LeafLabs wiki <http://wiki.leaflabs.com>`_ that you may find
+useful.
Get 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::
+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
+We do our best to keep the master libmaple branch on GitHub free from
+broken or half-finished code, so don't be too scared running the
+latest and greatest. If you do, please report any bugs or regressions!
+
+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.
@@ -559,14 +613,32 @@ notifications about bleeding-edge development.
.. _toolchain-openocd:
-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. 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.
+(Optional) Upload/Debug with JTAG/SWD
+-------------------------------------
+
+Advanced users will wish to use a JTAG (or SWD) dongle for uploading
+and debugging their programs. A big advantage to this approach is that
+it lets you use `GDB
+<http://www.gnu.org/software/gdb/documentation/>`_ to single-step
+through your code, inspect variables, etc.
+
+You can build your projects for JTAG or SWD upload with the ``jtag``
+Makefile target. Instead of compiling with ``make``, compile with
+``make jtag``. Then use your method of choice to upload the resulting
+program, which will be in ``build/<your-board>.elf`` in the libmaple
+directory.
+
+.. warning:: Uploading code built with the ``jtag`` target will
+ overwrite the :ref:`bootloader <bootloader>`. This is a good thing
+ -- since you're using another upload method, this lets you use the
+ Flash and RAM the bootloader ordinarily reserves for itself. You
+ can always :ref:`reflash the bootloader <bootloader-reflashing>`
+ later.
+
+While LeafLabs doesn't officially support any particular way of using
+JTAG with Maple, there is a `JTAG How-To
+<http://wiki.leaflabs.com/index.php?title=Maple_JTAG_How_To>`_ on the
+`LeafLabs wiki <http://wiki.leaflabs.com>`_ that you may find useful.
.. _toolchain-exuberantly:
@@ -579,12 +651,20 @@ Let us know what you come up with! Mention `@leaflabs on Twitter
<http://freenode.net/irc_servers.shtml>`_, whatever. We love projects!
.. _PySerial: http://pyserial.sourceforge.net/
+.. _OpenMoko: http://openmoko.com/
+.. _Git: http://git-scm.com/
+.. _dfu-util: http://wiki.openmoko.org/wiki/Dfu-util
.. 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.
+
.. [#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. Of course, your mileage
- may vary.
+ touched a package manager on OS X since. Your mileage may vary.