aboutsummaryrefslogtreecommitdiffstats
path: root/source
diff options
context:
space:
mode:
authorMarti Bolivar <mbolivar@leaflabs.com>2012-09-05 01:15:08 -0400
committerMarti Bolivar <mbolivar@leaflabs.com>2012-09-05 01:15:08 -0400
commit9c4e459269686720c57c690669312f2a0e2c347a (patch)
tree50e6022d950dab47844e787a7574129e7cca651a /source
parent5494bff2f9239b92ad8841bb127d33948bccf150 (diff)
downloadlibrambutan-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')
-rw-r--r--source/contents.rst3
-rw-r--r--source/epilog.rst6
-rw-r--r--source/unix-toolchain-linux-setup.rst186
-rw-r--r--source/unix-toolchain-osx-setup.rst131
-rw-r--r--source/unix-toolchain-win-setup.rst160
-rw-r--r--source/unix-toolchain.rst517
6 files changed, 524 insertions, 479 deletions
diff --git a/source/contents.rst b/source/contents.rst
index 7bb60b8..7be7aec 100644
--- a/source/contents.rst
+++ b/source/contents.rst
@@ -14,6 +14,9 @@ Contents in Full
maple-ide-install
ide
unix-toolchain
+ unix-toolchain-linux-setup
+ unix-toolchain-osx-setup
+ unix-toolchain-win-setup
whats-new
.. _index-maple-programming:
diff --git a/source/epilog.rst b/source/epilog.rst
index e64103c..b548001 100644
--- a/source/epilog.rst
+++ b/source/epilog.rst
@@ -6,3 +6,9 @@
.. _forum: http://forums.leaflabs.com
.. _contact: http://leaflabs.com/contact/
.. _contact us directly: http://leaflabs.com/contact/
+.. _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
diff --git a/source/unix-toolchain-linux-setup.rst b/source/unix-toolchain-linux-setup.rst
new file mode 100644
index 0000000..2ba7689
--- /dev/null
+++ b/source/unix-toolchain-linux-setup.rst
@@ -0,0 +1,186 @@
+.. highlight:: sh
+
+.. _unix-toolchain-linux-setup:
+
+Unix Toolchain Linux Setup
+==========================
+
+This page contains instructions for setting up a Linux computer for
+use with the :ref:`Unix toolchain <unix-toolchain>`.
+
+These instructions have been tested successfully on:
+
+- Ubuntu 10.04 and 12.04 (32- and 64-bit)
+- Fedora 17 (64-bit)
+
+Generic instructions for other distributions are also provided. Please
+`contact`_ us with any updates for distros not already covered!
+
+.. contents:: Contents
+ :local:
+
+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/>`_).
+
+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 the 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:
+
+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! Move on by :ref:`compiling a sample program <toolchain-test>`.
+
+.. 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.
+
diff --git a/source/unix-toolchain-osx-setup.rst b/source/unix-toolchain-osx-setup.rst
new file mode 100644
index 0000000..3ed78af
--- /dev/null
+++ b/source/unix-toolchain-osx-setup.rst
@@ -0,0 +1,131 @@
+.. highlight:: sh
+
+.. _unix-toolchain-osx-setup:
+
+Unix Toolchain OS X Setup
+=========================
+
+This page contains instructions for setting up an OS X computer for
+use with the :ref:`Unix toolchain <unix-toolchain>`.
+
+These instructions have been tested successfully on OS X 10.6.4 and
+10.8.1.
+
+.. contents:: Contents
+ :local:
+
+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
+
+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! Move on by :ref:`compiling a sample program <toolchain-test>`.
+
+.. rubric:: Footnotes
+
+.. [#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.
diff --git a/source/unix-toolchain-win-setup.rst b/source/unix-toolchain-win-setup.rst
new file mode 100644
index 0000000..5885741
--- /dev/null
+++ b/source/unix-toolchain-win-setup.rst
@@ -0,0 +1,160 @@
+.. highlight:: sh
+
+.. _unix-toolchain-win-setup:
+
+Unix Toolchain Windows Setup
+============================
+
+This page contains instructions for setting up a Windows computer for
+use with the :ref:`Unix toolchain <unix-toolchain>`.
+
+These instructions have been tested successfully on Windows 7 Home
+Premium.
+
+.. contents:: Contents
+ :local:
+
+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**.
+
+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
+
+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
+
+.. 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.
+
+So far, so good?
+----------------
+
+Great! Go on to the next section, where you'll compile a program.
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.