diff options
Diffstat (limited to 'source/unix-toolchain.rst')
| -rw-r--r-- | source/unix-toolchain.rst | 359 |
1 files changed, 244 insertions, 115 deletions
diff --git a/source/unix-toolchain.rst b/source/unix-toolchain.rst index 3c57605..40d14ea 100644 --- a/source/unix-toolchain.rst +++ b/source/unix-toolchain.rst @@ -324,112 +324,148 @@ Great! Test your setup by :ref:`compiling a sample program Windows ^^^^^^^ -These instructions have been tested successfully on Windows XP SP3. +These instructions have been tested successfully on Windows 7 Home +Premium. 1. Collect and Install Tools ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You'll need a few software tools for compiling and uploading programs. +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`_, a versioning system we use for :ref:`libmaple`. Install Git - using the wonderful `Windows guide on GitHub - <https://help.github.com/articles/set-up-git#platform-windows>`_. + $ git clone git://github.com/leaflabs/libmaple.git - .. note:: These instructions use Git Bash, the command-line - interface to Git on Windows. You can use the GitHub for - Windows application instead, but we haven't tried. + If you go this route, you don't need a GitHub account. -* `Install Python <http://python.org/download>`_. Choose the latest - **2.7.x version**; Python 3 might work, but it's not tested. +* `Python`_: choose the **latest 2.7.x version**. (Python 3 works, but + you're on your own.) -* `Install PySerial <http://pypi.python.org/pypi/pyserial>`_. Choose - the latest **pyserial-x.y-win32.exe version** (or the "py3k" version - if you installed Python 3). +* `PySerial`_: Choose the latest **pyserial-x.y-win32.exe version**. 2. Fetch ``libmaple`` and Compiler Toolchain ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -First, make a Git clone of :ref:`libmaple`. Do this by running Git -Bash (which you installed in step 1), 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). :: +First, make a Git clone of the :ref:`libmaple` repository with the +following steps: - $ git clone git://github.com/leaflabs/libmaple.git +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: -.. note:: Keep the Git Bash window open as you go. + .. figure:: /_static/img/github-clone-in-windows.png -You now have the libmaple repository in the folder ``C:\Documents and -Settings\<Your Name>``. + 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, download the `compilers and other tools -<http://static.leaflabs.com/pub/codesourcery/gcc-arm-none-eabi-latest-win32.tar.gz>`_ -you'll use to build and upload your programs. When the download -finishes, move the file into the libmaple repository's folder. Then -type these two lines into the Git Bash prompt to go to the libmaple -folder and extract the archive:: +Next, you'll need to get some cross-compilers and other tools for +building and uploading your programs: - $ cd libmaple - $ tar xzf gcc-arm-none-eabi-latest-win32.tar.gz +- `Download a .zip of the latest tools + <http://static.leaflabs.com/pub/codesourcery/gcc-arm-none-eabi-latest-win32.zip>`_. -This will create a folder named "arm" inside the libmaple folder. +- Extract the .zip, and **move the extracted "arm" folder into the + libmaple repository's folder**. -You'll now configure your system to use these tools. Type the -following lines into Git Bash. + You can open the libmaple repository folder by right-clicking + libmaple in the main GitHub for Windows screen and choosing "open in + explorer": -.. warning:: If you've installed Bash on your computer before starting - this guide, and have a .bashrc already, typing these lines will - overwrite it. If that's the case, we assume you know what you're - doing, and can modify your .bashrc appropriately. + .. figure:: /_static/img/win7-github-open-in-explorer.png + :align: center - If you're using Bash for the first time, don't worry about this - warning. +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. - $ cat >~/.bashrc <<EOF - > export PATH=\$PATH:~/libmaple/arm/bin/ - > EOF +If you've never set environment variables before, this section +explains what to do. -.. note:: The "> " at the beginning of the second and third lines will - appear automatically. +**Add Python to your PATH**: - 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 (.). + 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": -For reference, here's a screenshot of what your Git Bash window should -look like at this point (the green prompts and output after the ``git -clone`` line will be slightly different): + .. figure:: /_static/img/win7-copy-python-address.png + :align: center -.. _toolchain-git-bash-screenshot: + 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. -.. figure:: /_static/img/winxp-git-bash-screenshot.png - :align: center - :alt: Git Bash screenshot + - If PATH is missing from the list, click "New...". -3. Check Your Setup -~~~~~~~~~~~~~~~~~~~ + 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: -Let's check that you completed the previous step correctly. If you -did, there will 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/win7-copy-arm-bin-address.png + :align: center -.. figure:: /_static/img/winxp-open-bashrc-with.png - :align: center - :alt: Open .bashrc With + 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: -Choose "Notepad" from the resulting pop-up window, and click "OK". -The Notepad window should look like this: + .. figure:: /_static/img/win7-python-arm-bin-path.png + :align: center -.. figure:: /_static/img/winxp-bashrc-notepad.png - :align: center - :alt: .bashrc in Notepad + Click OK. -The little box at the end of the line is supposed to be there. Close -the Notepad window (don't save any changes you may have accidentally -made). +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? ~~~~~~~~~~~~~~~~ @@ -441,48 +477,114 @@ Great! Go on to the next section, where you'll compile a program. Test compilation ---------------- -Get back into the libmaple directory (this tutorial assumes you put it -in :file:`libmaple` under your home directory) and test that you've -installed all the compilation tools correctly:: +Test that you've installed all the compilation tools correctly by +running these commands in your shell:: + + # 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 - # Note: Use "cs-make" instead of "make" on Windows - $ cd ~/libmaple $ cp main.cpp.example main.cpp $ make clean $ make -.. 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 - Bash), run:: +If all goes well, you should see a bunch of output, then something +like this:: - $ export BOARD=maple_mini - $ make + Final Size: + text data bss dec hex filename + 13164 1704 552 15420 3c3c build/maple.elf + +Hurray! You've just compiled your first program for Maple. + +**Important: if you're not using Maple (Maple Mini, etc.), make sure +to read the following note before moving on**. + +You can now move on to :ref:`uploading a program <toolchain-upload>`, +or take a quick detour to learn :ref:`more about the build output +<toolchain-build-info>`. - You can also use the following, but you'll need to write the - ``BOARD=maple_mini`` part every time you call ``make`` (for ``make - install``, etc.):: +.. _toolchain-setting-board: - $ BOARD=maple_mini make +.. note:: This tutorial assumes you're using a Maple. If you're + compiling for another board, you'll need to set a ``BOARD`` + environment variable appropriately. - To get a list of all boards, run :: + To get a list of values for ``BOARD``, run :: $ make list-boards - To make this setting permanent, put the ``export BOARD=maple_mini`` - line in your .bashrc. + For example, to compile for Maple Mini: -If all goes well, you should see a bunch of output, then something -like this:: + * On OS X or Linux, run:: - Final Size: - text data bss dec hex filename - 13164 1704 552 15420 3c3c build/maple.elf + $ export BOARD=maple_mini + $ make + + * On Windows, set a new environment variable named ``BOARD`` to + value ``maple_mini``, then open a new Git Shell, and run ``cd + libmaple`` followed by ``cs-make`` as explained above. + + You can check that this worked by making sure that the final + program file is named ``build/maple_mini.elf`` instead of + ``maple.elf``:: + + Final Size: + text data bss dec hex filename + 16848 2696 704 20248 4f18 build/maple_mini.elf + + Other notes for OS X and Linux: + + - You can also use the following, but you'll need to write the + ``BOARD=maple_mini`` part every time you call ``make`` (for + ``make install``, etc.):: + + $ BOARD=maple_mini make + + - To make the board setting permanent, add this line to your + .bashrc:: + + export BOARD=maple_mini + +.. warning:: You must start from a clean build after each time you + change ``BOARD`` (advanced users: or ``MEMORY_TARGET``). For + example, if you compile a program for Maple, then you want to + compile another program for Maple Mini, you must run ``$ make + clean`` **before** you compile the second program. If you do not, + you will experience strange errors. + +.. _toolchain-build-info: + +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 gives the total program size in -bytes. The long table of object files above the ``Final Size`` shows -similar information on a per-file basis. You can use it to help slim -down programs that use too much space. +- 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 + programs that use too much space. + +- ``build/$BOARD.elf`` is the final build result (where ``BOARD`` is + ``maple``, ``maple_mini``, etc. :ref:`depending on your build + <toolchain-setting-board>`). + +- There are other files under ``build`` you may be interested in, like + disassembly and map files. + +- If you want quicker build times, you should check out our blog post, + `Making libmaple compile faster + <http://leaflabs.com/2012/08/2549/>`_. .. _toolchain-upload: @@ -491,13 +593,20 @@ Upload a program 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>`. If you're on Linux, then before -executing ``make install``, you'll want to have the udev rules setup -:ref:`as described above <toolchain-udev>`. +over a :ref:`USB serial port <usb>`. -Plug in your Maple using the Mini-B USB cable, then run :: +* Linux: you need udev rules set up :ref:`as described above + <toolchain-udev>`. + +* Windows: you need to :ref:`install the Maple's device drivers + <maple-ide-install-windows-drivers>`. + +* OS X: everything Just Works for you. Aren't you special? + +Plug in your Maple using a Mini-B USB cable, then run :: + + # Window users: as usual, use cs-make instead of make. - $ cd ~/libmaple $ cp examples/test-session.cpp main.cpp $ make clean $ make @@ -514,11 +623,14 @@ friend. Communicate over USB-Serial --------------------------- -Now let's try out the interactive test session. The serial port -device file will look something like :file:`/dev/ttyACMXXX` on Linux, -:file:`/dev/tty.usbmodemXXX` on OS X, or :file:`COMx` on Windows, but -``XXX`` will vary depending on your system. Try using one of these to -find out which it is:: +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*` +* Windows: it will be :file:`COMx`, where ``x`` is some number. + +Try using one of these to find out which it is:: # Linux $ ls /dev/ttyACM* @@ -537,11 +649,28 @@ To open up a session on Linux or OS X, run :: IDE's serial console or `PuTTY <http://www.chiark.greenend.org.uk/~sgtatham/putty/>`_.) -If the interactive test program built and uploaded correctly, -``screen`` won't report any errors, and will present you an empty -terminal. Your board is now waiting for you to send it a command. -Type ``h`` to print a list of commands which demonstrate various -features; type any command's letter to run it. +``screen`` will present you an empty terminal. Your board is waiting +for you to send it a command. Type ``h`` to print a list of commands; +type any command's letter to run it. + +.. highlight:: none + +Example output (for Maple):: + + > u + Hello World! + > b + Board information + ================= + * Clock speed (MHz): 72 + * BOARD_LED_PIN: 13 + * BOARD_BUTTON_PIN: 38 + * GPIO information (BOARD_NR_GPIO_PINS = 44): + ADC pins (15): 0, 1, 2, 3, 10, 11, 12, 15, 16, 17, 18, 19, 20, 27, 28 + PWM pins (15): 0, 1, 2, 3, 5, 6, 7, 8, 9, 11, 12, 14, 24, 27, 28 + Used pins (7): 13, 38, 39, 40, 41, 42, 43`` + +.. highlight:: sh To exit the screen session, type :kbd:`C-a k` (control-a k) on Linux, or :kbd:`C-a C-\\` (Control-a, followed by Control-backslash) on OS X, @@ -630,7 +759,7 @@ through your code, inspect variables, etc. You can build your projects for JTAG or SWD upload with the ``jtag`` Makefile target. Instead of compiling with ``make``, compile with ``make jtag``. Then use your method of choice to upload the resulting -program, which will be in ``build/<your-board>.elf`` in the libmaple +program, which will be in ``build/$BOARD.elf`` in the libmaple directory. .. warning:: Uploading code built with the ``jtag`` target will |