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"
        depends on BR2_PACKAGE_A
        select BR2_PACKAGE_B

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

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 18.12, “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) :

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 18.23, “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.

All the package metadata information variables that exist in the generic package infrastructure also exist in the autotools infrastructure.

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.

All the package metadata information variables that exist in the generic package infrastructure also exist in the CMake infrastructure.

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 = setuptools
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 setuptools Python build system is used. The five supported ones are flit, pep517, setuptools, setuptools-rust and maturin.

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).

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.

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 the luarocks-package macro.

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

All the package metadata information variables that exist in the generic package infrastructure also exist in the LuaRocks infrastructure.

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.

All the package metadata information variables that exist in the generic package infrastructure also exist in the Perl/CPAN infrastructure.

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.

All the package metadata information variables that exist in the generic package infrastructure also exist in the rebar infrastructure.

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.

All the package metadata information variables that exist in the generic package infrastructure also exist in the Waf infrastructure.

A few additional variables, 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 occurrences 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.

All the package metadata information variables that exist in the generic package infrastructure also exist in the Meson infrastructure.

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_RUSTC
05:     help
06:       This is a comment that explains what foo is.
07:
08:       http://foosoftware.org/foo/

And the .mk file for this package should contain:

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: $(eval $(cargo-package))

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

As seen in line 13, it is based on the cargo-package infrastructure. Cargo will be invoked automatically by this infrastructure to build and install the package.

It is still possible to define custom build commands or install commands (i.e. with FOO_BUILD_CMDS and FOO_INSTALL_TARGET_CMDS). Those will then replace the commands from the cargo infrastructure.

The main macros for the Cargo package infrastructure are cargo-package for target packages and host-cargo-package for host packages.

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

All the package metadata information variables that exist in the generic package infrastructure also exist in the Cargo infrastructure.

A few additional variables, specific to the Cargo 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.

A crate can depend on other libraries from crates.io or git repositories, listed in its Cargo.toml file. Buildroot automatically takes care of downloading such dependencies as part of the download step of packages that use the cargo-package infrastructure. Such dependencies are then kept together with the package source code in the tarball cached in Buildroot’s DL_DIR, and therefore the hash of the package’s tarball doesn’t only cover the source of the package itself, but also covers the sources of the dependencies. Thus, a change injected into one of the dependencies will also be discovered by the hash check. In addition, this mechanism allows the build to be performed completely offline since cargo will not do any downloads during the build. This mechanism is called vendoring the dependencies.

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 macro.

All the package metadata information variables that exist in the generic package infrastructure also exist in the Go infrastructure.

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:

A Go package can depend on other Go modules, listed in its go.mod file. Buildroot automatically takes care of downloading such dependencies as part of the download step of packages that use the golang-package infrastructure. Such dependencies are then kept together with the package source code in the tarball cached in Buildroot’s DL_DIR, and therefore the hash of the package’s tarball includes such dependencies.

This mechanism ensures that any change in the dependencies will be detected, and allows the build to be performed completely offline.

First, let’s see how to write a .mk file for a QMake-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 = QT_CONFIG+=bar QT_CONFIG-=baz
11: LIBFOO_DEPENDENCIES = bar
12:
13: $(eval $(qmake-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 qmake-package macro that generates all the Makefile rules that actually allows the package to be built.

The main macro of the QMake package infrastructure is qmake-package. It is similar to the generic-package macro.

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

All the package metadata information variables that exist in the generic package infrastructure also exist in the QMake infrastructure.

A few additional variables, specific to the QMake infrastructure, can also be defined.

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 $(FOO_DOCDIR)/*))
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 18.23, “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:

Buildroot sets the following variable that can be used in the definitions above:

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 $(FOO_DOCDIR)/*))
08: FOO_RESOURCES = $(sort $(wildcard $(FOO_DOCDIR)/resources))
09:
10: FOO_TOC_DEPTH = 2
11: FOO_TOC_DEPTH_HTML = 1
12: FOO_TOC_DEPTH_SPLIT_HTML = 3
13:
14: define FOO_GEN_EXTRA_DOC
15:     /path/to/generate-script --outdir=$(@D)
16: endef
17: FOO_POST_RSYNC_HOOKS += FOO_GEN_EXTRA_DOC
18:
19: define FOO_CHECK_MY_PROG
20:     if ! which my-prog >/dev/null 2>&1; then \
21:         echo "You need my-prog to generate the foo document"; \
22:         exit 1; \
23:     fi
24: endef
25: FOO_CHECK_DEPENDENCIES_HOOKS += FOO_CHECK_MY_PROG
26:
27: define FOO_CHECK_MY_OTHER_PROG
28:     if ! which my-other-prog >/dev/null 2>&1; then \
29:         echo "You need my-other-prog to generate the foo document as PDF"; \
30:         exit 1; \
31:     fi
32: endef
33: FOO_CHECK_DEPENDENCIES_PDF_HOOKS += FOO_CHECK_MY_OTHER_PROG
34:
35: $(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 information 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/*

The check-package script requires you install shellcheck and the Python PyPi packages flake8 and python-magic. The Buildroot code base is currently tested against version 0.7.1 of ShellCheck. If you use a different version of ShellCheck, you may see additional, unfixed, warnings.

If you have Docker or Podman you can run check-package without installing dependencies:

$ ./utils/docker-run ./utils/check-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 = 1.0
FOO_SITE = $(call github,<user>,<package>,v$(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:

In a similar way to the github macro described in Section 18.25.4, “How to add a package from GitHub”, Buildroot also provides the gitlab macro to download from Gitlab repositories. It can be used to download auto-generated tarballs produced by Gitlab, either for specific tags or commits:

# Use a tag or a full commit ID
FOO_VERSION = 1.0
FOO_SITE = $(call gitlab,<user>,<package>,v$(FOO_VERSION))

By default, it will use a .tar.gz tarball, but Gitlab also provides .tar.bz2 tarballs, so by adding a <pkg>_SOURCE variable, this .tar.bz2 tarball can be used:

# Use a tag or a full commit ID
FOO_VERSION = 1.0
FOO_SITE = $(call gitlab,<user>,<package>,v$(FOO_VERSION))
FOO_SOURCE = foo-$(FOO_VERSION).tar.bz2

If there is a specific tarball uploaded by the upstream developers in https://gitlab.com/<project>/releases/, do not use this macro, but rather use directly the link to the tarball.