diff options
author | Marti Bolivar <mbolivar@leaflabs.com> | 2012-09-05 01:15:08 -0400 |
---|---|---|
committer | Marti Bolivar <mbolivar@leaflabs.com> | 2012-09-05 01:15:08 -0400 |
commit | 9c4e459269686720c57c690669312f2a0e2c347a (patch) | |
tree | 50e6022d950dab47844e787a7574129e7cca651a /source/unix-toolchain.rst | |
parent | 5494bff2f9239b92ad8841bb127d33948bccf150 (diff) | |
download | librambutan-9c4e459269686720c57c690669312f2a0e2c347a.tar.gz librambutan-9c4e459269686720c57c690669312f2a0e2c347a.zip |
unix-toolchain: Break individual OS setup docs into separate files.
A monolithic quickstart is too unwieldy at this point. Move the
initial setup instructions into their own files to make it less
daunting and easier to read.
Signed-off-by: Marti Bolivar <mbolivar@leaflabs.com>
Diffstat (limited to 'source/unix-toolchain.rst')
-rw-r--r-- | source/unix-toolchain.rst | 517 |
1 files changed, 38 insertions, 479 deletions
diff --git a/source/unix-toolchain.rst b/source/unix-toolchain.rst index f767d7a..64fd9d1 100644 --- a/source/unix-toolchain.rst +++ b/source/unix-toolchain.rst @@ -11,469 +11,44 @@ This is a tutorial for using a standard Unix toolchain (``make``, 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: - :depth: 2 Requirements ------------ -You need: +We assume you've had success with the :ref:`Maple IDE <ide>` (this is +important on Windows, as this document doesn't cover :ref:`driver +installation <maple-ide-install-windows-drivers>`). + +At a minimum, you need: * Maple board * Mini-B USB cable * root (or Administrator) access to your computer. +On Linux and OS X, you need to know how to use `bash +<http://www.gnu.org/software/bash/>`_, and how to edit your .bashrc. Some experience using `GCC <http://gcc.gnu.org/>`_ and `make <http://www.gnu.org/software/make/>`_ is recommended, but is not required. -On Linux and OS X, you need to know how to use `bash -<http://www.gnu.org/software/bash/>`_, and how to edit your .bashrc. - -We assume you've had success with the :ref:`Maple IDE <ide>` (this is -important on Windows, as this document doesn't cover :ref:`driver -installation <maple-ide-install-windows-drivers>`). - -Setup ------ - .. _toolchain-linux-setup: - -Linux -^^^^^ - -1. Collect and Install Tools -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -First, you'll need some tools. - -.. 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. - -**Debian-based distributions (Debian, Ubuntu, Mint, etc.)**: - - Install mandatory and optional tools with :: - - $ sudo apt-get install build-essential git-core screen dfu-util python python-serial - - 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 :: - - # 64-bit systems only! - $ sudo apt-get install ia32-libs - - You may also need to remove `brltty <http://mielke.cc/brltty/>`_ - with :: - - # Optional - $ sudo apt-get remove brltty - - Brltty provides braille access to the console. It has been reported - to cause conflicts with Maple. - -**Red Hat-based distributions (RHEL, Fedora, Centos, etc.)**: - - Install mandatory and optional tools with :: - - $ sudo yum install screen git python pyserial dfu-util make - - 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 :: - - # 64-bit systems only! - $ sudo yum install glibc.i686 - - You may also need to remove `brltty <http://mielke.cc/brltty/>`_ - with one of these:: - - # Optional, 64-bit systems: - $ sudo yum erase brltty.x86_64 - - # Optional, 32-bit systems: - $ sudo yum erase brltty.i686 - - Brltty provides braille access to the console. It has been - reported to cause conflicts with Maple. - -**Other Linux distributions**: - - 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`_ 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`_. - - 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 - -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:: - - $ 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 - -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 -~~~~~~~~~~~~~~~~~~~~~ - -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 - -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 plugdev with :: - - $ sudo usermod -a -G plugdev $USER - - then log back out and log back in. - - After that's done, restart udev:: - - $ sudo restart udev - -**Red Hat-based distros**: - - :: - - $ udevadm control --reload-rules - -After restarting ``udev``, you'll need to unplug and re-plug your -Maple. - -So far, so good? -~~~~~~~~~~~~~~~~ - -Great! Test your setup by :ref:`compiling a sample program -<toolchain-test>`. - .. _toolchain-osx-setup: - -OS X -^^^^ - -These instructions have been tested successfully on OS X 10.6.4 and -10.8.1. - -1. Collect and Install Tools -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -First, you'll need some tools. [#fpackman]_ - -* `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`_: 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`_: 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 - uploads will not work. ``dfu-util`` versions 0.6 and greater - should work. - - 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>`_. - - 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` - - 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 - - .. note:: - - Copying the binary won't work, as it relies on dynamically linked - libraries found elsewhere in the .app bundle. - - 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 :: - - $ dfu-util -l - - The output should look like this:: - - 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" - -* `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 - extract 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 - - PySerial is also available via `easy_install`_, so if you're - comfortable using that, you could alternatively install it with :: - - $ easy_install pyserial - -2. Fetch ``libmaple`` and Compiler Toolchain -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -First, make a `Git`_ clone of :ref:`libmaple`:: - - $ cd ~ - $ git clone git://github.com/leaflabs/libmaple.git - -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 :ref:`GCC <arm-gcc>`). - -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 -xvf gcc-arm-none-eabi-latest-osx32.tar.gz - $ mv arm ~/libmaple/arm - $ export PATH=$PATH:~/libmaple/arm/bin - -After that's done, update your shell startup script so -:file:`~/libmaple/arm/bin` stays in your ``PATH``. - -So far, so good? -~~~~~~~~~~~~~~~~ - -Great! Test your setup by :ref:`compiling a sample program -<toolchain-test>`. - .. _toolchain-win-setup: -Windows -^^^^^^^ - -These instructions have been tested successfully on Windows 7 Home -Premium. - -1. Collect and Install Tools -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -First, you'll need some tools. - -* `GitHub for Windows <http://windows.github.com/>`_: this is a GUI - for `Git`_, the version control system we use for :ref:`libmaple`. - - If you don't have one, you need to sign up for a (free) `GitHub - account <https://github.com/signup/free>`_. - - .. note:: If you use Git from the command line, you can clone - libmaple with:: - - $ git clone git://github.com/leaflabs/libmaple.git - - If you go this route, you don't need a GitHub account. - -* `Python`_: choose the **latest 2.7.x version**. (Python 3 works, but - you're on your own.) - -* `PySerial`_: Choose the latest **pyserial-x.y-win32.exe version**. - -2. Fetch ``libmaple`` and Compiler Toolchain -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -First, make a Git clone of the :ref:`libmaple` repository with the -following steps: - -1. **Run GitHub for Windows**, and **sign in** using your GitHub - account. -2. **Visit** `libmaple's GitHub page - <https://github.com/leaflabs/libmaple/>`_, and **sign in** to - GitHub in your web browser as well. -3. **Click on the "Clone in Windows" button** on libmaple's GitHub - page, which looks like this: - - .. figure:: /_static/img/github-clone-in-windows.png - - Your browser may prompt you about what to do when you click the - "Clone in Windows" button. Choose the option that launches the - GitHub for Windows application. - -Next, you'll need to get some cross-compilers and other tools for -building and uploading your programs: - -- `Download a .zip of the latest tools - <http://static.leaflabs.com/pub/codesourcery/gcc-arm-none-eabi-latest-win32.zip>`_. - -- Extract the .zip, and **move the extracted "arm" folder into the - libmaple repository's folder**. - - You can open the libmaple repository folder by right-clicking - libmaple in the main GitHub for Windows screen and choosing "open in - explorer": - - .. figure:: /_static/img/win7-github-open-in-explorer.png - :align: center - -3. Update your PATH -~~~~~~~~~~~~~~~~~~~ - -You'll next need to configure your system to use the various tools -you've downloaded and installed. Do that by adding the Python and -``arm\bin`` directories to your PATH environment variable. - -If you've never set environment variables before, this section -explains what to do. - -**Add Python to your PATH**: - - Start by navigating to the folder where Python is installed on your - system (this is probably ``C:\Python27``). Right click on the folder - address, then choose "Copy address as text": - - .. figure:: /_static/img/win7-copy-python-address.png - :align: center - - Next, open your environment variables window: from the Start/Windows - menu, right click on Computer, then choose Properties > Advanced - System Settings > Environment Variables. Under the "User variables - for YOUR_USERNAME", look for PATH. - - - If PATH is missing from the list, click "New...". - - Under "Variable Name", write PATH. Under "Variable value", paste - the Python address you just copied, and click OK. The result looks - like this: - - .. figure:: /_static/img/win7-python-path.png - :align: center - - - If PATH is present in the list, click on it and choose "Edit...". - - Go to the end of the "Variable value:" text box, type a semicolon - (the ``;`` character), and then paste the path you just - copied. Click OK. - - Test that this worked by running the Git Shell program that came with - GitHub for Windows, then running ``python`` at the command prompt. You - should get a Python interpreter that looks like this: - - .. figure:: /_static/img/win7-python-prompt.png - :align: center - - If that worked, then close the window. - -**Add compiler toolchain to your PATH**: - - Do this by adding the ``arm\bin`` directory (earlier instructions - had you move ``arm`` to the libmaple repository folder) to your PATH - environment variable in the same way you added Python. - - Copy the address of the ``arm\bin`` folder by right-clicking on it - after navigating to it: - - .. figure:: /_static/img/win7-copy-arm-bin-address.png - :align: center - - The PATH environment variable should exist from when you added - Python to it, so make sure you choose "Edit..." from the - environment variables window. Then paste the ``arm\bin`` address you - copied after typing a semicolon. The final result will look - something like this: - - .. figure:: /_static/img/win7-python-arm-bin-path.png - :align: center - - Click OK. - -Once that's done, **open a new Git Shell**, then type this at the -prompt, and hit return:: - - cd libmaple +Setup +----- -.. warning:: You must open a new Git Shell window. If you use a shell - that's already open, then the changes to PATH you just - made won't be available, and the instructions in the next - section won't work. +You first need to set up your computer by installing and configuring +various things. Don't fret! We've got detailed instructions, just for +you. -So far, so good? -~~~~~~~~~~~~~~~~ +* :ref:`Linux <unix-toolchain-linux-setup>` +* :ref:`OS X <unix-toolchain-osx-setup>` +* :ref:`Windows <unix-toolchain-win-setup>` -Great! Go on to the next section, where you'll compile a program. +Come back when you're ready. We'll wait. .. _toolchain-test: @@ -481,14 +56,19 @@ Test compilation ---------------- Test that you've installed all the compilation tools correctly by -running these commands in your shell:: +running the following commands in your shell. + +Windows users: - # Windows users: - # - Type "cs-make" instead of "make" - # - Don't type the "$", just the parts that come after - # - # Linux and OS X users: - # - First get to libmaple with $ cd libmaple + - Don't type the ``$``'s, just the parts that come after. + - First get to libmaple by opening a Git Shell, then running ``cd libmaple``. + - **Always type** ``cs-make`` **instead of** ``make``. + +Linux and OS X users: + + - Run these from the top-level libmaple directory. + +:: $ cp main.cpp.example main.cpp $ make clean @@ -567,12 +147,12 @@ Notes about the ``libmaple`` build These are just some miscellaneous notes that are good to know. Feel free to skip reading this section. -- The ``dec`` field at the end under ``Final Size:`` gives the total - program size in bytes. The ``text``, ``data``, and ``bss`` fields - respectively break down the size of the program into `code - <http://en.wikipedia.org/wiki/Code_segment>`_, `initialized data - <http://en.wikipedia.org/wiki/Data_segment>`_, and `zero-valued data - <http://en.wikipedia.org/wiki/.bss>`_. +- The ``dec`` field at the end of the build output under ``Final + Size:`` gives the total program size in bytes. The ``text``, + ``data``, and ``bss`` fields respectively break down the size of the + program into `code <http://en.wikipedia.org/wiki/Code_segment>`_, + `initialized data <http://en.wikipedia.org/wiki/Data_segment>`_, and + `zero-valued data <http://en.wikipedia.org/wiki/.bss>`_. - The long list of object files above the ``Final Size`` shows similar information on a per-file basis. You can use it to help slim down @@ -598,8 +178,8 @@ 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>`. -* Linux: you need udev rules set up :ref:`as described above - <toolchain-udev>`. +* Linux: you need udev rules set up :ref:`as described in the setup + doc <toolchain-udev>`. * Windows: you need to :ref:`install the Maple's device drivers <maple-ide-install-windows-drivers>`. @@ -629,8 +209,8 @@ Communicate over USB-Serial Now let's try out the interactive test session. You need to connect to the board's serial port device file. -* Linux: this looks like :file:`/dev/ttyACM*` -* OS X: it looks like :file:`/dev/tty.usbmodem*` +* Linux: this looks like :file:`/dev/ttyACM*`. +* OS X: it looks like :file:`/dev/tty.usbmodem*`. * Windows: it will be :file:`COMx`, where ``x`` is some number. Try using one of these to find out which it is:: @@ -786,24 +366,3 @@ 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! - -.. _Python: http://python.org/download/ -.. _PySerial: http://pyserial.sourceforge.net/ -.. _OpenMoko: http://openmoko.com/ -.. _Git: http://git-scm.com/ -.. _dfu-util: http://wiki.openmoko.org/wiki/Dfu-util -.. _easy_install: http://packages.python.org/distribute/easy_install.html - -.. 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. Your mileage may vary. |