Buildroot
From GumstixDocsWiki
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Customers using Gumstix OpenEmbedded should go to gumstix.net and the related user wiki
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
For customers using buildroot:
The Buildroot is the system used to create flash filesystem images for use on the Gumstix.
With the Buildroot, anyone can 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
which svnat the command prompt. - A C compiler, such as
gccand 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:
[groups]
group1=*.gumstix.com
Edit group1:
[group1]
http-proxy-host = proxy1.some-domain-name.com
http-proxy-port = 80
http-proxy-username = <username>
http-proxy-password = <passwd>
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 rootfs.arm_nofpu.jffs2.
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:
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 gumstix-buildroot 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 gumstix-buildroot/build_arm_nofpu/root, or simply by erasing that whole directory -- the Buildroot will restore it when you next run make.
ATTENTION wifistix users-
If you delete the gumstix-buildroot/build_arm_nofpu/root directory then the wifistix support will not be properly re-installed unless you also delete the gumstix-buildroot/build_arm/.cf8385 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
Troubleshooting
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-exceptions = *.exception.com, www.internal-site.org http-proxy-host = <IP address of proxy server> http-proxy-port = <proxy html port>
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.
