Buildroot

As of 2010, all Gumstix customers should be using Gumstix OpenEmbedded, not Buildroot.

The Gumstix Developer's website is www.gumstix.net

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

For legacy customers still requiring buildroot:

The Buildroot is the system was used to create flash filesystem images for use on the Gumstix.

With the Buildroot, anyone could construct a custom, complete Gumstix filesystem in a single command. It automates the steps in constructing the image, including
 * Downloading all necessary source code and data;
 * Building a cross-compilation toolchain to compile code for the Gumstix's ARM processor;
 * Compiling all Gumstix software, from the Linux kernel up through applications;
 * Stuffing all the results into the final filesystem image, suitable for loading into the Gumstix's flash memory.

The Buildroot also provides configuration menus, which can be used to add software to the filesystem image or remove existing packages. Everything from voice recognition to terminal emulators is but a checkbox away.

Version Information
For the latest information about the current buildroot version, visit http://cia.navi.cx/stats/project/gumstix-buildroot

A Note on Operating Systems
The Buildroot is designed for use on Linux. It can be coerced into working on other Unix-like systems (like FreeBSD, Mac OS X, or Cygwin), but it tends to be more difficult to maintain.

The default Buildroot configuration works on Linux 2.6.x-based systems. For 2.4.x systems, see the Buildroot on Linux 2.4 page for tips.

The Buildroot can be used on Windows by installing Linux. You don't even have to leave Windows -- you can install Linux in a virtual environment, such as VMware or Colinux, so that it runs in a window alongside your other applications. See the Buildroot on Windows page for details.

See Buildroot on Ubuntu for a Howto on getting Ubuntu configured for building the Buildroot.

See Buildroot on Dreamhost for a Howto on getting buildroot to build under your Dreamhost account.

See Buildroot on MacOSX for a Howto on getting buildroot to build on an Apple Mac OS X machine.

See Buildroot on SLED 10 SP1 for information on getting SLED 10 SP1 to build Buildroot.

Getting Started
To use the Buildroot, you must first obtain the files from Gumstix's public Subversion repository.

You will need the following things on your development host machine:
 * A Subversion client, to check out the files (and, later, to get updates). You can check if your Linux box already has one by entering   at the command prompt.
 * A C compiler, such as  and associated tools.  Most Linux systems already have these tools installed; if yours are missing, install your distribution's development tools package.  You will need the following tools installed: autoconf, automake, bison, byacc, gcc, gcc-c++, make, ncurses-devel, subversion, zlib-devel, texinfo, flex.
 * A network connection, both to fetch the Buildroot itself, and for the Buildroot to download subsequent files.
 * About 150MB of free disk space.

A browseable version of the repository can be accessed in your web browser by navigating to:

http://svn.gumstix.com/gumstix-buildroot/trunk

This will always be the latest version of the gumstix Subversion repository.

To check out the current revision of the Buildroot, enter the following on your development host:

Basix, Connex and Verdex boards (since revision 1445 the 270 branch has been merged into the main trunk): svn co http://svn.gumstix.com/gumstix-buildroot/trunk gumstix-buildroot (note: this will check out the latest version, which might not be stable, and might not build without errors. Check below on how to obtain an earlier revision)

The repository will prompt you for authentication. Use root as the user and root as the login.

If you are behind a proxy, make the following changes in ~/.subversion/servers Add a group:

Edit group1:

If you want to get a specific revision XXX, use

svn co -rXXX http://svn.gumstix.com/gumstix-buildroot/trunk gumstix-buildroot

To confirm the current revision on your gumstix, enter the following on your gumstix: cat /etc/gumstix-release | grep RELEASE

Different gumstix are shipped with different buildroot revisions (whatever was the latest release at the time of production of that batch of gumstix). The current revision MAY NOT BE BINARY COMPATIBLE with what came on your gumstix. This means that to use the buildroot toolchain to write programs without reflashing the operating system, you MUST first determine the version present on your gumstix. To find this version, boot the gumstix, and look at the file /etc/gumstix-release which will contain something like:

DISTRIB_ID='gumstix' DISTRIB_DESCRIPTION='' DISTRIB_RELEASE='773' DISTRIB_CODENAME='' BUILD_DATE='Fri Feb 2 13:36:05 PST 2007' BUILD_HOSTNAME='azazel.hughes-family.org'

The "DISTRIB_RELEASE" value is the revision of the buildroot which was used to build your gumstix's filesystem. Now do:

svn co -r773 http://svn.gumstix.com/gumstix-buildroot/trunk gumstix-buildroot

Replace "773" with your release number. This will create a new directory named gumstix-buildroot within your current directory. Using a version of buildroot which differs from the version of buildroot running on your gumstix, may result in segfaults or other errors which have nothing to do with the program being run.

If the make does not succeed, check the Troubleshooting section below, or the  operating system specific buildroot pages

Comment: (please edit if you have a solution, or if you have more insight into the buildroot system) It is possible that the build of the revision on your gumstix fails to build on your setup. I found revision 1161 on my gumstix, which had build errors on Ubuntu 6.06. However, I found revision 1445 and 1541 to compile successfully. (If anyone has a complete list of stable revisions, please create a wiki entry and link from here) (end comment)

Comment: Revision 1161, "makeinfo" build errors solved upgrading texinfo to 4.4 version or superior. ftp://ftp.gnu.org/gnu/texinfo/

For revisions of buildroot from 1445 to present, the verdex and basicx/connex branches have been merged together. cd gumstix-buildroot rm .config make defconfig make

This will stop and prompt you for the "Target Architecture Variant". Choose either "11. xscale (eg Gumstix basix/connex) (BR2_xscale) (NEW)" or "12. iwmmxt (eg Gumstix verdex) (BR2_iwmmxt) (NEW)". Then you will be prompted for the processor speed of your gumstix. Make the appropriate selection. Finally, type 'make' again to get the build to proceed.

For revisions of buildroot from 865 to 1444, use: cd gumstix-buildroot make defconfig make

For revisions of buildroot earlier than 865, use: cd gumstix-buildroot make

This will generate the initial Buildroot configuration files and kick off the process. Now is a good time to make some coffee or take up crochet -- this process will take a while, but it's fully automated and can run unattended.

The build process will generate a lot of output, and you may see some error messages go by. Unless the build halts with a glaring error message, you can safely ignore them for now -- some application configuration scripts will try various approaches and choose the one that works.

If it succeeds, the build will end with a line describing your shiny new root filesystem, which will be named.

The cross compilation toolchain can be found in the directory build_arm_nofpu/staging_dir/bin. The gcc and binutils tools should have the prefix "arm-linux-"; i.e. the gcc is called arm-linux-gcc.

You're done!

Installing the Filesystem
The Buildroot scripts produce a JFFS2 filesystem image, suitable for loading directly onto the Gumstix's flash memory, but not -- by default -- usable from an MMC or CompactFlash card. Fortunately, the process for flashing the image onto the Gumstix is safe and easy. See the Replacing the filesystem image page for details.

Using the cross compilation toolchain
Check the following pages for more detail:

Gumstix programming

Sample_code

Configuring the Buildroot
Unless the stock configuration meets your needs, you'll probably wish to install more software on your Gumstix. The easiest way to do this is with the Buildroot configuration menu.

In your buildroot directory (the  directory created when you checked out the Buildroot), enter: make menuconfig

This will bring you into a simple, text-based menu system for selecting what goes into your filesystem image. Use the arrow keys and spacebar to select or deselect packages, to tune the machine to your specifications. When completed, exit the configuration menu (saving your changes when prompted) and re-enter: make

It will rebuild only the parts that have changed, including fetching the source to any new packages you've selected.

Removing Packages from the Filesystem
If you enter the configuration menu and deselect a package, you may be surprised to discover that it's still in your filesystem image.

The Buildroot will rebuild only the aspects of your system that have changed -- and if you deselect a package, the change is that the Buildroot now no longer even looks at the package. It will not build the package's files, but it will also not remove them.

You can fix this by manually removing the package's files from, or simply by erasing that whole directory -- the Buildroot will restore it when you next run.

ATTENTION wifistix users- If you delete the  directory then the wifistix support will not be properly re-installed unless you also delete the   file.

Updating your Buildroot
Development of the Buildroot, and the software packages it contains, is ongoing. From time to time, you may wish to update your copy of the Buildroot -- either to get bug fixes, or to bring in new software packages.

To update your Buildroot, change to the gumstix-buildroot directory on your host and enter: svn update

(You will need a network connection.)

Adding a New Package to the Buildroot
If you'd like to install a software package that isn't available in the Buildroot, you can compile it yourself -- described in more detail on the Programming page -- or add it to the Buildroot system, and let the Buildroot do the work.

Adding new packages to the Buildroot itself has another advantage, of course: you can submit them for inclusion in the official Buildroot, benefiting your fellow Gumstix users.

The process for adding new software is described in detail in the buildroot documentation.

Inside the Buildroot
The structure of files and directories within the Buildroot is quite simple, and makes modifying the system very easy. This is described in more detail on the Buildroot Internals page.

Speeding up Buildroot
If you find yourself buidling multiple versions of buildroot in different directories, or otherwise starting from a clean slate, then this tip can save you a fair amount of time. I like to create a directory parallel to my gumstix-buildroot directory that I call dl-cache.

cd gumstix-buildroot mkdir ../dl-cache

If your gumstix-buildroot already has a dl directory then you can do this: cd gumstix-buildroot mv dl/* ../dl-cache rmdir dl

Finally, create a symbolic link from the dl directory to ../dl-cache cd gumstix-buildroot ln -s ../dl-cache dl

Now, when buildroot needs to download any files, they're be in the dl-cache directory. If you do a super clean: cd gumstix-buildroot rm -rf * svn update. ln -s ../dl-cache dl

then you will have saved yourself all of the tarballs which are in the dl-cache directory and you won't need to redownload them

Branching
If you want to create a branch out of the buildroot, in order to keep a parallel development tree of your own, please check this page: Buildroot_branching

Makeinfo "Missing"
If you see the following error: WARNING: `makeinfo' is missing on your system. You should only need it if       you modified a `.texi' or `.texinfo' file, or any other file indirectly affecting the aspect of the manual. The spurious call might also be the consequence of using a buggy `make' (AIX,       DU, IRIX). You might want to install the `Texinfo' package or       the `GNU make' package. Grab either from any GNU archive site.

1. Verify texinfo is installed. Locate and install the texinfo package on your build system. After installing texinfo, you should verify that the makeinfo command is in your PATH (i.e. type makeinfo on the command line and make sure it's not missing). Finally, do cd gumstix-buildroot rm -rf toolchain_build_arm_nofpu make

2. Workaround version check bug. If you still get the error message above AND you're sure that makeinfo is properly installed on your path, then type makeinfo --version If your makeinfo version is 4.11 or higher, then you may have encountered a well-known `binutils' bug. In short, the build scripts incorrectly thinks 4.11 is an older version than 4.4. If you are sure that you have a correct version of makeinfo, then you can manually remove this broken check.

In `gumstix-buildroot/toolchain_build_arm_nofpu/binutils-2.17.50.0.6-build/Makefile', find: MAKEINFO = /projects/eink/gumstix-buildroot/toolchain_build_arm_nofpu/binutils-2.17.50.0.6/missing makeinfo and change it to MAKEINFO = /usr/bin/makeinfo

See this thread for others ways to work around this bug, including a patch.

Behind a Proxy
If you are behind a proxy and are having trouble pulling down required files after running 'make': export http_proxy="http://proxy.example.com:8080"

Replace proxy.example.com with your actual proxy server. Replace 8080 with your actual proxy server port.

Also check your `.subversion/servers file. The proxy can be defined by editing the commented out entries near the end of the file.

http-proxy-host =  http-proxy-port =
 * 1) http-proxy-exceptions = *.exception.com, www.internal-site.org

Open /gumstix-buildroot/toolchain/getter_script.sh Edit the wget line (last line in my version) to read wget -Y on -nd ${a[@]}

Try running make again.