The internal toolchain backend is the backend where Buildroot builds by itself a cross-compilation toolchain, before building the userspace applications and libraries for your target embedded system.

This backend supports several C libraries: uClibc-ng, glibc and musl.

Once you have selected this backend, a number of options appear. The most important ones allow to:

It is worth noting that whenever one of those options is modified, then the entire toolchain and system must be rebuilt. See Section 8.2, “Understanding when a full rebuild is necessary”.

Advantages of this backend:

Drawbacks of this backend:

The external toolchain backend allows to use existing pre-built cross-compilation toolchains. Buildroot knows about a number of well-known cross-compilation toolchains (from Linaro for ARM, Sourcery CodeBench for ARM, x86-64, PowerPC, and MIPS, and is capable of downloading them automatically, or it can be pointed to a custom toolchain, either available for download or installed locally.

Then, you have three solutions to use an external toolchain:

Our external toolchain support has been tested with toolchains from CodeSourcery and Linaro, toolchains generated by crosstool-NG, and toolchains generated by Buildroot itself. In general, all toolchains that support the sysroot feature should work. If not, do not hesitate to contact the developers.

We do not support toolchains or SDK generated by OpenEmbedded or Yocto, because these toolchains are not pure toolchains (i.e. just the compiler, binutils, the C and C++ libraries). Instead these toolchains come with a very large set of pre-compiled libraries and programs. Therefore, Buildroot cannot import the sysroot of the toolchain, as it would contain hundreds of megabytes of pre-compiled libraries that are normally built by Buildroot.

We also do not support using the distribution toolchain (i.e. the gcc/binutils/C library installed by your distribution) as the toolchain to build software for the target. This is because your distribution toolchain is not a "pure" toolchain (i.e. only with the C/C++ library), so we cannot import it properly into the Buildroot build environment. So even if you are building a system for a x86 or x86_64 target, you have to generate a cross-compilation toolchain with Buildroot or crosstool-NG.

If you want to generate a custom toolchain for your project, that can be used as an external toolchain in Buildroot, our recommendation is to build it either with Buildroot itself (see Section 6.1.3, “Build an external toolchain with Buildroot”) or with crosstool-NG.

Advantages of this backend:

Drawbacks of this backend:

The Buildroot internal toolchain option can be used to create an external toolchain. Here are a series of steps to build an internal toolchain and package it up for reuse by Buildroot itself (or other projects).

Create a new Buildroot configuration, with the following details:

Then, we can trigger the build, and also ask Buildroot to generate a SDK. This will conveniently generate for us a tarball which contains our toolchain:

make sdk

This produces the SDK tarball in $(O)/images, with a name similar to arm-buildroot-linux-uclibcgnueabi_sdk-buildroot.tar.gz. Save this tarball, as it is now the toolchain that you can re-use as an external toolchain in other Buildroot projects.

In those other Buildroot projects, in the Toolchain menu:

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.

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:

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

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.

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.

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:

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:

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

It is quite common for a user to have several related projects that partly need the same customizations. Instead of duplicating these customizations for each project, it is recommended to use a layered customization approach, as explained in this section.

Almost all of the customization methods available in Buildroot, like post-build scripts and root filesystem overlays, accept a space-separated list of items. The specified items are always treated in order, from left to right. By creating more than one such item, one for the common customizations and another one for the really project-specific customizations, you can avoid unnecessary duplication. Each layer is typically embodied by a separate directory inside board/<company>/. Depending on your projects, you could even introduce more than two layers.

An example directory structure for where a user has two customization layers common and fooboard is:

+-- board/
    +-- <company>/
        +-- common/
        |   +-- post_build.sh
        |   +-- rootfs_overlay/
        |   |   +-- ...
        |   +-- patches/
        |       +-- ...
        |
        +-- fooboard/
            +-- linux.config
            +-- busybox.config
            +-- <other configuration files>
            +-- post_build.sh
            +-- rootfs_overlay/
            |   +-- ...
            +-- patches/
                +-- ...

For example, if the user has the BR2_GLOBAL_PATCH_DIR configuration option set as:

BR2_GLOBAL_PATCH_DIR="board/<company>/common/patches board/<company>/fooboard/patches"

then first the patches from the common layer would be applied, followed by the patches from the fooboard layer.

A br2-external tree must contain at least those three files, described in the following chapters:

Apart from those mandatory files, there may be additional and optional content that may be present in a br2-external tree, like the configs/ or provides/ directories. They are described in the following chapters as well.

A complete example br2-external tree layout is also described later.

source "$BR2_EXTERNAL_BAR_42_PATH/package/package1/Config.in"
source "$BR2_EXTERNAL_BAR_42_PATH/package/package2/Config.in"

include $(sort $(wildcard $(BR2_EXTERNAL_BAR_42_PATH)/package/*/*.mk))

BR2_GLOBAL_PATCH_DIR=$(BR2_EXTERNAL_BAR_42_PATH)/patches/
BR2_ROOTFS_OVERLAY=$(BR2_EXTERNAL_BAR_42_PATH)/board/<boardname>/overlay/
BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE=$(BR2_EXTERNAL_BAR_42_PATH)/board/<boardname>/kernel.config

/path/to/br2-ext-tree/
  |- external.desc
  |     |name: BAR_42
  |     |desc: Example br2-external tree
  |     `----
  |
  |- Config.in
  |     |source "$BR2_EXTERNAL_BAR_42_PATH/toolchain/toolchain-external-mine/Config.in.options"
  |     |source "$BR2_EXTERNAL_BAR_42_PATH/package/pkg-1/Config.in"
  |     |source "$BR2_EXTERNAL_BAR_42_PATH/package/pkg-2/Config.in"
  |     |source "$BR2_EXTERNAL_BAR_42_PATH/package/my-jpeg/Config.in"
  |     |
  |     |config BAR_42_FLASH_ADDR
  |     |    hex "my-board flash address"
  |     |    default 0x10AD
  |     `----
  |
  |- external.mk
  |     |include $(sort $(wildcard $(BR2_EXTERNAL_BAR_42_PATH)/package/*/*.mk))
  |     |include $(sort $(wildcard $(BR2_EXTERNAL_BAR_42_PATH)/toolchain/*/*.mk))
  |     |
  |     |flash-my-board:
  |     |    $(BR2_EXTERNAL_BAR_42_PATH)/board/my-board/flash-image \
  |     |        --image $(BINARIES_DIR)/image.bin \
  |     |        --address $(BAR_42_FLASH_ADDR)
  |     `----
  |
  |- package/pkg-1/Config.in
  |     |config BR2_PACKAGE_PKG_1
  |     |    bool "pkg-1"
  |     |    help
  |     |      Some help about pkg-1
  |     `----
  |- package/pkg-1/pkg-1.hash
  |- package/pkg-1/pkg-1.mk
  |     |PKG_1_VERSION = 1.2.3
  |     |PKG_1_SITE = /some/where/to/get/pkg-1
  |     |PKG_1_LICENSE = blabla
  |     |
  |     |define PKG_1_INSTALL_INIT_SYSV
  |     |    $(INSTALL) -D -m 0755 $(PKG_1_PKGDIR)/S99my-daemon \
  |     |                          $(TARGET_DIR)/etc/init.d/S99my-daemon
  |     |endef
  |     |
  |     |$(eval $(autotools-package))
  |     `----
  |- package/pkg-1/S99my-daemon
  |
  |- package/pkg-2/Config.in
  |- package/pkg-2/pkg-2.hash
  |- package/pkg-2/pkg-2.mk
  |
  |- provides/jpeg.in
  |     |config BR2_PACKAGE_MY_JPEG
  |     |    bool "my-jpeg"
  |     `----
  |- package/my-jpeg/Config.in
  |     |config BR2_PACKAGE_PROVIDES_JPEG
  |     |    default "my-jpeg" if BR2_PACKAGE_MY_JPEG
  |     `----
  |- package/my-jpeg/my-jpeg.mk
  |     |# This is a normal package .mk file
  |     |MY_JPEG_VERSION = 1.2.3
  |     |MY_JPEG_SITE = https://example.net/some/place
  |     |MY_JPEG_PROVIDES = jpeg
  |     |$(eval $(autotools-package))
  |     `----
  |
  |- provides/toolchains.in
  |     |config BR2_TOOLCHAIN_EXTERNAL_MINE
  |     |    bool "my custom toolchain"
  |     |    depends on BR2_some_arch
  |     |    select BR2_INSTALL_LIBSTDCPP
  |     `----
  |- toolchain/toolchain-external-mine/Config.in.options
  |     |if BR2_TOOLCHAIN_EXTERNAL_MINE
  |     |config BR2_TOOLCHAIN_EXTERNAL_PREFIX
  |     |    default "arch-mine-linux-gnu"
  |     |config BR2_PACKAGE_PROVIDES_TOOLCHAIN_EXTERNAL
  |     |    default "toolchain-external-mine"
  |     |endif
  |     `----
  |- toolchain/toolchain-external-mine/toolchain-external-mine.mk
  |     |TOOLCHAIN_EXTERNAL_MINE_SITE = https://example.net/some/place
  |     |TOOLCHAIN_EXTERNAL_MINE_SOURCE = my-toolchain.tar.gz
  |     |$(eval $(toolchain-external-package))
  |     `----
  |
  |- linux/Config.ext.in
  |     |config BR2_LINUX_KERNEL_EXT_EXAMPLE_DRIVER
  |     |    bool "example-external-driver"
  |     |    help
  |     |      Example external driver
  |     |---
  |- linux/linux-ext-example-driver.mk
  |
  |- configs/my-board_defconfig
  |     |BR2_GLOBAL_PATCH_DIR="$(BR2_EXTERNAL_BAR_42_PATH)/patches/"
  |     |BR2_ROOTFS_OVERLAY="$(BR2_EXTERNAL_BAR_42_PATH)/board/my-board/overlay/"
  |     |BR2_ROOTFS_POST_IMAGE_SCRIPT="$(BR2_EXTERNAL_BAR_42_PATH)/board/my-board/post-image.sh"
  |     |BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE="$(BR2_EXTERNAL_BAR_42_PATH)/board/my-board/kernel.config"
  |     `----
  |
  |- patches/linux/0001-some-change.patch
  |- patches/linux/0002-some-other-change.patch
  |- patches/busybox/0001-fix-something.patch
  |
  |- board/my-board/kernel.config
  |- board/my-board/overlay/var/www/index.html
  |- board/my-board/overlay/var/www/my.css
  |- board/my-board/flash-image
  `- board/my-board/post-image.sh
        |#!/bin/sh
        |generate-my-binary-image \
        |    --root ${BINARIES_DIR}/rootfs.tar \
        |    --kernel ${BINARIES_DIR}/zImage \
        |    --dtb ${BINARIES_DIR}/my-board.dtb \
        |    --output ${BINARIES_DIR}/image.bin
        `----

External options  --->
    *** Example br2-external tree (in /path/to/br2-ext-tree/)
    [ ] pkg-1
    [ ] pkg-2
    (0x10AD) my-board flash address

External options  --->
    Example br2-external tree  --->
        *** Example br2-external tree (in /path/to/br2-ext-tree)
        [ ] pkg-1
        [ ] pkg-2
        (0x10AD) my-board flash address
    FOO_27  --->
        *** FOO_27 (in /path/to/another-br2-ext)
        [ ] foo
        [ ] bar

Target packages  --->
    Libraries  --->
        Graphics  --->
            [*] jpeg support
                jpeg variant ()  --->
                    ( ) jpeg
                    ( ) jpeg-turbo
                        *** jpeg from: Example br2-external tree ***
                    (X) my-jpeg
                        *** jpeg from: FOO_27 ***
                    ( ) another-jpeg

Toolchain  --->
    Toolchain ()  --->
        ( ) Custom toolchain
            *** Toolchains from: Example br2-external tree ***
        (X) my custom toolchain

Sometimes it is needed to set specific permissions or ownership on files or device nodes. For example, certain files may need to be owned by root. Since the post-build scripts are not run as root, you cannot do such changes from there unless you use an explicit fakeroot from the post-build script.

Instead, Buildroot provides support for so-called permission tables. To use this feature, set config option BR2_ROOTFS_DEVICE_TABLE to a space-separated list of permission tables, regular text files following the makedev syntax.

If you are using a static device table (i.e. not using devtmpfs, mdev, or (e)udev) then you can add device nodes using the same syntax, in so-called device tables. To use this feature, set config option BR2_ROOTFS_STATIC_DEVICE_TABLE to a space-separated list of device tables.

As shown in Section 9.1, “Recommended directory structure”, the recommended location for such files is board/<company>/<boardname>/.

It should be noted that if the specific permissions or device nodes are related to a specific application, you should set variables FOO_PERMISSIONS and FOO_DEVICES in the package’s .mk file instead (see Section 17.5.2, “generic-package reference”).

Buildroot also bundles patch files, which are applied to the sources of the various packages. Those patches are not covered by the license of Buildroot. Instead, they are covered by the license of the software to which the patches are applied. When said software is available under multiple licenses, the Buildroot patches are only provided under the publicly accessible licenses.

See Chapter 18, Patching a package for the technical details.

To achieve NFS-boot, enable tar root filesystem in the Filesystem images menu.

After a complete build, just run the following commands to setup the NFS-root directory:

sudo tar -xavf /path/to/output_dir/rootfs.tar -C /path/to/nfs_root_dir

Remember to add this path to /etc/exports.

Then, you can execute a NFS-boot from your target.

To build a live CD image, enable the iso image option in the Filesystem images menu. Note that this option is only available on the x86 and x86-64 architectures, and if you are building your kernel with Buildroot.

You can build a live CD image with either IsoLinux, Grub or Grub 2 as a bootloader, but only Isolinux supports making this image usable both as a live CD and live USB (through the Build hybrid image option).

You can test your live CD image using QEMU:

qemu-system-i386 -cdrom output/images/rootfs.iso9660

Or use it as a hard-drive image if it is a hybrid ISO:

qemu-system-i386 -hda output/images/rootfs.iso9660

It can be easily flashed to a USB drive with dd:

dd if=output/images/rootfs.iso9660 of=/dev/sdb

For packages used on the target, create a file named Config.in. This file will contain the option descriptions related to our libfoo software that will be used and displayed in the configuration tool. It should basically contain:

config BR2_PACKAGE_LIBFOO
        bool "libfoo"
        help
          This is a comment that explains what libfoo is. The help text
          should be wrapped.

          http://foosoftware.org/libfoo/

The bool line, help line and other metadata information about the configuration option must be indented with one tab. The help text itself should be indented with one tab and two spaces, lines should be wrapped to fit 72 columns, where tab counts for 8, so 62 characters in the text itself. The help text must mention the upstream URL of the project after an empty line.

As a convention specific to Buildroot, the ordering of the attributes is as follows:

You can add other sub-options into a if BR2_PACKAGE_LIBFOO…endif statement to configure particular things in your software. You can look at examples in other packages. The syntax of the Config.in file is the same as the one for the kernel Kconfig file. The documentation for this syntax is available at http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt

Finally you have to add your new libfoo/Config.in to package/Config.in (or in a category subdirectory if you decided to put your package in one of the existing categories). The files included there are sorted alphabetically per category and are NOT supposed to contain anything but the bare name of the package.

source "package/libfoo/Config.in"

Some packages also need to be built for the host system. There are two options here:

The Config.in file of your package must also ensure that dependencies are enabled. Typically, Buildroot uses the following rules:

Note. The current problem with the kconfig language is that these two dependency semantics are not internally linked. Therefore, it may be possible to select a package, whom one of its dependencies/requirement is not met.

An example illustrates both the usage of select and depends on.

config BR2_PACKAGE_RRDTOOL
        bool "rrdtool"
        depends on BR2_USE_WCHAR
        select BR2_PACKAGE_FREETYPE
        select BR2_PACKAGE_LIBART
        select BR2_PACKAGE_LIBPNG
        select BR2_PACKAGE_ZLIB
        help
          RRDtool is the OpenSource industry standard, high performance
          data logging and graphing system for time series data.

          http://oss.oetiker.ch/rrdtool/

comment "rrdtool needs a toolchain w/ wchar"
        depends on !BR2_USE_WCHAR

Note that these two dependency types are only transitive with the dependencies of the same kind.

This means, in the following example:

config BR2_PACKAGE_A
        bool "Package A"

config BR2_PACKAGE_B
        bool "Package B"
        depends on BR2_PACKAGE_A

config BR2_PACKAGE_C
        bool "Package C"
        depends on BR2_PACKAGE_B

config BR2_PACKAGE_D
        bool "Package D"
        select BR2_PACKAGE_B

config BR2_PACKAGE_E
        bool "Package E"
        select BR2_PACKAGE_D

config BR2_PACKAGE_D
        bool "Package D"
        select BR2_PACKAGE_B
        depends on BR2_PACKAGE_A

config BR2_PACKAGE_E
        bool "Package E"
        select BR2_PACKAGE_D
        depends on BR2_PACKAGE_A

Overall, for package library dependencies, select should be preferred.

Note that such dependencies will ensure that the dependency option is also enabled, but not necessarily built before your package. To do so, the dependency also needs to be expressed in the .mk file of the package.

Further formatting details: see the coding style.

Many packages depend on certain options of the toolchain: the choice of C library, C++ support, thread support, RPC support, wchar support, or dynamic library support. Some packages can only be built on certain target architectures, or if an MMU is available in the processor.

These dependencies have to be expressed with the appropriate depends on statements in the Config.in file. Additionally, for dependencies on toolchain options, a comment should be displayed when the option is not enabled, so that the user knows why the package is not available. Dependencies on target architecture or MMU support should not be made visible in a comment: since it is unlikely that the user can freely choose another target, it makes little sense to show these dependencies explicitly.

The comment should only be visible if the config option itself would be visible when the toolchain option dependencies are met. This means that all other dependencies of the package (including dependencies on target architecture and MMU support) have to be repeated on the comment definition. To keep it clear, the depends on statement for these non-toolchain option should be kept separate from the depends on statement for the toolchain options. If there is a dependency on a config option in that same file (typically the main package) it is preferable to have a global if … endif construct rather than repeating the depends on statement on the comment and other config options.

The general format of a dependency comment for package foo is:

foo needs a toolchain w/ featA, featB, featC

for example:

mpd needs a toolchain w/ C++, threads, wchar

or

crda needs a toolchain w/ threads

Note that this text is kept brief on purpose, so that it will fit on a 80-character terminal.

The rest of this section enumerates the different target and toolchain options, the corresponding config symbols to depend on, and the text to use in the comment.

Some packages need a Linux kernel to be built by buildroot. These are typically kernel modules or firmware. A comment should be added in the Config.in file to express this dependency, similar to dependencies on toolchain options. The general format is:

foo needs a Linux kernel to be built

If there is a dependency on both toolchain options and the Linux kernel, use this format:

foo needs a toolchain w/ featA, featB, featC and a Linux kernel to be built

If a package needs udev /dev management, it should depend on symbol BR2_PACKAGE_HAS_UDEV, and the following comment should be added:

foo needs udev /dev management

If there is a dependency on both toolchain options and udev /dev management, use this format:

foo needs udev /dev management and a toolchain w/ featA, featB, featC

Some features can be provided by more than one package, such as the openGL libraries.

See Section 17.11, “Infrastructure for virtual packages” for more on the virtual packages.

01: ################################################################################
02: #
03: # libfoo
04: #
05: ################################################################################
06:
07: LIBFOO_VERSION = 1.0
08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
09: LIBFOO_SITE = http://www.foosoftware.org/download
10: LIBFOO_LICENSE = GPL-3.0+
11: LIBFOO_LICENSE_FILES = COPYING
12: LIBFOO_INSTALL_STAGING = YES
13: LIBFOO_CONFIG_SCRIPTS = libfoo-config
14: LIBFOO_DEPENDENCIES = host-libaaa libbbb
15:
16: define LIBFOO_BUILD_CMDS
17:     $(MAKE) $(TARGET_CONFIGURE_OPTS) -C $(@D) all
18: endef
19:
20: define LIBFOO_INSTALL_STAGING_CMDS
21:     $(INSTALL) -D -m 0755 $(@D)/libfoo.a $(STAGING_DIR)/usr/lib/libfoo.a
22:     $(INSTALL) -D -m 0644 $(@D)/foo.h $(STAGING_DIR)/usr/include/foo.h
23:     $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(STAGING_DIR)/usr/lib
24: endef
25:
26: define LIBFOO_INSTALL_TARGET_CMDS
27:     $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(TARGET_DIR)/usr/lib
28:     $(INSTALL) -d -m 0755 $(TARGET_DIR)/etc/foo.d
29: endef
30:
31: define LIBFOO_USERS
32:     foo -1 libfoo -1 * - - - LibFoo daemon
33: endef
34:
35: define LIBFOO_DEVICES
36:     /dev/foo  c  666  0  0  42  0  -  -  -
37: endef
38:
39: define LIBFOO_PERMISSIONS
40:     /bin/foo  f  4755  foo  libfoo   -  -  -  -  -
41: endef
42:
43: $(eval $(generic-package))

The Makefile begins on line 7 to 11 with metadata information: the version of the package (LIBFOO_VERSION), the name of the tarball containing the package (LIBFOO_SOURCE) (xz-ed tarball recommended) the Internet location at which the tarball can be downloaded from (LIBFOO_SITE), the license (LIBFOO_LICENSE) and file with the license text (LIBFOO_LICENSE_FILES). All variables must start with the same prefix, LIBFOO_ in this case. This prefix is always the uppercased version of the package name (see below to understand where the package name is defined).

On line 12, we specify that this package wants to install something to the staging space. This is often needed for libraries, since they must install header files and other development files in the staging space. This will ensure that the commands listed in the LIBFOO_INSTALL_STAGING_CMDS variable will be executed.

On line 13, we specify that there is some fixing to be done to some of the libfoo-config files that were installed during LIBFOO_INSTALL_STAGING_CMDS phase. These *-config files are executable shell script files that are located in $(STAGING_DIR)/usr/bin directory and are executed by other 3rd party packages to find out the location and the linking flags of this particular package.

The problem is that all these *-config files by default give wrong, host system linking flags that are unsuitable for cross-compiling.

For example: -I/usr/include instead of -I$(STAGING_DIR)/usr/include or: -L/usr/lib instead of -L$(STAGING_DIR)/usr/lib

So some sed magic is done to these scripts to make them give correct flags. The argument to be given to LIBFOO_CONFIG_SCRIPTS is the file name(s) of the shell script(s) needing fixing. All these names are relative to $(STAGING_DIR)/usr/bin and if needed multiple names can be given.

In addition, the scripts listed in LIBFOO_CONFIG_SCRIPTS are removed from $(TARGET_DIR)/usr/bin, since they are not needed on the target.

DIVINE_CONFIG_SCRIPTS = divine-config

IMAGEMAGICK_CONFIG_SCRIPTS = \
   Magick-config Magick++-config \
   MagickCore-config MagickWand-config Wand-config

On line 14, we specify the list of dependencies this package relies on. These dependencies are listed in terms of lower-case package names, which can be packages for the target (without the host- prefix) or packages for the host (with the host-) prefix). Buildroot will ensure that all these packages are built and installed before the current package starts its configuration.

The rest of the Makefile, lines 16..29, defines what should be done at the different steps of the package configuration, compilation and installation. LIBFOO_BUILD_CMDS tells what steps should be performed to build the package. LIBFOO_INSTALL_STAGING_CMDS tells what steps should be performed to install the package in the staging space. LIBFOO_INSTALL_TARGET_CMDS tells what steps should be performed to install the package in the target space.

All these steps rely on the $(@D) variable, which contains the directory where the source code of the package has been extracted.

On lines 31..33, we define a user that is used by this package (e.g. to run a daemon as non-root) (LIBFOO_USERS).

On line 35..37, we define a device-node file used by this package (LIBFOO_DEVICES).

On line 39..41, we define the permissions to set to specific files installed by this package (LIBFOO_PERMISSIONS).

Finally, on line 43, we call the generic-package function, which generates, according to the variables defined previously, all the Makefile code necessary to make your package working.

There are two variants of the generic target. The generic-package macro is used for packages to be cross-compiled for the target. The host-generic-package macro is used for host packages, natively compiled for the host. It is possible to call both of them in a single .mk file: once to create the rules to generate a target package and once to create the rules to generate a host package:

$(eval $(generic-package))
$(eval $(host-generic-package))

This might be useful if the compilation of the target package requires some tools to be installed on the host. If the package name is libfoo, then the name of the package for the target is also libfoo, while the name of the package for the host is host-libfoo. These names should be used in the DEPENDENCIES variables of other packages, if they depend on libfoo or host-libfoo.

The call to the generic-package and/or host-generic-package macro must be at the end of the .mk file, after all variable definitions. The call to host-generic-package must be after the call to generic-package, if any.

For the target package, the generic-package uses the variables defined by the .mk file and prefixed by the uppercased package name: LIBFOO_*. host-generic-package uses the HOST_LIBFOO_* variables. For some variables, if the HOST_LIBFOO_ prefixed variable doesn’t exist, the package infrastructure uses the corresponding variable prefixed by LIBFOO_. This is done for variables that are likely to have the same value for both the target and host packages. See below for details.

The list of variables that can be set in a .mk file to give metadata information is (assuming the package name is libfoo) :

# 0001-fix-cve-2020-12345.patch
LIBFOO_IGNORE_CVES += CVE-2020-12345
# only when built with libbaz, which Buildroot doesn't support
LIBFOO_IGNORE_CVES += CVE-2020-54321

The recommended way to define these variables is to use the following syntax:

LIBFOO_VERSION = 2.32

Now, the variables that define what should be performed at the different steps of the build process.

The preferred way to define these variables is:

define LIBFOO_CONFIGURE_CMDS
        action 1
        action 2
        action 3
endef

In the action definitions, you can use the following variables:

Finally, you can also use hooks. See Section 17.21, “Hooks available in the various build steps” for more information.

First, let’s see how to write a .mk file for an autotools-based package, with an example :

01: ################################################################################
02: #
03: # libfoo
04: #
05: ################################################################################
06:
07: LIBFOO_VERSION = 1.0
08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
09: LIBFOO_SITE = http://www.foosoftware.org/download
10: LIBFOO_INSTALL_STAGING = YES
11: LIBFOO_INSTALL_TARGET = NO
12: LIBFOO_CONF_OPTS = --disable-shared
13: LIBFOO_DEPENDENCIES = libglib2 host-pkgconf
14:
15: $(eval $(autotools-package))

On line 7, we declare the version of the package.

On line 8 and 9, we declare the name of the tarball (xz-ed tarball recommended) and the location of the tarball on the Web. Buildroot will automatically download the tarball from this location.

On line 10, we tell Buildroot to install the package to the staging directory. The staging directory, located in output/staging/ is the directory where all the packages are installed, including their development files, etc. By default, packages are not installed to the staging directory, since usually, only libraries need to be installed in the staging directory: their development files are needed to compile other libraries or applications depending on them. Also by default, when staging installation is enabled, packages are installed in this location using the make install command.

On line 11, we tell Buildroot to not install the package to the target directory. This directory contains what will become the root filesystem running on the target. For purely static libraries, it is not necessary to install them in the target directory because they will not be used at runtime. By default, target installation is enabled; setting this variable to NO is almost never needed. Also by default, packages are installed in this location using the make install command.

On line 12, we tell Buildroot to pass a custom configure option, that will be passed to the ./configure script before configuring and building the package.

On line 13, we declare our dependencies, so that they are built before the build process of our package starts.

Finally, on line line 15, we invoke the autotools-package macro that generates all the Makefile rules that actually allows the package to be built.

The main macro of the autotools package infrastructure is autotools-package. It is similar to the generic-package macro. The ability to have target and host packages is also available, with the host-autotools-package macro.

Just like the generic infrastructure, the autotools infrastructure works by defining a number of variables before calling the autotools-package macro.

First, all the package metadata information variables that exist in the generic infrastructure also exist in the autotools infrastructure: LIBFOO_VERSION, LIBFOO_SOURCE, LIBFOO_PATCH, LIBFOO_SITE, LIBFOO_SUBDIR, LIBFOO_DEPENDENCIES, LIBFOO_INSTALL_STAGING, LIBFOO_INSTALL_TARGET.

A few additional variables, specific to the autotools infrastructure, can also be defined. Many of them are only useful in very specific cases, typical packages will therefore only use a few of them.

With the autotools infrastructure, all the steps required to build and install the packages are already defined, and they generally work well for most autotools-based packages. However, when required, it is still possible to customize what is done in any particular step:

First, let’s see how to write a .mk file for a CMake-based package, with an example :

01: ################################################################################
02: #
03: # libfoo
04: #
05: ################################################################################
06:
07: LIBFOO_VERSION = 1.0
08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
09: LIBFOO_SITE = http://www.foosoftware.org/download
10: LIBFOO_INSTALL_STAGING = YES
11: LIBFOO_INSTALL_TARGET = NO
12: LIBFOO_CONF_OPTS = -DBUILD_DEMOS=ON
13: LIBFOO_DEPENDENCIES = libglib2 host-pkgconf
14:
15: $(eval $(cmake-package))

On line 7, we declare the version of the package.

On line 8 and 9, we declare the name of the tarball (xz-ed tarball recommended) and the location of the tarball on the Web. Buildroot will automatically download the tarball from this location.

On line 10, we tell Buildroot to install the package to the staging directory. The staging directory, located in output/staging/ is the directory where all the packages are installed, including their development files, etc. By default, packages are not installed to the staging directory, since usually, only libraries need to be installed in the staging directory: their development files are needed to compile other libraries or applications depending on them. Also by default, when staging installation is enabled, packages are installed in this location using the make install command.

On line 11, we tell Buildroot to not install the package to the target directory. This directory contains what will become the root filesystem running on the target. For purely static libraries, it is not necessary to install them in the target directory because they will not be used at runtime. By default, target installation is enabled; setting this variable to NO is almost never needed. Also by default, packages are installed in this location using the make install command.

On line 12, we tell Buildroot to pass custom options to CMake when it is configuring the package.

On line 13, we declare our dependencies, so that they are built before the build process of our package starts.

Finally, on line line 15, we invoke the cmake-package macro that generates all the Makefile rules that actually allows the package to be built.

The main macro of the CMake package infrastructure is cmake-package. It is similar to the generic-package macro. The ability to have target and host packages is also available, with the host-cmake-package macro.

Just like the generic infrastructure, the CMake infrastructure works by defining a number of variables before calling the cmake-package macro.

First, all the package metadata information variables that exist in the generic infrastructure also exist in the CMake infrastructure: LIBFOO_VERSION, LIBFOO_SOURCE, LIBFOO_PATCH, LIBFOO_SITE, LIBFOO_SUBDIR, LIBFOO_DEPENDENCIES, LIBFOO_INSTALL_STAGING, LIBFOO_INSTALL_TARGET.

A few additional variables, specific to the CMake infrastructure, can also be defined. Many of them are only useful in very specific cases, typical packages will therefore only use a few of them.

With the CMake infrastructure, all the steps required to build and install the packages are already defined, and they generally work well for most CMake-based packages. However, when required, it is still possible to customize what is done in any particular step:

First, let’s see how to write a .mk file for a Python package, with an example :

01: ################################################################################
02: #
03: # python-foo
04: #
05: ################################################################################
06:
07: PYTHON_FOO_VERSION = 1.0
08: PYTHON_FOO_SOURCE = python-foo-$(PYTHON_FOO_VERSION).tar.xz
09: PYTHON_FOO_SITE = http://www.foosoftware.org/download
10: PYTHON_FOO_LICENSE = BSD-3-Clause
11: PYTHON_FOO_LICENSE_FILES = LICENSE
12: PYTHON_FOO_ENV = SOME_VAR=1
13: PYTHON_FOO_DEPENDENCIES = libmad
14: PYTHON_FOO_SETUP_TYPE = distutils
15:
16: $(eval $(python-package))

On line 7, we declare the version of the package.

On line 8 and 9, we declare the name of the tarball (xz-ed tarball recommended) and the location of the tarball on the Web. Buildroot will automatically download the tarball from this location.

On line 10 and 11, we give licensing details about the package (its license on line 10, and the file containing the license text on line 11).

On line 12, we tell Buildroot to pass custom options to the Python setup.py script when it is configuring the package.

On line 13, we declare our dependencies, so that they are built before the build process of our package starts.

On line 14, we declare the specific Python build system being used. In this case the distutils Python build system is used. The two supported ones are distutils and setuptools.

Finally, on line 16, we invoke the python-package macro that generates all the Makefile rules that actually allow the package to be built.

As a policy, packages that merely provide Python modules should all be named python-<something> in Buildroot. Other packages that use the Python build system, but are not Python modules, can freely choose their name (existing examples in Buildroot are scons and supervisor).

Packages that are only compatible with one version of Python (as in: Python 2 or Python 3) should depend on that version explicitely in their Config.in file (BR2_PACKAGE_PYTHON for Python 2, BR2_PACKAGE_PYTHON3 for Python 3). Packages that are compatible with both versions should not explicitely depend on them in their Config.in file, since that condition is already expressed for the whole "External python modules" menu.

The main macro of the Python package infrastructure is python-package. It is similar to the generic-package macro. It is also possible to create Python host packages with the host-python-package macro.

Just like the generic infrastructure, the Python infrastructure works by defining a number of variables before calling the python-package or host-python-package macros.

All the package metadata information variables that exist in the generic package infrastructure also exist in the Python infrastructure: PYTHON_FOO_VERSION, PYTHON_FOO_SOURCE, PYTHON_FOO_PATCH, PYTHON_FOO_SITE, PYTHON_FOO_SUBDIR, PYTHON_FOO_DEPENDENCIES, PYTHON_FOO_LICENSE, PYTHON_FOO_LICENSE_FILES, PYTHON_FOO_INSTALL_STAGING, etc.

Note that:

One variable specific to the Python infrastructure is mandatory:

A few additional variables, specific to the Python infrastructure, can optionally be defined, depending on the package’s needs. Many of them are only useful in very specific cases, typical packages will therefore only use a few of them, or none.

With the Python infrastructure, all the steps required to build and install the packages are already defined, and they generally work well for most Python-based packages. However, when required, it is still possible to customize what is done in any particular step:

If the Python package for which you would like to create a Buildroot package is available on PyPI, you may want to use the scanpypi tool located in utils/ to automate the process.

You can find the list of existing PyPI packages here.

scanpypi requires Python’s setuptools package to be installed on your host.

When at the root of your buildroot directory just do :

utils/scanpypi foo bar -o package

This will generate packages python-foo and python-bar in the package folder if they exist on https://pypi.python.org.

Find the external python modules menu and insert your package inside. Keep in mind that the items inside a menu should be in alphabetical order.

Please keep in mind that you’ll most likely have to manually check the package for any mistakes as there are things that cannot be guessed by the generator (e.g. dependencies on any of the python core modules such as BR2_PACKAGE_PYTHON_ZLIB). Also, please take note that the license and license files are guessed and must be checked. You also need to manually add the package to the package/Config.in file.

If your Buildroot package is not in the official Buildroot tree but in a br2-external tree, use the -o flag as follows:

utils/scanpypi foo bar -o other_package_dir

This will generate packages python-foo and python-bar in the other_package_directory instead of package.

Option -h will list the available options:

utils/scanpypi -h

C Foreign Function Interface for Python (CFFI) provides a convenient and reliable way to call compiled C code from Python using interface declarations written in C. Python packages relying on this backend can be identified by the appearance of a cffi dependency in the install_requires field of their setup.py file.

Such a package should:

config BR2_PACKAGE_PYTHON_FOO
        bool "python-foo"
        select BR2_PACKAGE_PYTHON_CFFI # runtime

################################################################################
#
# python-foo
#
################################################################################

...

PYTHON_FOO_DEPENDENCIES = host-python-cffi

$(eval $(python-package))

First, let’s see how to write a .mk file for a LuaRocks-based package, with an example :

01: ################################################################################
02: #
03: # lua-foo
04: #
05: ################################################################################
06:
07: LUA_FOO_VERSION = 1.0.2-1
08: LUA_FOO_NAME_UPSTREAM = foo
09: LUA_FOO_DEPENDENCIES = bar
10:
11: LUA_FOO_BUILD_OPTS += BAR_INCDIR=$(STAGING_DIR)/usr/include
12: LUA_FOO_BUILD_OPTS += BAR_LIBDIR=$(STAGING_DIR)/usr/lib
13: LUA_FOO_LICENSE = luaFoo license
14: LUA_FOO_LICENSE_FILES = $(LUA_FOO_SUBDIR)/COPYING
15:
16: $(eval $(luarocks-package))

On line 7, we declare the version of the package (the same as in the rockspec, which is the concatenation of the upstream version and the rockspec revision, separated by a hyphen -).

On line 8, we declare that the package is called "foo" on LuaRocks. In Buildroot, we give Lua-related packages a name that starts with "lua", so the Buildroot name is different from the upstream name. LUA_FOO_NAME_UPSTREAM makes the link between the two names.

On line 9, we declare our dependencies against native libraries, so that they are built before the build process of our package starts.

On lines 11-12, we tell Buildroot to pass custom options to LuaRocks when it is building the package.

On lines 13-14, we specify the licensing terms for the package.

Finally, on line 16, we invoke the luarocks-package macro that generates all the Makefile rules that actually allows the package to be built.

Most of these details can be retrieved from the rock and rockspec. So, this file and the Config.in file can be generated by running the command luarocks buildroot foo lua-foo in the Buildroot directory. This command runs a specific Buildroot addon of luarocks that will automatically generate a Buildroot package. The result must still be manually inspected and possibly modified.

LuaRocks is a deployment and management system for Lua modules, and supports various build.type: builtin, make and cmake. In the context of Buildroot, the luarocks-package infrastructure only supports the builtin mode. LuaRocks packages that use the make or cmake build mechanisms should instead be packaged using the generic-package and cmake-package infrastructures in Buildroot, respectively.

The main macro of the LuaRocks package infrastructure is luarocks-package: like generic-package it works by defining a number of variables providing metadata information about the package, and then calling luarocks-package. It is worth mentioning that building LuaRocks packages for the host is not supported, so the macro host-luarocks-package is not implemented.

Just like the generic infrastructure, the LuaRocks infrastructure works by defining a number of variables before calling the luarocks-package macro.

First, all the package metadata information variables that exist in the generic infrastructure also exist in the LuaRocks infrastructure: LUA_FOO_VERSION, LUA_FOO_SOURCE, LUA_FOO_SITE, LUA_FOO_DEPENDENCIES, LUA_FOO_LICENSE, LUA_FOO_LICENSE_FILES.

Two of them are populated by the LuaRocks infrastructure (for the download step). If your package is not hosted on the LuaRocks mirror $(BR2_LUAROCKS_MIRROR), you can override them:

A few additional variables, specific to the LuaRocks infrastructure, are also defined. They can be overridden in specific cases.

First, let’s see how to write a .mk file for a Perl/CPAN package, with an example :

01: ################################################################################
02: #
03: # perl-foo-bar
04: #
05: ################################################################################
06:
07: PERL_FOO_BAR_VERSION = 0.02
08: PERL_FOO_BAR_SOURCE = Foo-Bar-$(PERL_FOO_BAR_VERSION).tar.gz
09: PERL_FOO_BAR_SITE = $(BR2_CPAN_MIRROR)/authors/id/M/MO/MONGER
10: PERL_FOO_BAR_DEPENDENCIES = perl-strictures
11: PERL_FOO_BAR_LICENSE = Artistic or GPL-1.0+
12: PERL_FOO_BAR_LICENSE_FILES = LICENSE
13: PERL_FOO_BAR_DISTNAME = Foo-Bar
14:
15: $(eval $(perl-package))

On line 7, we declare the version of the package.

On line 8 and 9, we declare the name of the tarball and the location of the tarball on a CPAN server. Buildroot will automatically download the tarball from this location.

On line 10, we declare our dependencies, so that they are built before the build process of our package starts.

On line 11 and 12, we give licensing details about the package (its license on line 11, and the file containing the license text on line 12).

On line 13, the name of the distribution as needed by the script utils/scancpan (in order to regenerate/upgrade these package files).

Finally, on line 15, we invoke the perl-package macro that generates all the Makefile rules that actually allow the package to be built.

Most of these data can be retrieved from https://metacpan.org/. So, this file and the Config.in can be generated by running the script utils/scancpan Foo-Bar in the Buildroot directory (or in a br2-external tree). This script creates a Config.in file and foo-bar.mk file for the requested package, and also recursively for all dependencies specified by CPAN. You should still manually edit the result. In particular, the following things should be checked.

As a policy, packages that provide Perl/CPAN modules should all be named perl-<something> in Buildroot.

This infrastructure handles various Perl build systems : ExtUtils-MakeMaker (EUMM), Module-Build (MB) and Module-Build-Tiny. Build.PL is preferred by default when a package provides a Makefile.PL and a Build.PL.

The main macro of the Perl/CPAN package infrastructure is perl-package. It is similar to the generic-package macro. The ability to have target and host packages is also available, with the host-perl-package macro.

Just like the generic infrastructure, the Perl/CPAN infrastructure works by defining a number of variables before calling the perl-package macro.

First, all the package metadata information variables that exist in the generic infrastructure also exist in the Perl/CPAN infrastructure: PERL_FOO_VERSION, PERL_FOO_SOURCE, PERL_FOO_PATCH, PERL_FOO_SITE, PERL_FOO_SUBDIR, PERL_FOO_DEPENDENCIES, PERL_FOO_INSTALL_TARGET.

Note that setting PERL_FOO_INSTALL_STAGING to YES has no effect unless a PERL_FOO_INSTALL_STAGING_CMDS variable is defined. The perl infrastructure doesn’t define these commands since Perl modules generally don’t need to be installed to the staging directory.

A few additional variables, specific to the Perl/CPAN infrastructure, can also be defined. Many of them are only useful in very specific cases, typical packages will therefore only use a few of them.

In the following example, we will explain how to add a new virtual package (something-virtual) and a provider for it (some-provider).

First, let’s create the virtual package.

The Config.in file of virtual package something-virtual should contain:

01: config BR2_PACKAGE_HAS_SOMETHING_VIRTUAL
02:     bool
03:
04: config BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL
05:     depends on BR2_PACKAGE_HAS_SOMETHING_VIRTUAL
06:     string

In this file, we declare two options, BR2_PACKAGE_HAS_SOMETHING_VIRTUAL and BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL, whose values will be used by the providers.

The .mk for the virtual package should just evaluate the virtual-package macro:

01: ################################################################################
02: #
03: # something-virtual
04: #
05: ################################################################################
06:
07: $(eval $(virtual-package))

The ability to have target and host packages is also available, with the host-virtual-package macro.

When adding a package as a provider, only the Config.in file requires some modifications.

The Config.in file of the package some-provider, which provides the functionalities of something-virtual, should contain:

01: config BR2_PACKAGE_SOME_PROVIDER
02:     bool "some-provider"
03:     select BR2_PACKAGE_HAS_SOMETHING_VIRTUAL
04:     help
05:       This is a comment that explains what some-provider is.
06:
07:       http://foosoftware.org/some-provider/
08:
09: if BR2_PACKAGE_SOME_PROVIDER
10: config BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL
11:     default "some-provider"
12: endif

On line 3, we select BR2_PACKAGE_HAS_SOMETHING_VIRTUAL, and on line 11, we set the value of BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL to the name of the provider, but only if it is selected.

The .mk file should also declare an additional variable SOME_PROVIDER_PROVIDES to contain the names of all the virtual packages it is an implementation of:

01: SOME_PROVIDER_PROVIDES = something-virtual

Of course, do not forget to add the proper build and runtime dependencies for this package!

When adding a package that requires a certain FEATURE provided by a virtual package, you have to use depends on BR2_PACKAGE_HAS_FEATURE, like so:

config BR2_PACKAGE_HAS_FEATURE
    bool

config BR2_PACKAGE_FOO
    bool "foo"
    depends on BR2_PACKAGE_HAS_FEATURE

If your package really requires a specific provider, then you’ll have to make your package depends on this provider; you can not select a provider.

Let’s take an example with two providers for a FEATURE:

config BR2_PACKAGE_HAS_FEATURE
    bool

config BR2_PACKAGE_FOO
    bool "foo"
    select BR2_PACKAGE_HAS_FEATURE

config BR2_PACKAGE_BAR
    bool "bar"
    select BR2_PACKAGE_HAS_FEATURE

And you are adding a package that needs FEATURE as provided by foo, but not as provided by bar.

If you were to use select BR2_PACKAGE_FOO, then the user would still be able to select BR2_PACKAGE_BAR in the menuconfig. This would create a configuration inconsistency, whereby two providers of the same FEATURE would be enabled at once, one explicitly set by the user, the other implicitly by your select.

Instead, you have to use depends on BR2_PACKAGE_FOO, which avoids any implicit configuration inconsistency.

First, let’s see how to write a .mk file for a rebar-based package, with an example :

01: ################################################################################
02: #
03: # erlang-foobar
04: #
05: ################################################################################
06:
07: ERLANG_FOOBAR_VERSION = 1.0
08: ERLANG_FOOBAR_SOURCE = erlang-foobar-$(ERLANG_FOOBAR_VERSION).tar.xz
09: ERLANG_FOOBAR_SITE = http://www.foosoftware.org/download
10: ERLANG_FOOBAR_DEPENDENCIES = host-libaaa libbbb
11:
12: $(eval $(rebar-package))

On line 7, we declare the version of the package.

On line 8 and 9, we declare the name of the tarball (xz-ed tarball recommended) and the location of the tarball on the Web. Buildroot will automatically download the tarball from this location.

On line 10, we declare our dependencies, so that they are built before the build process of our package starts.

Finally, on line 12, we invoke the rebar-package macro that generates all the Makefile rules that actually allows the package to be built.

The main macro of the rebar package infrastructure is rebar-package. It is similar to the generic-package macro. The ability to have host packages is also available, with the host-rebar-package macro.

Just like the generic infrastructure, the rebar infrastructure works by defining a number of variables before calling the rebar-package macro.

First, all the package metadata information variables that exist in the generic infrastructure also exist in the rebar infrastructure: ERLANG_FOOBAR_VERSION, ERLANG_FOOBAR_SOURCE, ERLANG_FOOBAR_PATCH, ERLANG_FOOBAR_SITE, ERLANG_FOOBAR_SUBDIR, ERLANG_FOOBAR_DEPENDENCIES, ERLANG_FOOBAR_INSTALL_STAGING, ERLANG_FOOBAR_INSTALL_TARGET, ERLANG_FOOBAR_LICENSE and ERLANG_FOOBAR_LICENSE_FILES.

A few additional variables, specific to the rebar infrastructure, can also be defined. Many of them are only useful in very specific cases, typical packages will therefore only use a few of them.

With the rebar infrastructure, all the steps required to build and install the packages are already defined, and they generally work well for most rebar-based packages. However, when required, it is still possible to customize what is done in any particular step:

First, let’s see how to write a .mk file for a Waf-based package, with an example :

01: ################################################################################
02: #
03: # libfoo
04: #
05: ################################################################################
06:
07: LIBFOO_VERSION = 1.0
08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
09: LIBFOO_SITE = http://www.foosoftware.org/download
10: LIBFOO_CONF_OPTS = --enable-bar --disable-baz
11: LIBFOO_DEPENDENCIES = bar
12:
13: $(eval $(waf-package))

On line 7, we declare the version of the package.

On line 8 and 9, we declare the name of the tarball (xz-ed tarball recommended) and the location of the tarball on the Web. Buildroot will automatically download the tarball from this location.

On line 10, we tell Buildroot what options to enable for libfoo.

On line 11, we tell Buildroot the dependencies of libfoo.

Finally, on line line 13, we invoke the waf-package macro that generates all the Makefile rules that actually allows the package to be built.

The main macro of the Waf package infrastructure is waf-package. It is similar to the generic-package macro.

Just like the generic infrastructure, the Waf infrastructure works by defining a number of variables before calling the waf-package macro.

First, all the package metadata information variables that exist in the generic infrastructure also exist in the Waf infrastructure: LIBFOO_VERSION, LIBFOO_SOURCE, LIBFOO_PATCH, LIBFOO_SITE, LIBFOO_SUBDIR, LIBFOO_DEPENDENCIES, LIBFOO_INSTALL_STAGING, LIBFOO_INSTALL_TARGET.

An additional variable, specific to the Waf infrastructure, can also be defined.

Meson is an open source build system meant to be both extremely fast, and, even more importantly, as user friendly as possible. It uses Ninja as a companion tool to perform the actual build operations.

Let’s see how to write a .mk file for a Meson-based package, with an example:

01: ################################################################################
02: #
03: # foo
04: #
05: ################################################################################
06:
07: FOO_VERSION = 1.0
08: FOO_SOURCE = foo-$(FOO_VERSION).tar.gz
09: FOO_SITE = http://www.foosoftware.org/download
10: FOO_LICENSE = GPL-3.0+
11: FOO_LICENSE_FILES = COPYING
12: FOO_INSTALL_STAGING = YES
13:
14: FOO_DEPENDENCIES = host-pkgconf bar
15:
16: ifeq ($(BR2_PACKAGE_BAZ),y)
17: FOO_CONF_OPTS += -Dbaz=true
18: FOO_DEPENDENCIES += baz
19: else
20: FOO_CONF_OPTS += -Dbaz=false
21: endif
22:
23: $(eval $(meson-package))

The Makefile starts with the definition of the standard variables for package declaration (lines 7 to 11).

On line line 23, we invoke the meson-package macro that generates all the Makefile rules that actually allows the package to be built.

In the example, host-pkgconf and bar are declared as dependencies in FOO_DEPENDENCIES at line 14 because the Meson build file of foo uses pkg-config to determine the compilation flags and libraries of package bar.

Note that it is not necessary to add host-meson in the FOO_DEPENDENCIES variable of a package, since this basic dependency is automatically added as needed by the Meson package infrastructure.

If the "baz" package is selected, then support for the "baz" feature in "foo" is activated by adding -Dbaz=true to FOO_CONF_OPTS at line 17, as specified in the meson_options.txt file in "foo" source tree. The "baz" package is also added to FOO_DEPENDENCIES. Note that the support for baz is explicitly disabled at line 20, if the package is not selected.

To sum it up, to add a new meson-based package, the Makefile example can be copied verbatim then edited to replace all occurences of FOO with the uppercase name of the new package and update the values of the standard variables.

The main macro of the Meson package infrastructure is meson-package. It is similar to the generic-package macro. The ability to have target and host packages is also available, with the host-meson-package macro.

Just like the generic infrastructure, the Meson infrastructure works by defining a number of variables before calling the meson-package macro.

First, all the package metadata information variables that exist in the generic infrastructure also exist in the Meson infrastructure: FOO_VERSION, FOO_SOURCE, FOO_PATCH, FOO_SITE, FOO_SUBDIR, FOO_DEPENDENCIES, FOO_INSTALL_STAGING, FOO_INSTALL_TARGET.

A few additional variables, specific to the Meson infrastructure, can also be defined. Many of them are only useful in very specific cases, typical packages will therefore only use a few of them.

The Config.in file of Cargo-based package foo should contain:

01: config BR2_PACKAGE_FOO
02:     bool "foo"
03:     depends on BR2_PACKAGE_HOST_RUSTC_TARGET_ARCH_SUPPORTS
04:     select BR2_PACKAGE_HOST_CARGO
05:     help
06:       This is a comment that explains what foo is.
07:
08:       http://foosoftware.org/foo/

Buildroot does not (yet) provide a dedicated package infrastructure for Cargo-based packages. So, we will explain how to write a .mk file for such a package. Let’s start with an example:

01: ################################################################################
02: #
03: # foo
04: #
05: ################################################################################
06:
07: FOO_VERSION = 1.0
08: FOO_SOURCE = foo-$(FOO_VERSION).tar.gz
09: FOO_SITE = http://www.foosoftware.org/download
10: FOO_LICENSE = GPL-3.0+
11: FOO_LICENSE_FILES = COPYING
12:
13: FOO_DEPENDENCIES = host-cargo
14:
15: FOO_CARGO_ENV = CARGO_HOME=$(HOST_DIR)/share/cargo
16:
17: FOO_BIN_DIR = target/$(RUSTC_TARGET_NAME)/$(FOO_CARGO_MODE)
18:
19: FOO_CARGO_OPTS = \
20:     $(if $(BR2_ENABLE_DEBUG),,--release) \
21:     --target=$(RUSTC_TARGET_NAME) \
22:     --manifest-path=$(@D)/Cargo.toml
23:
24: define FOO_BUILD_CMDS
25:     $(TARGET_MAKE_ENV) $(FOO_CARGO_ENV) \
26:             cargo build $(FOO_CARGO_OPTS)
27: endef
28:
29: define FOO_INSTALL_TARGET_CMDS
30:     $(INSTALL) -D -m 0755 $(@D)/$(FOO_BIN_DIR)/foo \
31:             $(TARGET_DIR)/usr/bin/foo
32: endef
33:
34: $(eval $(generic-package))

The Makefile starts with the definition of the standard variables for package declaration (lines 7 to 11).

As seen in line 34, it is based on the generic-package infrastructure. So, it defines the variables required by this particular infrastructure, where Cargo is invoked:

In order to have Cargo available for the build, FOO_DEPENDENCIES needs to contain host-cargo.

To sum it up, to add a new Cargo-based package, the Makefile example can be copied verbatim then edited to replace all occurences of FOO with the uppercase name of the new package and update the values of the standard variables.

A crate can depend on other libraries from crates.io or git repositories, listed in its Cargo.toml file. Before starting a build, Cargo usually downloads automatically them. This step can also be performed independently, via the cargo fetch command.

Cargo maintains a local cache of the registry index and of git checkouts of the crates, whose location is given by $CARGO_HOME. As seen in the package Makefile example at line 15, this environment variable is set to $(HOST_DIR)/share/cargo.

This dependency download mechanism is not convenient when performing an offline build, as Cargo will fail to fetch the dependencies. In that case, it is advised to generate a tarball of the dependencies using the cargo vendor and add it to FOO_EXTRA_DOWNLOADS.

First, let’s see how to write a .mk file for a go package, with an example :

01: ################################################################################
02: #
03: # foo
04: #
05: ################################################################################
06:
07: FOO_VERSION = 1.0
08: FOO_SITE = $(call github,bar,foo,$(FOO_VERSION))
09: FOO_LICENSE = BSD-3-Clause
10: FOO_LICENSE_FILES = LICENSE
11:
12: $(eval $(golang-package))

On line 7, we declare the version of the package.

On line 8, we declare the upstream location of the package, here fetched from Github, since a large number of Go packages are hosted on Github.

On line 9 and 10, we give licensing details about the package.

Finally, on line 12, we invoke the golang-package macro that generates all the Makefile rules that actually allow the package to be built.

In their Config.in file, packages using the golang-package infrastructure should depend on BR2_PACKAGE_HOST_GO_TARGET_ARCH_SUPPORTS because Buildroot will automatically add a dependency on host-go to such packages. If you need CGO support in your package, you must add a dependency on BR2_PACKAGE_HOST_GO_TARGET_CGO_LINKING_SUPPORTS.

The main macro of the Go package infrastructure is golang-package. It is similar to the generic-package macro. The ability to build host packages is also available, with the host-golang-package macro. Host packages built by host-golang-package macro should depend on BR2_PACKAGE_HOST_GO_HOST_ARCH_SUPPORTS.

Just like the generic infrastructure, the Go infrastructure works by defining a number of variables before calling the golang-package.

All the package metadata information variables that exist in the generic package infrastructure also exist in the Go infrastructure: FOO_VERSION, FOO_SOURCE, FOO_PATCH, FOO_SITE, FOO_SUBDIR, FOO_DEPENDENCIES, FOO_LICENSE, FOO_LICENSE_FILES, FOO_INSTALL_STAGING, etc.

Note that it is not necessary to add host-go in the FOO_DEPENDENCIES variable of a package, since this basic dependency is automatically added as needed by the Go package infrastructure.

A few additional variables, specific to the Go infrastructure, can optionally be defined, depending on the package’s needs. Many of them are only useful in very specific cases, typical packages will therefore only use a few of them, or none.

With the Go infrastructure, all the steps required to build and install the packages are already defined, and they generally work well for most Go-based packages. However, when required, it is still possible to customize what is done in any particular step:

Let’s start with an example on how to prepare a simple package that only builds a kernel module, and no other component:

01: ################################################################################
02: #
03: # foo
04: #
05: ################################################################################
06:
07: FOO_VERSION = 1.2.3
08: FOO_SOURCE = foo-$(FOO_VERSION).tar.xz
09: FOO_SITE = http://www.foosoftware.org/download
10: FOO_LICENSE = GPL-2.0
11: FOO_LICENSE_FILES = COPYING
12:
13: $(eval $(kernel-module))
14: $(eval $(generic-package))

Lines 7-11 define the usual meta-data to specify the version, archive name, remote URI where to find the package source, licensing information.

On line 13, we invoke the kernel-module helper infrastructure, that generates all the appropriate Makefile rules and variables to build that kernel module.

Finally, on line 14, we invoke the generic-package infrastructure.

The dependency on linux is automatically added, so it is not needed to specify it in FOO_DEPENDENCIES.

What you may have noticed is that, unlike other package infrastructures, we explicitly invoke a second infrastructure. This allows a package to build a kernel module, but also, if needed, use any one of other package infrastructures to build normal userland components (libraries, executables…). Using the kernel-module infrastructure on its own is not sufficient; another package infrastructure must be used.

Let’s look at a more complex example:

01: ################################################################################
02: #
03: # foo
04: #
05: ################################################################################
06:
07: FOO_VERSION = 1.2.3
08: FOO_SOURCE = foo-$(FOO_VERSION).tar.xz
09: FOO_SITE = http://www.foosoftware.org/download
10: FOO_LICENSE = GPL-2.0
11: FOO_LICENSE_FILES = COPYING
12:
13: FOO_MODULE_SUBDIRS = driver/base
14: FOO_MODULE_MAKE_OPTS = KVERSION=$(LINUX_VERSION_PROBED)
15:
16: ifeq ($(BR2_PACKAGE_LIBBAR),y)
17: FOO_DEPENDENCIES = libbar
18: FOO_CONF_OPTS = --enable-bar
19: FOO_MODULE_SUBDIRS += driver/bar
20: else
21: FOO_CONF_OPTS = --disable-bar
22: endif
23:
24: $(eval $(kernel-module))
26: $(eval $(autotools-package))

Here, we see that we have an autotools-based package, that also builds the kernel module located in sub-directory driver/base and, if libbar is enabled, the kernel module located in sub-directory driver/bar, and defines the variable KVERSION to be passed to the Linux buildsystem when building the module(s).

The main macro for the kernel module infrastructure is kernel-module. Unlike other package infrastructures, it is not stand-alone, and requires any of the other *-package macros be called after it.

The kernel-module macro defines post-build and post-target-install hooks to build the kernel modules. If the package’s .mk needs access to the built kernel modules, it should do so in a post-build hook, registered after the call to kernel-module. Similarly, if the package’s .mk needs access to the kernel module after it has been installed, it should do so in a post-install hook, registered after the call to kernel-module. Here’s an example:

$(eval $(kernel-module))

define FOO_DO_STUFF_WITH_KERNEL_MODULE
    # Do something with it...
endef
FOO_POST_BUILD_HOOKS += FOO_DO_STUFF_WITH_KERNEL_MODULE

$(eval $(generic-package))

Finally, unlike the other package infrastructures, there is no host-kernel-module variant to build a host kernel module.

The following additional variables can optionally be defined to further configure the build of the kernel module:

You may also reference (but you may not set!) those variables:

Whereas package infrastructures are suffixed with -package, the document infrastructures are suffixed with -document. So, the AsciiDoc infrastructure is named asciidoc-document.

Here is an example to render a simple AsciiDoc document.

01: ################################################################################
02: #
03: # foo-document
04: #
05: ################################################################################
06:
07: FOO_SOURCES = $(sort $(wildcard $(pkgdir)/*))
08: $(eval $(call asciidoc-document))

On line 7, the Makefile declares what the sources of the document are. Currently, it is expected that the document’s sources are only local; Buildroot will not attempt to download anything to render a document. Thus, you must indicate where the sources are. Usually, the string above is sufficient for a document with no sub-directory structure.

On line 8, we call the asciidoc-document function, which generates all the Makefile code necessary to render the document.

The list of variables that can be set in a .mk file to give metadata information is (assuming the document name is foo) :

There are also additional hooks (see Section 17.21, “Hooks available in the various build steps” for general information on hooks), that a document may set to define extra actions to be done at various steps:

Here is a complete example that uses all variables and all hooks:

01: ################################################################################
02: #
03: # foo-document
04: #
05: ################################################################################
06:
07: FOO_SOURCES = $(sort $(wildcard $(pkgdir)/*))
08: FOO_RESOURCES = $(sort $(wildcard $(pkgdir)/ressources))
09:
10: define FOO_GEN_EXTRA_DOC
11:     /path/to/generate-script --outdir=$(@D)
12: endef
13: FOO_POST_RSYNC_HOOKS += FOO_GEN_EXTRA_DOC
14:
15: define FOO_CHECK_MY_PROG
16:     if ! which my-prog >/dev/null 2>&1; then \
17:         echo "You need my-prog to generate the foo document"; \
18:         exit 1; \
19:     fi
20: endef
21: FOO_CHECK_DEPENDENCIES_HOOKS += FOO_CHECK_MY_PROG
22:
23: define FOO_CHECK_MY_OTHER_PROG
24:     if ! which my-other-prog >/dev/null 2>&1; then \
25:         echo "You need my-other-prog to generate the foo document as PDF"; \
26:         exit 1; \
27:     fi
28: endef
29: FOO_CHECK_DEPENDENCIES_PDF_HOOKS += FOO_CHECK_MY_OTHER_PROG
30:
31: $(eval $(call asciidoc-document))

Buildroot offers a helper infrastructure to build some userspace tools for the target available within the Linux kernel sources. Since their source code is part of the kernel source code, a special package, linux-tools, exists and re-uses the sources of the Linux kernel that runs on the target.

Let’s look at an example of a Linux tool. For a new Linux tool named foo, create a new menu entry in the existing package/linux-tools/Config.in. This file will contain the option descriptions related to each kernel tool that will be used and displayed in the configuration tool. It would basically look like:

01: config BR2_PACKAGE_LINUX_TOOLS_FOO
02:     bool "foo"
03:     select BR2_PACKAGE_LINUX_TOOLS
04:     help
05:       This is a comment that explains what foo kernel tool is.
06:
07:       http://foosoftware.org/foo/

The name of the option starts with the prefix BR2_PACKAGE_LINUX_TOOLS_, followed by the uppercase name of the tool (like is done for packages).

Note. Unlike other packages, the linux-tools package options appear in the linux kernel menu, under the Linux Kernel Tools sub-menu, not under the Target packages main menu.

Then for each linux tool, add a new .mk.in file named package/linux-tools/linux-tool-foo.mk.in. It would basically look like:

01: ################################################################################
02: #
03: # foo
04: #
05: ################################################################################
06:
07: LINUX_TOOLS += foo
08:
09: FOO_DEPENDENCIES = libbbb
10:
11: define FOO_BUILD_CMDS
12:     $(TARGET_MAKE_ENV) $(MAKE) -C $(LINUX_DIR)/tools foo
13: endef
14:
15: define FOO_INSTALL_STAGING_CMDS
16:     $(TARGET_MAKE_ENV) $(MAKE) -C $(LINUX_DIR)/tools \
17:             DESTDIR=$(STAGING_DIR) \
18:             foo_install
19: endef
20:
21: define FOO_INSTALL_TARGET_CMDS
22:     $(TARGET_MAKE_ENV) $(MAKE) -C $(LINUX_DIR)/tools \
23:             DESTDIR=$(TARGET_DIR) \
24:             foo_install
25: endef

On line 7, we register the Linux tool foo to the list of available Linux tools.

On line 9, we specify the list of dependencies this tool relies on. These dependencies are added to the Linux package dependencies list only when the foo tool is selected.

The rest of the Makefile, lines 11-25 defines what should be done at the different steps of the Linux tool build process like for a generic package. They will actually be used only when the foo tool is selected. The only supported commands are _BUILD_CMDS, _INSTALL_STAGING_CMDS and _INSTALL_TARGET_CMDS.

Note. One must not call $(eval $(generic-package)) or any other package infrastructure! Linux tools are not packages by themselves, they are part of the linux-tools package.

Some packages provide new features that require the Linux kernel tree to be modified. This can be in the form of patches to be applied on the kernel tree, or in the form of new files to be added to the tree. The Buildroot’s Linux kernel extensions infrastructure provides a simple solution to automatically do this, just after the kernel sources are extracted and before the kernel patches are applied. Examples of extensions packaged using this mechanism are the real-time extensions Xenomai and RTAI, as well as the set of out-of-tree LCD screens drivers fbtft.

Let’s look at an example on how to add a new Linux extension foo.

First, create the package foo that provides the extension: this package is a standard package; see the previous chapters on how to create such a package. This package is in charge of downloading the sources archive, checking the hash, defining the licence informations and building user space tools if any.

Then create the Linux extension proper: create a new menu entry in the existing linux/Config.ext.in. This file contains the option descriptions related to each kernel extension that will be used and displayed in the configuration tool. It would basically look like:

01: config BR2_LINUX_KERNEL_EXT_FOO
02:     bool "foo"
03:     help
04:       This is a comment that explains what foo kernel extension is.
05:
06:       http://foosoftware.org/foo/

Then for each linux extension, add a new .mk file named linux/linux-ext-foo.mk. It should basically contain:

01: ################################################################################
02: #
03: # foo
04: #
05: ################################################################################
06:
07: LINUX_EXTENSIONS += foo
08:
09: define FOO_PREPARE_KERNEL
10:     $(FOO_DIR)/prepare-kernel-tree.sh --linux-dir=$(@D)
11: endef

On line 7, we add the Linux extension foo to the list of available Linux extensions.

On line 9-11, we define what should be done by the extension to modify the Linux kernel tree; this is specific to the linux extension and can use the variables defined by the foo package, like: $(FOO_DIR) or $(FOO_VERSION)… as well as all the Linux variables, like: $(LINUX_VERSION) or $(LINUX_VERSION_PROBED), $(KERNEL_ARCH)… See the definition of those kernel variables.

The POST_RSYNC hook is run only for packages that use a local source, either through the local site method or the OVERRIDE_SRCDIR mechanism. In this case, package sources are copied using rsync from the local location into the buildroot build directory. The rsync command does not copy all files from the source directory, though. Files belonging to a version control system, like the directories .git, .hg, etc. are not copied. For most packages this is sufficient, but a given package can perform additional actions using the POST_RSYNC hook.

In principle, the hook can contain any command you want. One specific use case, though, is the intentional copying of the version control directory using rsync. The rsync command you use in the hook can, among others, use the following variables:

Packages may also register hooks in LIBFOO_TARGET_FINALIZE_HOOKS. These hooks are run after all packages are built, but before the filesystem images are generated. They are seldom used, and your package probably do not need them.

In Buildroot, there is some relationship between:

It is mandatory to maintain consistency between these elements, using the following rules:

Buildroot provides a script in utils/check-package that checks new or changed files for coding style. It is not a complete language validator, but it catches many common mistakes. It is meant to run in the actual files you created or modified, before creating the patch for submission.

This script can be used for packages, filesystem makefiles, Config.in files, etc. It does not check the files defining the package infrastructures and some other files containing similar common code.

To use it, run the check-package script, by telling which files you created or changed:

$ ./utils/check-package package/new-package/*

If you have the utils directory in your path you can also run:

$ cd package/new-package/
$ check-package *

The tool can also be used for packages in a br2-external:

$ check-package -b /path/to/br2-ext-tree/package/my-package/*

Once you have added your new package, it is important that you test it under various conditions: does it build for all architectures? Does it build with the different C libraries? Does it need threads, NPTL? And so on…

Buildroot runs autobuilders which continuously test random configurations. However, these only build the master branch of the git tree, and your new fancy package is not yet there.

Buildroot provides a script in utils/test-pkg that uses the same base configurations as used by the autobuilders so you can test your package in the same conditions.

First, create a config snippet that contains all the necessary options needed to enable your package, but without any architecture or toolchain option. For example, let’s create a config snippet that just enables libcurl, without any TLS backend:

$ cat libcurl.config
BR2_PACKAGE_LIBCURL=y

If your package needs more configuration options, you can add them to the config snippet. For example, here’s how you would test libcurl with openssl as a TLS backend and the curl program:

$ cat libcurl.config
BR2_PACKAGE_LIBCURL=y
BR2_PACKAGE_LIBCURL_CURL=y
BR2_PACKAGE_OPENSSL=y

Then run the test-pkg script, by telling it what config snippet to use and what package to test:

$ ./utils/test-pkg -c libcurl.config -p libcurl

By default, test-pkg will build your package against a subset of the toolchains used by the autobuilders, which has been selected by the Buildroot developers as being the most useful and representative subset. If you want to test all toolchains, pass the -a option. Note that in any case, internal toolchains are excluded as they take too long to build.

The output lists all toolchains that are tested and the corresponding result (excerpt, results are fake):

$ ./utils/test-pkg -c libcurl.config -p libcurl
                armv5-ctng-linux-gnueabi [ 1/11]: OK
              armv7-ctng-linux-gnueabihf [ 2/11]: OK
                        br-aarch64-glibc [ 3/11]: SKIPPED
                           br-arcle-hs38 [ 4/11]: SKIPPED
                            br-arm-basic [ 5/11]: FAILED
                  br-arm-cortex-a9-glibc [ 6/11]: OK
                   br-arm-cortex-a9-musl [ 7/11]: FAILED
                   br-arm-cortex-m4-full [ 8/11]: OK
                             br-arm-full [ 9/11]: OK
                    br-arm-full-nothread [10/11]: FAILED
                      br-arm-full-static [11/11]: OK
11 builds, 2 skipped, 2 build failed, 1 legal-info failed

The results mean:

When there are failures, you can just re-run the script with the same options (after you fixed your package); the script will attempt to re-build the package specified with -p for all toolchains, without the need to re-build all the dependencies of that package.

The test-pkg script accepts a few options, for which you can get some help by running:

$ ./utils/test-pkg -h

Packages on GitHub often don’t have a download area with release tarballs. However, it is possible to download tarballs directly from the repository on GitHub. As GitHub is known to have changed download mechanisms in the past, the github helper function should be used as shown below.

# Use a tag or a full commit ID
FOO_VERSION = v1.0
FOO_SITE = $(call github,<user>,<package>,$(FOO_VERSION))

If the package you wish to add does have a release section on GitHub, the maintainer may have uploaded a release tarball, or the release may just point to the automatically generated tarball from the git tag. If there is a release tarball uploaded by the maintainer, we prefer to use that since it may be slightly different (e.g. it contains a configure script so we don’t need to do AUTORECONF).

You can see on the release page if it’s an uploaded tarball or a git tag:

If it is necessary to apply a patch that is available for download, then add it to the <packagename>_PATCH variable. If an entry contains ://, then Buildroot will assume it is a full URL and download the patch from this location. Otherwise, Buildroot will assume that the patch should be downloaded from <packagename>_SITE. It can be a single patch, or a tarball containing a patch series.

Like for all downloads, a hash should be added to the <packagename>.hash file.

This method is typically used for packages from Debian.

Most patches are provided within Buildroot, in the package directory; these typically aim to fix cross-compilation, libc support, or other such issues.

These patch files should be named <number>-<description>.patch.

The BR2_GLOBAL_PATCH_DIR configuration file option can be used to specify a space separated list of one or more directories containing global package patches. See Section 9.8, “Adding project-specific patches” for details.

The main use of Buildroot’s Patchwork website for a developer is for pulling in patches into their local git repository for testing purposes.

When browsing patches in the patchwork management interface, an mbox link is provided at the top of the page. Copy this link address and run the following commands:

$ git checkout -b <test-branch-name>
$ wget -O - <mbox-url> | git am

Another option for applying patches is to create a bundle. A bundle is a set of patches that you can group together using the patchwork interface. Once the bundle is created and the bundle is made public, you can copy the mbox link for the bundle and apply the bundle using the above commands.

We expect patches to be formatted in a specific way. This is necessary to make it easy to review patches, to be able to apply them easily to the git repository, to make it easy to find back in the history how and why things have changed, and to make it possible to use git bisect to locate the origin of a problem.

First of all, it is essential that the patch has a good commit message. The commit message should start with a separate line with a brief summary of the change, prefixed by the area touched by the patch. A few examples of good commit titles:

The description that follows the prefix should start with a lower case letter (i.e "bump", "needs", "postpone", "add" in the above examples).

Second, the body of the commit message should describe why this change is needed, and if necessary also give details about how it was done. When writing the commit message, think of how the reviewers will read it, but also think about how you will read it when you look at this change again a few years down the line.

Third, the patch itself should do only one change, but do it completely. Two unrelated or weakly related changes should usually be done in two separate patches. This usually means that a patch affects only a single package. If several changes are related, it is often still possible to split them up in small patches and apply them in a specific order. Small patches make it easier to review, and often make it easier to understand afterwards why a change was done. However, each patch must be complete. It is not allowed that the build is broken when only the first but not the second patch is applied. This is necessary to be able to use git bisect afterwards.

Of course, while you’re doing your development, you’re probably going back and forth between packages, and certainly not committing things immediately in a way that is clean enough for submission. So most developers rewrite the history of commits to produce a clean set of commits that is appropriate for submission. To do this, you need to use interactive rebasing. You can learn about it in the Pro Git book. Sometimes, it is even easier to discard you history with git reset --soft origin/master and select individual changes with git add -i or git add -p.

Finally, the patch should be signed off. This is done by adding Signed-off-by: Your Real Name <your@email.address> at the end of the commit message. git commit -s does that for you, if configured properly. The Signed-off-by tag means that you publish the patch under the Buildroot license (i.e. GPL-2.0+, except for package patches, which have the upstream license), and that you are allowed to do so. See the Developer Certificate of Origin for details.

When adding new packages, you should submit every package in a separate patch. This patch should have the update to package/Config.in, the package Config.in file, the .mk file, the .hash file, any init script, and all package patches. If the package has many sub-options, these are sometimes better added as separate follow-up patches. The summary line should be something like <packagename>: new package. The body of the commit message can be empty for simple packages, or it can contain the description of the package (like the Config.in help text). If anything special has to be done to build the package, this should also be explained explicitly in the commit message body.

When you bump a package to a new version, you should also submit a separate patch for each package. Don’t forget to update the .hash file, or add it if it doesn’t exist yet. Also don’t forget to check if the _LICENSE and _LICENSE_FILES are still valid. The summary line should be something like <packagename>: bump to version <new version>. If the new version only contains security updates compared to the existing one, the summary should be <packagename>: security bump to version <new version> and the commit message body should show the CVE numbers that are fixed. If some package patches can be removed in the new version, it should be explained explicitly why they can be removed, preferably with the upstream commit ID. Also any other required changes should be explained explicitly, like configure options that no longer exist or are no longer needed.

If you are interested in getting notified of build failures and of further changes in the packages you added or modified, please add yourself to the DEVELOPERS file. This should be done in the same patch creating or modifying the package. See the DEVELOPERS file for more information.

Buildroot provides a handy tool to check for common coding style mistakes on files you created or modified, called check-package (see Section 17.23.2, “How to check the coding style” for more information).

Starting from the changes committed in your local git view, rebase your development branch on top of the upstream tree before generating a patch set. To do so, run:

$ git fetch --all --tags
$ git rebase origin/master

Now, you are ready to generate then submit your patch set.

To generate it, run:

$ git format-patch -M -n -s -o outgoing origin/master

This will generate patch files in the outgoing subdirectory, automatically adding the Signed-off-by line.

Once patch files are generated, you can review/edit the commit message before submitting them, using your favorite text editor.

Buildroot provides a handy tool to know to whom your patches should be sent, called get-developers (see Chapter 22, DEVELOPERS file and get-developers for more information). This tool reads your patches and outputs the appropriate git send-email command to use:

$ ./utils/get-developers outgoing/*

Use the output of get-developers to send your patches:

$ git send-email --to buildroot@buildroot.org --cc bob --cc alice outgoing/*

Alternatively, get-developers -e can be used directly with the --cc-cmd argument to git send-email to automatically CC the affected developers:

$ git send-email --to buildroot@buildroot.org \
      --cc-cmd './utils/get-developers -e' origin/master

git can be configured to automatically do this out of the box with:

$ git config sendemail.to buildroot@buildroot.org
$ git config sendemail.ccCmd "$(pwd)/utils/get-developers -e"

And then just do:

$ git send-email origin/master

Note that git should be configured to use your mail account. To configure git, see man git-send-email or google it.

If you do not use git send-email, make sure posted patches are not line-wrapped, otherwise they cannot easily be applied. In such a case, fix your e-mail client, or better yet, learn to use git send-email.

If you want to present the whole patch set in a separate mail, add --cover-letter to the git format-patch command (see man git-format-patch for further information). This will generate a template for an introduction e-mail to your patch series.

A cover letter may be useful to introduce the changes you propose in the following cases:

When fixing bugs on a maintenance branch, bugs should be fixed on the master branch first. The commit log for such a patch may then contain a post-commit note specifying what branches are affected:

package/foo: fix stuff

Signed-off-by: Your Real Name <your@email.address>
---
Backport to: 2020.02.x, 2020.05.x
(2020.08.x not affected as the version was bumped)

Those changes will then be backported by a maintainer to the affected branches.

However, some bugs may apply only to a specific release, for example because it is using an older version of a package. In that case, patches should be based off the maintenance branch, and the patch subject prefix must include the maintenance branch name (for example "[PATCH 2020.02.x]"). This can be done with the git format-patch flag --subject-prefix:

$ git format-patch --subject-prefix "PATCH 2020.02.x" \
    -M -s -o outgoing origin/2020.02.x

Then send the patches with git send-email, as described above.

When improvements are requested, the new revision of each commit should include a changelog of the modifications between each submission. Note that when your patch series is introduced by a cover letter, an overall changelog may be added to the cover letter in addition to the changelog in the individual commits. The best thing to rework a patch series is by interactive rebasing: git rebase -i origin/master. Consult the git manual for more information.

When added to the individual commits, this changelog is added when editing the commit message. Below the Signed-off-by section, add --- and your changelog.

Although the changelog will be visible for the reviewers in the mail thread, as well as in patchwork, git will automatically ignores lines below --- when the patch will be merged. This is the intended behavior: the changelog is not meant to be preserved forever in the git history of the project.

Hereafter the recommended layout:

Patch title: short explanation, max 72 chars

A paragraph that explains the problem, and how it manifests itself. If
the problem is complex, it is OK to add more paragraphs. All paragraphs
should be wrapped at 72 characters.

A paragraph that explains the root cause of the problem. Again, more
than one paragraph is OK.

Finally, one or more paragraphs that explain how the problem is solved.
Don't hesitate to explain complex solutions in detail.

Signed-off-by: John DOE <john.doe@example.net>

---
Changes v2 -> v3:
  - foo bar  (suggested by Jane)
  - bar buz

Changes v1 -> v2:
  - alpha bravo  (suggested by John)
  - charly delta

Any patch revision should include the version number. The version number is simply composed of the letter v followed by an integer greater or equal to two (i.e. "PATCH v2", "PATCH v3" …).

This can be easily handled with git format-patch by using the option --subject-prefix:

$ git format-patch --subject-prefix "PATCH v4" \
    -M -s -o outgoing origin/master

Since git version 1.8.1, you can also use -v <n> (where <n> is the version number):

$ git format-patch -v4 -M -s -o outgoing origin/master

When you provide a new version of a patch, please mark the old one as superseded in patchwork. You need to create an account on patchwork to be able to modify the status of your patches. Note that you can only change the status of patches you submitted yourself, which means the email address you register in patchwork should match the one you use for sending patches to the mailing list.

You can also add the --in-reply-to <message-id> option when submitting a patch to the mailing list. The id of the mail to reply to can be found under the "Message Id" tag on patchwork. The advantage of in-reply-to is that patchwork will automatically mark the previous version of the patch as superseded.

The best way to get familiar with how to create a test case is to look at a few of the basic file system support/testing/tests/fs/ and init support/testing/tests/init/ test scripts. Those tests give good examples of a basic build and build with run type of tests. There are other more advanced cases that use things like nested br2-external folders to provide skeletons and additional packages.

The test cases by default use a br-arm-full-* uClibc-ng toolchain and the prebuild kernel for a armv5/7 cpu. It is recommended to use the default defconfig test configuration except when Glibc/musl or a newer kernel are necessary. By using the default it saves build time and the test would automatically inherit a kernel/std library upgrade when the default is updated.

The basic test case definition involves

Beyond creating the test script, there are a couple of additional steps that should be taken once you have your initial test case script. The first is to add yourself to the DEVELOPERS file to be the maintainer of that test case. The second is to update the Gitlab CI yml by executing make .gitlab-ci.yml.

Within the Buildroot repository, the testing framework is organized at the top level in support/testing/ by folders of conf, infra and tests. All the test cases live under the test folder and are organized in various folders representing the catagory of test.

Lets walk through an example.

$ support/testing/run-tests -d dl -o output_folder -k tests.init.test_busybox.TestInitSystemBusyboxRw
15:03:26 TestInitSystemBusyboxRw                  Starting
15:03:28 TestInitSystemBusyboxRw                  Building
15:08:18 TestInitSystemBusyboxRw                  Building done
15:08:27 TestInitSystemBusyboxRw                  Cleaning up
.
Ran 1 test in 301.140s

OK

$ ls output_folder/
TestInitSystemBusyboxRw/
TestInitSystemBusyboxRw-build.log
TestInitSystemBusyboxRw-run.log

To test an existing or new test case within Gitlab CI, there is a method of invoking a specific test by creating a Buildroot fork in Gitlab under your account. This can be handy when adding/changing a run-time test or fixing a bug on a use case tested by a run-time test case.

In the examples below, the <name> component of the branch name is a unique string you choose to identify this specific job being created.

 $ git push gitlab HEAD:<name>-runtime-tests

 $ git push gitlab HEAD:<name>-<test case name>