diff options
Diffstat (limited to 'source/unix-toolchain.rst')
| -rw-r--r-- | source/unix-toolchain.rst | 395 |
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 |