Buildroot

- -

Usage and documentation by Thomas Petazzoni. Contributions from - Karsten Kruse, Ned Ludd, Martin Herren.

- -

Last modification : $Id: buildroot-documentation.html,v 1.2 2004/12/28 19:15:20 andersen Exp $

- -

About Buildroot
Obtaining Buildroot
Using Buildroot
Customizing the target filesystem
Customizing the Busybox - configuration
Customizing the uClibc - configuration
How Buildroot works
Using the uClibc toolchain
Using the uClibc toolchain - outside of Buildroot
Location of downloaded packages
Extending Buildroot with more - Software
Ressources

- -

About Buildroot

- -

Buildroot is a set of Makefiles and patches that allows to easily - generate both a cross-compilation toolchain and a root filesystem for your - target. The cross-compilation toolchain uses uClibc (http://www.uclibc.org/), a tiny C standard - library.

- -

Buildroot is useful mainly for people working with embedded systems. - Embedded systems often use processors that are not the regular x86 - processors everyone is used to have on his PC. It can be PowerPC - processors, MIPS processors, ARM processors, etc.

- -

A compilation toolchain is the set of tools that allows to - compile code for your system. It consists of a compiler (in our - case, gcc), binary utils like assembler and linker - (in our case, binutils) and a C standard library (for - example GNU - Libc, uClibc or dietlibc). The system - installed on your development station certainly already has a - compilation toolchain that you can use to compile application that - runs on your system. If you're using a PC, your compilation - toolchain runs on an x86 processor and generates code for a x86 - processor. Under most Linux systems, the compilation toolchain - uses the GNU libc as C standard library. This compilation - toolchain is called the "host compilation toolchain", and more - generally, the machine on which it is running, and on which you're - working is called the "host system". The compilation toolchain is - provided by your distribution, and Buildroot has nothing to do - with it.

- -

As said above, the compilation toolchain that comes with your system - runs and generates code for the processor of your host system. As your - embedded system has a different processor, you need a cross-compilation - toolchain: it's a compilation toolchain that runs on your host system but - that generates code for your target system (and target processor). For - example, if your host system uses x86 and your target system uses ARM, the - regular compilation toolchain of your host runs on x86 and generates code - for x86, while the cross-compilation toolchain runs on x86 and generates - code for ARM.

- -

Even if your embedded system uses a x86 processor, you might interested - in Buildroot, for two reasons:

- -

The compilation toolchain of your host certainly uses the GNU Libc - which is a complete but huge C standard library. Instead of using GNU - Libc on your target system, you can use uClibc which is a tiny C standard - library. If you want to use this C library, then you need a compilation - toolchain to generate binaries linked with it. Buildroot can do it for - you.
Buildroot automates the building of a root filesystem with all needed - tools like busybox. It makes it much easier than doing it by hand.

- -

You might wonder why such a tool is needed when you can compile - gcc, binutils, uClibc and all the tools by hand. - Of course, doing so is possible. But dealing with all configure options, - with all problems of every gcc or binutils - version it very time-consuming and uninteresting. Buildroot automates this - process through the use of Makefiles, and has a collection of patches for - each gcc and binutils version to make them work - on most architectures.

- -

Obtaining Buildroot

- -

Buildroot is available as daily CVS snapshots or directly using - CVS.

- -

The latest snapshot is always available at http://uclibc.org/downloads/snapshots/buildroot-snapshot.tar.bz2, - and previous snapshots are also available at http://uclibc.org/downloads/snapshots/.

- -

To download Buildroot using CVS, you can simply follow - the rules described on the "Accessing CVS"-page (http://www.uclibc.org/cvs_anon.html) - of the uClibc website (http://www.uclibc.org), and download the - buildroot CVS module. For the impatient, here's a quick - recipe:

- -

- $ cvs -d:pserver:anonymous@uclibc.org:/var/cvs login
- $ cvs -z3 -d:pserver:anonymous@uclibc.org:/var/cvs co buildroot
-

- -

Using Buildroot

- -

Buildroot has a nice configuration tool similar to the one you can find - in the Linux Kernel (http://www.kernel.org/) or in Busybox - (http://www.busybox.org/). Note that - you can run everything as a normal user. There is no need to be root to - configure and use Buildroot. The first step is to run the configuration - assistant:

- -

- $ make menuconfig
-

- -

For each entry of the configuration tool, you can find associated help - that describes the purpose of the entry.

- -

Once everything is configured, the configuration tool has generated a - .config file that contains the description of your - configuration. It will be used by the Makefiles to do what's needed.

- -

Let's go:

- -

- $ make
-

- -

This command will download, configure and compile all the selected - tools, and finally generate a target filesystem. The target filesystem will - be named root_fs_ARCH.EXT where ARCH is your - architecture and EXT depends on the type of target filesystem - selected in the Target options section of the configuration - tool.

- -

Customizing the - target filesystem

- -

There are two ways to customize the resulting target filesystem:

- -

Customize the target filesystem directly, and rebuild the image. The - target filesystem is available under build_ARCH/root/ where - ARCH is the chosen target architecture. You can simply make - your changes here, and run make afterwards, which will rebuild the target - filesystem image. This method allows to do everything on the target - filesystem, but if you decide to completely rebuild your toolchain and - tools, these changes will be lost.
Customize the target filesystem skeleton, available under - target/default/target_skeleton/. You can customize - configuration files or other stuff here. However, the full file hierarchy - is not yet present, because it's created during the compilation process. - So you can't do everything on this target filesystem skeleton, but - changes to it remains even you completely rebuild the cross-compilation - toolchain and the tools.
- You can also customize the target/default/device_table.txt - file which is used by the tools that generate the target filesystem image - to properly set permissions and create device nodes. The - target/default/skel.tar.gz file contains the main - directories of a root filesystem and there is no obvious reason for which - it should be changed. These main directories are in an tarball inside of - inside the skeleton because it contains symlinks that would be broken - otherwise.

- -

Customizing the - Busybox configuration

- -

Busybox is very configurable, and you may want to customize it. You can - follow these simple steps to do it. It's not an optimal way, but it's - simple and it works.

- -

Make a first compilation of buildroot with busybox without trying to - customize it.
Go into build_ARCH/busybox/ and run make - menuconfig. The nice configuration tool appears and you can - customize everything.
Copy the .config file to - package/busybox/busybox.config so that your customized - configuration will remains even if you remove the cross-compilation - toolchain.
Run the compilation of buildroot again.

- -

Otherwise, you can simply change the - package/busybox/busybox.config file if you know the options - you want to change without using the configuration tool.

- -

Customizing the uClibc - configuration

- -

Just like BusyBox, uClibc offers a lot of - configuration options. They allow to select various - functionalities, depending on your needs and limitations.

- -

The easiest way to modify the configuration of uClibc is to - follow these steps :

- -

Make a first compilation of buildroot without trying to - customize uClibc.
Go into the directory - toolchain_build_ARCH/uClibc/ and run make - menuconfig. The nice configuration assistant, similar to - the one used in the Linux Kernel or in Buildroot appears. Make - your configuration as appropriate.
Copy the .config file to - toolchain/uClibc/uClibc.config or - toolchain/uClibc/uClibc.config-locale. The former - is used if you haven't selected locale support in Buildroot - configuration, and the latter is used if you have selected - locale support.
Run the compilation of Buildroot again

- -

Otherwise, you can simply change - toolchain/uClibc/uClibc.config or - toolchain/uClibc/uClibc.config-locale without running - the configuration assistant.

- -

How Buildroot - works

- -

As said above, Buildroot is basically a set of Makefiles that download, - configure and compiles software with the correct options. It also includes - some patches for various software, mainly the ones involved in the - cross-compilation tool chain (gcc, binutils and - uClibc).

- -

There is basically one Makefile per software, and they are named with - the .mk extension. Makefiles are split into three - sections:

- -

package (in the package/ directory) contains the - Makefiles and associated files for all user-space tools that Buildroot - can compile and add to the target root filesystem. There is one - sub-directory per tool.
toolchain (in the toolchain/ directory) contains - the Makefiles and associated files for all software related to the - cross-compilation toolchain : binutils, ccache, - gcc, gdb, kernel-headers and - uClibc.
target (in the target directory) contains the - Makefiles and associated files for software related to the generation of - the target root filesystem image. Four types of filesystems are supported - : ext2, jffs2, cramfs and squashfs. For each of them, there's a - sub-directory with the required files. There is also a - default/ directory that contains the target filesystem - skeleton.

- -

Each directory contains at least 2 files :

- -

something.mk is the Makefile that downloads, configures, - compiles and installs the software something.
Config.in is a part of the configuration tool - description file. It describes the option related to the current - software.

- -

The main Makefile do the job through the following steps (once the - configuration is done):

- -

Create the download directory (dl/ by default). This is - where the tarballs will be downloaded. It is interesting to know that the - tarballs are in this directory because it may be useful to save them - somewhere to avoid further downloads.
Create the build directory (build_ARCH/ by default, - where ARCH is your architecture). This is where all - user-space tools while be compiled.
Create the toolchain build directory - (toolchain_build_ARCH/ by default, where ARCH - is your architecture). This is where the cross compilation toolchain will - be compiled.
Setup the staging directory (build_ARCH/staging_dir/ by - default). This is where the cross-compilation toolchain will be - installed. If you want to use the same cross-compilation toolchain for - other purposes, such as compiling third-party applications, you can add - build_ARCH/staging_dir/bin to your PATH, and then use - arch-linux-gcc to compile your application. In order to - setup this staging directory, it first removes it, and then it creates - various subdirectories and symlinks inside it.
Create the target directory (build_ARCH/root/ by - default) and the target filesystem skeleton. This directory will contain - the final root filesystem. To setup it up, it first deletes it, then it - uncompress the target/default/skel.tar.gz file to create the - main subdirectories and symlinks, copies the skeleton available in - target/default/target_skeleton and then removes useless - CVS/ directories.
Add the TARGETS dependency. This should generally check - if the configuration option for this package is enabled, and if so then - "subscribe" this package to be compiled by adding it to the TARGETS - global variable.

- -

Using the - uClibc toolchain

- -

You may want to compile your own programs or other software - that are not packaged in Buildroot. In order to do this, you can - use the toolchain that was generated by Buildroot.

- -

The toolchain generated by Buildroot by default is located in - build_ARCH/staging_dir/. The simplest way to use it - is to add build_ARCH/staging_dir/bin/ to your PATH - environnement variable, and then to use - arch-linux-gcc, arch-linux-objdump, - arch-linux-ld, etc.

- -

For example, you may add the following to your - .bashrc (considering you're building for the MIPS - architecture and that Buildroot is located in - ~/buildroot/) :

- -

-export PATH=$PATH:~/buildroot/build_mips/bin/
-

- -

Then you can simply do :

- -

-mips-linux-gcc -o foo foo.c
-

- -

Important : do not try to move the toolchain to an other - directory, it won't work. There are some hard-coded paths in the - gcc configuration. If the default toolchain directory - doesn't suit your needs, please refer to the Using the uClibc toolchain outside of - buildroot section.

- -

Using the - uClibc toolchain outside of buildroot

- -

By default, the cross-compilation toolchain is generated inside - build_ARCH/staging_dir/. But sometimes, it may be useful to - install it somewhere else, so that it can be used to compile other programs - or by other users. Moving the build_ARCH/staging_dir/ - directory elsewhere is not possible, because they are some hardcoded - paths in the toolchain configuration.

- -

If you want to use the generated toolchain for other purposes, - you can configure Buildroot to generate it elsewhere using the - option of the configuration tool : Build options -> - Toolchain and header file location, which defaults to - $(BUILD_DIR)/staging_dir/.

- -

Location of downloaded packages

- -

It might be useful to know that the various tarballs that are - downloaded by the Makefiles are all stored in the - DL_DIR which by default is the dl - directory. It's useful for example if you want to keep a complete - version of Buildroot which is know to be working with the - associated tarballs. This will allow you to regenerate the - toolchain and the target filesystem with exactly the same - versions.

- -

Extending Buildroot with - more software

- -

This section will only consider the case in which you want to - add user-space software.

- -

Package directory

- -

First of all, create a directory under the package - directory for your software, for example foo.

- -

`Config.in` file

- -

Then, create a file named Config.in. This file - will contain the portion of options description related to our - foo software that will be used and displayed in the - configuration tool. It should basically contain :

- -

-config BR2_PACKAGE_FOO
-        bool "foo"
-        default n
-        help
-	     This is a comment that explains what foo is.
-

- -

Of course, you can add other options to configure particular - things in your software.

- -

The real Makefile

- -

Finally, here's the hardest part. Create a file named - foo.mk. It will contain the Makefile rules that - are in charge of downloading, configuring, compiling and installing - the software. Below is an example that we will comment - afterwards.

- -

-     1  #############################################################
-     2  #
-     3  # foo
-     4  #
-     5  #############################################################
-     6  FOO_VERSION:=1.0
-     7  FOO_SOURCE:=less-$(FOO_VERSION).tar.gz
-     8  FOO_SITE:=http://www.foosoftware.org/downloads
-     9  FOO_DIR:=$(BUILD_DIR)/less-$(FOO_VERSION)
-    10  FOO_BINARY:=foo
-    11  FOO_TARGET_BINARY:=usr/bin/foo
-    12
-    13  $(DL_DIR)/$(FOO_SOURCE):
-    14          $(WGET) -P $(DL_DIR) $(FOO_SITE)/$(FOO_SOURCE)
-    15
-    16  $(FOO_DIR)/.source: $(DL_DIR)/$(FOO_SOURCE)
-    17          zcat $(DL_DIR)/$(FOO_SOURCE) | tar -C $(BUILD_DIR) $(TAR_OPTIONS) -
-    18          touch $(FOO_DIR)/.source
-    19
-    20  $(FOO_DIR)/.configured: $(FOO_DIR)/.source
-    21          (cd $(FOO_DIR); \
-    22                  $(TARGET_CONFIGURE_OPTS) \
-    23                  CFLAGS="$(TARGET_CFLAGS)" \
-    24                  ./configure \
-    25                  --target=$(GNU_TARGET_NAME) \
-    26                  --host=$(GNU_TARGET_NAME) \
-    27                  --build=$(GNU_HOST_NAME) \
-    28                  --prefix=/usr \
-    29                  --sysconfdir=/etc \
-    30          );
-    31          touch $(FOO_DIR)/.configured;
-    32
-    33  $(FOO_DIR)/$(FOO_BINARY): $(FOO_DIR)/.configured
-    34          $(MAKE) CC=$(TARGET_CC) -C $(FOO_DIR)
-    35
-    36  $(TARGET_DIR)/$(FOO_TARGET_BINARY): $(FOO_DIR)/$(FOO_BINARY)
-    37          $(MAKE) prefix=$(TARGET_DIR)/usr -C $(FOO_DIR) install
-    38          rm -Rf $(TARGET_DIR)/usr/man
-    39
-    40  foo: uclibc ncurses $(TARGET_DIR)/$(FOO_TARGET_BINARY)
-    41
-    42  foo-source: $(DL_DIR)/$(FOO_SOURCE)
-    43
-    44  foo-clean:
-    45          $(MAKE) prefix=$(TARGET_DIR)/usr -C $(FOO_DIR) uninstall
-    46          -$(MAKE) -C $(FOO_DIR) clean
-    47
-    48  foo-dirclean:
-    49          rm -rf $(FOO_DIR)
-    50
-    51 #############################################################
-    52 #
-    53 # Toplevel Makefile options
-    54 #
-    55 #############################################################
-    56 ifeq ($(strip $(BR2_PACKAGE_FOO)),y)
-    57 TARGETS+=foo
-    58 endif
-
-

- -

First of all, this Makefile example works for a single - binary software. For other software such as libraries or more - complex stuff with multiple binaries, it should be adapted. Look at - the other *.mk files in the package - directory.

- -

At lines 6-11, a couple of useful variables are defined :

- -

FOO_VERSION : The version of foo that - should be downloaded.
FOO_SOURCE : The name of the tarball of - foo on the download website of FTP site. As you can see - FOO_VERSION is used.
FOO_SITE : The HTTP or FTP site from which - foo archive is downloaded. It must include the complete - path to the directory where FOO_SOURCE can be - found.
FOO_DIR : The directory into which the software - will be configured and compiled. Basically, it's a subdirectory - of BUILD_DIR which is created upon decompression of - the tarball.
FOO_BINARY : Software binary name. As said - previously, this is an example for a single binary software.
FOO_TARGET_BINARY : The full path of the binary - inside the target filesystem.

- -

Lines 13-14 defines a target that downloads the tarball from - the remote site to the download directory - (DL_DIR).

- -

Lines 16-18 defines a target and associated rules that - uncompress the downloaded tarball. As you can see, this target - depends on the tarball file, so that the previous target (line - 13-14) is called before executing the rules of the current - target. Uncompressing is followed by touching a hidden file - to mark the software has having been uncompressed. This trick is - used everywhere in Buildroot Makefile to split steps - (download, uncompress, configure, compile, install) while still - having correct dependencies.

- -

Lines 20-31 defines a target and associated rules that - configures the software. It depends on the previous target (the - hidden .source file) so that we are sure the software has - been uncompressed. In order to configure it, it basically runs the - well-known ./configurescript. As we may be doing - cross-compilation, target, host and - build arguments are given. The prefix is also set to - /usr, not because the software will be installed in - /usr on your host system, but in the target - filesystem. Finally it creates a .configured file to - mark the software as configured.

- -

Lines 33-34 defines a target and a rule that compiles the - software. This target will create the binary file in the - compilation directory, and depends on the software being already - configured (hence the reference to the .configured - file). It basically runs make inside the source - directory.

- -

Lines 36-38 defines a target and associated rules that install - the software inside the target filesystem. It depends on the - binary file in the source directory, to make sure the software has - been compiled. It uses the install target of the - software Makefile by passing a prefix - argument, so that the Makefile doesn't try to install - the software inside host /usr but inside target - /usr. After the installation, the - /usr/man directory inside the target filesystem is - removed to save space.

- -

Line 40 defines the main target of the software, the one - that will be eventually be used by the top level - Makefile to download, compile, and then install - this package. This target should first of all depends on all - needed dependecies of the software (in our example, - uclibc and ncurses), and also depend on the - final binary. This last dependency will call all previous - dependencies in the correct order.

- -

Line 42 defines a simple target that only downloads the code - source. This is not used during normal operation of Buildroot, but - might be useful.

- -

Lignes 44-46 define a simple target to clean the software build - by calling the Makefiles with the appropriate option.

- -

Lines 48-49 define a simple target to completely remove the - directory in which the software was uncompressed, configured and - compiled.

- -

Lines 51-58 adds the target foo to the list - of targets to be compiled by Buildroot by first checking if - the configuration option for this package has been enabled - using the configuration tool, and if so then "subscribes" - this package to be compiled by adding it to the TARGETS - global variable. The name added to the TARGETS global - variable is the name of this package's target, as defined on - line 40, which is used by Buildroot to download, compile, and - then install this package.

- - -

Conclusion

- -

As you can see, adding a software to buildroot is simply a - matter of writing a Makefile using an already existing - example and to modify it according to the compilation process of - the software.

- -

If you package software that might be useful for other persons, - don't forget to send a patch to Buildroot developers !

- -

Ressources

- -

To learn more about Buildroot you can visit these - websites:

- -