diff options
Diffstat (limited to 'docs/source/unix-toolchain.rst')
| -rw-r--r-- | docs/source/unix-toolchain.rst | 134 |
1 files changed, 32 insertions, 102 deletions
diff --git a/docs/source/unix-toolchain.rst b/docs/source/unix-toolchain.rst index e6039a2..836f777 100644 --- a/docs/source/unix-toolchain.rst +++ b/docs/source/unix-toolchain.rst @@ -8,7 +8,7 @@ This is a tutorial for using the Maple with a standard Unix toolchain. It's not necessary to do this in order to program the Maple; you can -always use our `IDE <maple-ide-install>`_ instead. +always :ref:`install the Maple IDE <maple-ide-install>` instead. You'll need a Maple board, a mini-b USB cable, a functional computer, and root access to that computer. This guide assumes you've had @@ -16,10 +16,10 @@ 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 `make <http://www.gnu.org/software/make/>`_ is recommended. For -generic installation/setup issues, the `IDE install -<http://leaflabs.com/docs/libmaple/install/>`_ and -:ref:`troubleshooting` pages may be helpful. If all else fails, try -our `forum`_, or `contact us directly`_\ ! +generic installation/setup issues, the :ref:`IDE installation +<maple-ide-install>` and :ref:`troubleshooting` pages may be +helpful. If all else fails, try our `forum`_, or `contact us +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 @@ -28,7 +28,7 @@ directions on your own. As a jumping off point, 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, +(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! @@ -55,7 +55,7 @@ First I'll give the commands to run, then explain:: You'll want to install a bunch of developer "basics" like :command:`make`, :command:`tar`, etc. A good catch-all for these -tools is the "build-essential" meta-package on most debian platforms: +tools is the "build-essential" meta-package on most Debian platforms: installing this fake package will pull in dozens of useful tools without bogging your system down too much. ``git-core`` is the name of the git package; `Git <http://git-scm.com/>`_ is a distributed code @@ -90,7 +90,7 @@ package; this could also be installed with `easy_install $ git clone git://github.com/leaflabs/libmaple.git libmaple $ cd libmaple $ wget http://static.leaflabs.com/pub/codesourcery/gcc-arm-none-eabi-latest-linux32.tar.gz - $ tar xvf arm-*-linux32.tar.gz + $ tar xvf 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 @@ -104,6 +104,9 @@ where you put the toolchain, make sure to preserve its internal directory layout, as the binaries make relative path calls and references. +After you're done, you'll probably want to update your shell startup +script so :file:`~/libmaple/arm/bin` stays in your ``PATH``. + .. _toolchain-udev: **3. Install udev Rules** @@ -136,15 +139,11 @@ 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 `Maple IDE -<http://leaflabs.com/docs/maple-ide/>`_ to develop programs. Some of -these software packages might be available on `MacPorts -<http://www.macports.org/>`_. The author had some bad experiences with -MacPorts a few years ago, though, and hasn't touched it since. Of -course, your mileage may vary. +<http://leaflabs.com/docs/maple-ide/>`_ to develop programs. **1. Collect and Install Tools** -You will need the following tools to get started: +You will need the following tools\ [#fmacports]_ to get started: 1. `XCode <http://developer.apple.com/technologies/xcode.html>`_: If you're reading this, you've probably already got this. Provides @@ -326,7 +325,7 @@ something like :file:`/dev/ttyACMXXX` on Linux or :file:`/dev/tty.usbmodemXXX` on OS X, but it might have a slightly different name on your system. To open up a session, run :: - $ screen /dev/tty-whatever-it-is + $ screen /dev/ttyXXX If the interactive test program built and uploaded correctly, you should be able to connect without any errors reported by @@ -335,20 +334,25 @@ there are a number of commands which demonstrate Maple peripheral features. As of October 2010, the HardwareSerial library is blocking, so using any commands which would write to the USART Serial ports will cause the program to hang. To exit the screen session, type :kbd:`C-a -C-\\` (control-a, followed by control-backslash), and type ``y`` when -prompted if you're sure. +C-\\` (control-a, followed by control-backslash) on Mac, or :kbd:`C-a +k` (control-a k) on Linux, and type ``y`` when prompted if you're +sure. -Using :command:`screen` in this way sometimes messes up your session. -If your shell starts acting up after you exit screen, you should be -able to fix it with :: +.. note:: - $ reset && clear + Using :command:`screen` in this way sometimes messes up your + terminal session on OS X. If your shell starts acting up after you + exit screen, you should be able to fix it with :: + + $ reset && clear .. _toolchain-projects: Starting your own projects -------------------------- +.. TODO fix the build-targets.mk mess, note the "library" target + So everything worked, and you want to start your own project? Great! It's easy. Just set the environment variable ``LIB_MAPLE_HOME`` in your shell startup script to point to the libmaple repository you @@ -402,87 +406,6 @@ TODO. For now see `this great guide <http://fun-tech.se/stm32/OpenOCD/index.php>`_ from fun-tech.se, and the ``jtag`` Makefile target. -.. _toolchain-codeblocks: - -Do it all with Code::Blocks ---------------------------- - -.. TODO this really should reflect the new, more pleasant build system - -Optional. `Code::Blocks <http://www.codeblocks.org/>`_ is a generic -cross platform IDE. We don't personally use it for development, so we -haven't worked out all the kinks (e.g., debugging isn't integrated), -but it might be helpful for people who are allergic to `vim -<http://www.vim.org/>`_ and/or `Emacs -<http://www.gnu.org/software/emacs/>`_. The simple configuration -described here just calls down to the :file:`Makefile`, so follow the -above directions to get the command line tools configured (you'll -definitely need the arm-none-eabi-* tools on your ``PATH``), then -`install Code::Blocks <http://www.codeblocks.org/downloads/26>`_. You -can do this on Linux with:: - - $ sudo aptitude install codeblocks - -The first time it runs you'll maybe want to disable all the glitzy -"Getting Started" crap (when will they learn?). We've added a .cbp -"projects" file to the libmaple repository: you can try using that one -by copying it from :file:`support/codeblocks/libmaple.cbp` to the top -level directory, but no promises (it might be missing new source files -etc). It's probably worth reading through these instructions as well -to get a feel for how it all works. - -To create your own "libmaple" project, start with an "Empty Project" -with the "Folder to create project in" set to your -``LIB_MAPLE_HOME``. Make sure that the "Resulting filename" is in the -top level directory as well. - -.. image:: /_static/img/codeblocks_newproject.png - :align: center - :alt: Code::Blocks new project wizard - -Select the "GNU GCC Compiler" (it won't be used, anyway) and disable -the "Debug" configuration in the next window. Now you should have a -project with no files; add files by right clicking on the project in -the left panel file hierarchy and "Add files recursively". Import both -the :file:`wirish` and :file:`libmaple` directories recursively, then -add :file:`main.cpp` separately. - -.. image:: /_static/img/codeblocks_makefile.png - :align: center - :alt: Code::Blocks targets options - -Next we have to configure the Makefile targets. Go to the -"Properties..." menu under "Project" and check the "This is a custom -Makefile" box. Then go to the "Build targets" tab and create "ram" and -"flash" targets, both of type "Console application" and without the -Auto-generated filename prefixes or extensions. Set the Output -filename to :file:`support/codeblocks/program_flash.sh` and -:file:`support/codeblocks/program_ram.sh` respectively; these scripts -just call the program_ram/program_flash make targets and are a hack to -get the "run" button to upload code to the Maple. The IDE will warn -that these files will be overwritten, but they won't be. For both the -"flash" and "ram" targets, click the "Build options..." button (below -"Virtual targets..." etc) and go to the far right tab ("'Make' -commands"). Edit the Clean project/target line so it's just "clean" -(not "clean$target"), and set the "Build project/target" and "Compile -single file" commands to ``$make -f $makefile MAPLE_TARGET=$target`` -and ``$make -f $makefile MAPLE_TARGET=$target $file``, respectively. - -.. image:: /_static/img/codeblocks_maketargets.png - :align: center - :alt: Code::Blocks make targets - -Save all these changes, go back to the main IDE window, and try to -build/run. "Build" will compile everything, "Run" will run the upload -script in a terminal window (if there are problems they will flash by -very quickly; you can start Code::Blocks in a terminal window and -check the output in that base window if necessary), and "Rebuild" will -clean before rebuilding. - -.. image:: /_static/img/codeblocks_build.png - :align: center - :alt: Success! - .. _toolchain-exuberantly: Go forth exuberantly! @@ -491,3 +414,10 @@ Go forth exuberantly! Let us know what you come up with! Use #leaflabs on Twitter, post in the `forum`_, track us down in the real world, whatever. We love projects! + +.. rubric:: Footnotes + +.. [#fmacports] Some of these software packages might be available on + `MacPorts <http://www.macports.org/>`_. The author had some bad + experiences with MacPorts a few years ago, though, and hasn't + touched it since. Of course, your mileage may vary. |