Advanced usage

Using the generated toolchain outside Buildroot

You may want to compile, for your target, 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 is located by default in output/host/. The simplest way to use it is to add output/host/bin/ to your PATH environment variable and then to use ARCH-linux-gcc, ARCH-linux-objdump, ARCH-linux-ld, etc.

Alternatively, Buildroot can also export the toolchain and the development files of all selected packages, as an SDK, by running the command make sdk. This generates a tarball of the content of the host directory output/host/, named <TARGET-TUPLE>_sdk-buildroot.tar.gz (which can be overriden by setting the environment variable BR2_SDK_PREFIX) and located in the output directory output/images/.

This tarball can then be distributed to application developers, when they want to develop their applications that are not (yet) packaged as a Buildroot package.

Upon extracting the SDK tarball, the user must run the script relocate-sdk.sh (located at the top directory of the SDK), to make sure all paths are updated with the new location.

Alternatively, if you just want to prepare the SDK without generating the tarball (e.g. because you will just be moving the host directory, or will be generating the tarball on your own), Buildroot also allows you to just prepare the SDK with make prepare-sdk without actually generating a tarball.

For your convenience, by selecting the option BR2_PACKAGE_HOST_ENVIRONMENT_SETUP, you can get a environment-setup script installed in output/host/ and therefore in your SDK. This script can be sourced with . your/sdk/path/environment-setup to export a number of environment variables that will help cross-compile your projects using the Buildroot SDK: the PATH will contain the SDK binaries, standard autotools variables will be defined with the appropriate values, and CONFIGURE_FLAGS will contain basic ./configure options to cross-compile autotools projects. It also provides some useful commands. Note however that once this script is sourced, the environment is setup only for cross-compilation, and no longer for native compilation.

Using gdb in Buildroot

Buildroot allows to do cross-debugging, where the debugger runs on the build machine and communicates with gdbserver on the target to control the execution of the program.

To achieve this:

• If you are using an internal toolchain (built by Buildroot), you must enable BR2_PACKAGE_HOST_GDB, BR2_PACKAGE_GDB and BR2_PACKAGE_GDB_SERVER. This ensures that both the cross gdb and gdbserver get built, and that gdbserver gets installed to your target.
• If you are using an external toolchain, you should enable BR2_TOOLCHAIN_EXTERNAL_GDB_SERVER_COPY, which will copy the gdbserver included with the external toolchain to the target. If your external toolchain does not have a cross gdb or gdbserver, it is also possible to let Buildroot build them, by enabling the same options as for the internal toolchain backend.

Now, to start debugging a program called foo, you should run on the target:

gdbserver :2345 foo

This will cause gdbserver to listen on TCP port 2345 for a connection from the cross gdb.

Then, on the host, you should start the cross gdb using the following command line:

<buildroot>/output/host/bin/<tuple>-gdb -x <buildroot>/output/staging/usr/share/buildroot/gdbinit foo

Of course, foo must be available in the current directory, built with debugging symbols. Typically you start this command from the directory where foo is built (and not from output/target/ as the binaries in that directory are stripped).

The <buildroot>/output/staging/usr/share/buildroot/gdbinit file will tell the cross gdb where to find the libraries of the target.

Finally, to connect to the target from the cross gdb:

(gdb) target remote <target ip address>:2345

Using ccache in Buildroot

ccache is a compiler cache. It stores the object files resulting from each compilation process, and is able to skip future compilation of the same source file (with same compiler and same arguments) by using the pre-existing object files. When doing almost identical builds from scratch a number of times, it can nicely speed up the build process.

ccache support is integrated in Buildroot. You just have to enable Enable compiler cache in Build options. This will automatically build ccache and use it for every host and target compilation.

The cache is located in $HOME/.buildroot-ccache. It is stored outside of Buildroot output directory so that it can be shared by separate Buildroot builds. If you want to get rid of the cache, simply remove this directory.

You can get statistics on the cache (its size, number of hits, misses, etc.) by running make ccache-stats.

The make target ccache-options and the CCACHE_OPTIONS variable provide more generic access to the ccache. For example

# set cache limit size
make CCACHE_OPTIONS="--max-size=5G" ccache-options
# zero statistics counters
make CCACHE_OPTIONS="--zero-stats" ccache-options

ccache makes a hash of the source files and of the compiler options. If a compiler option is different, the cached object file will not be used. Many compiler options, however, contain an absolute path to the staging directory. Because of this, building in a different output directory would lead to many cache misses.

To avoid this issue, buildroot has the Use relative paths option (BR2_CCACHE_USE_BASEDIR). This will rewrite all absolute paths that point inside the output directory into relative paths. Thus, changing the output directory no longer leads to cache misses.

A disadvantage of the relative paths is that they also end up to be relative paths in the object file. Therefore, for example, the debugger will no longer find the file, unless you cd to the output directory first.

See the ccache manual's section on "Compiling in different directories" for more details about this rewriting of absolute paths.

Location of downloaded packages

The various tarballs that are downloaded by Buildroot are all stored in BR2_DL_DIR, which by default is the dl directory. If you want to keep a complete version of Buildroot which is known to be working with the associated tarballs, you can make a copy of this directory. This will allow you to regenerate the toolchain and the target filesystem with exactly the same versions.

If you maintain several Buildroot trees, it might be better to have a shared download location. This can be achieved by pointing the BR2_DL_DIR environment variable to a directory. If this is set, then the value of BR2_DL_DIR in the Buildroot configuration is overridden. The following line should be added to <~/.bashrc>.

 export BR2_DL_DIR=<shared download location>

The download location can also be set in the .config file, with the BR2_DL_DIR option. Unlike most options in the .config file, this value is overridden by the BR2_DL_DIR environment variable.

Package-specific make targets

Running make <package> builds and installs that particular package and its dependencies.

For packages relying on the Buildroot infrastructure, there are numerous special make targets that can be called independently like this:

make <package>-<target>

The package build targets are (in the order they are executed):

Additionally, there are some other useful make targets:

Using Buildroot during development

The normal operation of Buildroot is to download a tarball, extract it, configure, compile and install the software component found inside this tarball. The source code is extracted in output/build/<package>-<version>, which is a temporary directory: whenever make clean is used, this directory is entirely removed, and re-created at the next make invocation. Even when a Git or Subversion repository is used as the input for the package source code, Buildroot creates a tarball out of it, and then behaves as it normally does with tarballs.

This behavior is well-suited when Buildroot is used mainly as an integration tool, to build and integrate all the components of an embedded Linux system. However, if one uses Buildroot during the development of certain components of the system, this behavior is not very convenient: one would instead like to make a small change to the source code of one package, and be able to quickly rebuild the system with Buildroot.

Making changes directly in output/build/<package>-<version> is not an appropriate solution, because this directory is removed on make clean.

Therefore, Buildroot provides a specific mechanism for this use case: the <pkg>_OVERRIDE_SRCDIR mechanism. Buildroot reads an override file, which allows the user to tell Buildroot the location of the source for certain packages.

The default location of the override file is $(CONFIG_DIR)/local.mk, as defined by the BR2_PACKAGE_OVERRIDE_FILE configuration option. $(CONFIG_DIR) is the location of the Buildroot .config file, so local.mk by default lives side-by-side with the .config file, which means:

• In the top-level Buildroot source directory for in-tree builds (i.e., when O= is not used)
• In the out-of-tree directory for out-of-tree builds (i.e., when O= is used)

If a different location than these defaults is required, it can be specified through the BR2_PACKAGE_OVERRIDE_FILE configuration option.

In this override file, Buildroot expects to find lines of the form:

<pkg1>_OVERRIDE_SRCDIR = /path/to/pkg1/sources
<pkg2>_OVERRIDE_SRCDIR = /path/to/pkg2/sources

For example:

LINUX_OVERRIDE_SRCDIR = /home/bob/linux/
BUSYBOX_OVERRIDE_SRCDIR = /home/bob/busybox/

When Buildroot finds that for a given package, an <pkg>_OVERRIDE_SRCDIR has been defined, it will no longer attempt to download, extract and patch the package. Instead, it will directly use the source code available in the specified directory and make clean will not touch this directory. This allows to point Buildroot to your own directories, that can be managed by Git, Subversion, or any other version control system. To achieve this, Buildroot will use rsync to copy the source code of the component from the specified <pkg>_OVERRIDE_SRCDIR to output/build/<package>-custom/.

This mechanism is best used in conjunction with the make <pkg>-rebuild and make <pkg>-reconfigure targets. A make <pkg>-rebuild all sequence will rsync the source code from <pkg>_OVERRIDE_SRCDIR to output/build/<package>-custom (thanks to rsync, only the modified files are copied), and restart the build process of just this package.

In the example of the linux package above, the developer can then make a source code change in /home/bob/linux and then run:

make linux-rebuild all

and in a matter of seconds gets the updated Linux kernel image in output/images. Similarly, a change can be made to the BusyBox source code in /home/bob/busybox, and after:

make busybox-rebuild all

the root filesystem image in output/images contains the updated BusyBox.

Source trees for big projects often contain hundreds or thousands of files which are not needed for building, but will slow down the process of copying the sources with rsync. Optionally, it is possible define <pkg>_OVERRIDE_SRCDIR_RSYNC_EXCLUSIONS to skip syncing certain files from the source tree. For example, when working on the webkitgtk package, the following will exclude the tests and in-tree builds from a local WebKit source tree:

WEBKITGTK_OVERRIDE_SRCDIR = /home/bob/WebKit
WEBKITGTK_OVERRIDE_SRCDIR_RSYNC_EXCLUSIONS = \
        --exclude JSTests --exclude ManualTests --exclude PerformanceTests \
        --exclude WebDriverTests --exclude WebKitBuild --exclude WebKitLibraries \
        --exclude WebKit.xcworkspace --exclude Websites --exclude Examples

By default, Buildroot skips syncing of VCS artifacts (e.g., the .git and .svn directories). Some packages prefer to have these VCS directories available during build, for example for automatically determining a precise commit reference for version information. To undo this built-in filtering at a cost of a slower speed, add these directories back:

LINUX_OVERRIDE_SRCDIR_RSYNC_EXCLUSIONS = --include .git