aboutsummaryrefslogtreecommitdiffstats
path: root/source/unix-toolchain.rst
diff options
context:
space:
mode:
Diffstat (limited to 'source/unix-toolchain.rst')
-rw-r--r--source/unix-toolchain.rst395
1 files changed, 249 insertions, 146 deletions
diff --git a/source/unix-toolchain.rst b/source/unix-toolchain.rst
index f68a17e..4fc21ea 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,53 +21,51 @@ 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.
.. warning:: Due to firmware bugs in our :ref:`bootloader
<bootloader>`, you must use recent versions of ``dfu-util``, or
@@ -84,18 +74,37 @@ upload programs to the Maple over USB.
.. _OpenMoko: http://openmoko.com/
-``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.
+* `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>`_.
-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** ::
@@ -106,16 +115,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``.
@@ -154,113 +162,101 @@ 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.
- .. 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.
+* `dfu-util <http://wiki.openmoko.org/wiki/Dfu-util>`_: A tool from
+ `OpenMoko`_ that we use to upload programs to the Maple over USB.
- 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
+ .. 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.
- :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
@@ -272,7 +268,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:
@@ -280,8 +380,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
@@ -291,7 +392,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
@@ -360,8 +461,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
@@ -402,8 +503,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.
@@ -435,8 +536,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
@@ -472,11 +573,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