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:

+ +