Chapterﾂ6.ﾂBuildroot configuration
All the configuration options in make *config have a help text
-providing details about the option.
The make *config commands also offer a search tool. Read the help
-message in the different frontend menus to know how to use it:
-
-in menuconfig, the search tool is called by pressing
/;
- -
-in xconfig, the search tool is called by pressing
Ctrl + f.
-
The result of the search shows the help message of the matching items.
-In menuconfig, numbers in the left column provide a shortcut to the
-corresponding entry. Just type this number to directly jump to the
-entry, or to the containing menu in case the entry is not selectable due
-to a missing dependency.
Although the menu structure and the help text of the entries should be
-sufficiently self-explanatory, a number of topics require additional
-explanation that cannot easily be covered in the help text and are
-therefore covered in the following sections.
6.1.ﾂCross-compilation toolchain
A compilation toolchain is the set of tools that allows you to compile
-code for your system. It consists of a compiler (in our case, gcc),
-binary utils like assembler and linker (in our case, binutils) and a
-C standard library (for example
-GNU Libc,
-uClibc-ng).
The system installed on your development station certainly already has
-a compilation toolchain that you can use to compile an application
-that runs on your system. If you窶决e using a PC, your compilation
-toolchain runs on an x86 processor and generates code for an x86
-processor. Under most Linux systems, the compilation toolchain uses
-the GNU libc (glibc) as the C standard library. This compilation
-toolchain is called the "host compilation toolchain". The machine on
-which it is running, and on which you窶决e working, is called the "host
-system" .
The compilation toolchain is provided by your distribution, and
-Buildroot has nothing to do with it (other than using it to build a
-cross-compilation toolchain and other tools that are run on the
-development host).
As said above, the compilation toolchain that comes with your system
-runs on and generates code for the processor in your host system. As
-your embedded system has a different processor, you need a
-cross-compilation toolchain - a compilation toolchain that runs on
-your host system but generates code for your target system (and
-target processor). For example, if your host system uses x86 and your
-target system uses ARM, the regular compilation toolchain on your host
-runs on x86 and generates code for x86, while the cross-compilation
-toolchain runs on x86 and generates code for ARM.
Buildroot provides two solutions for the cross-compilation toolchain:
-
-The internal toolchain backend, called
Buildroot toolchain in
- the configuration interface.
- -
-The external toolchain backend, called
External toolchain in
- the configuration interface.
-
The choice between these two solutions is done using the Toolchain
-Type option in the Toolchain menu. Once one solution has been
-chosen, a number of configuration options appear, they are detailed in
-the following sections.
6.1.1.ﾂInternal toolchain backend
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:
-
-Change the version of the Linux kernel headers used to build the
- toolchain. This item deserves a few explanations. In the process of
- building a cross-compilation toolchain, the C library is being
- built. This library provides the interface between userspace
- applications and the Linux kernel. In order to know how to "talk"
- to the Linux kernel, the C library needs to have access to the
- Linux kernel headers (i.e. the
.h files from the kernel), which
- define the interface between userspace and the kernel (system
- calls, data structures, etc.). Since this interface is backward
- compatible, the version of the Linux kernel headers used to build
- your toolchain do not need to match exactly the version of the
- Linux kernel you intend to run on your embedded system. They only
- need to have a version equal or older to the version of the Linux
- kernel you intend to run. If you use kernel headers that are more
- recent than the Linux kernel you run on your embedded system, then
- the C library might be using interfaces that are not provided by
- your Linux kernel.
- -
-Change the version of the GCC compiler, binutils and the C library.
-
-
-Select a number of toolchain options (uClibc only): whether the
- toolchain should have RPC support (used mainly for NFS),
- wide-char support, locale support (for internationalization),
- C++ support or thread support. Depending on which options you choose,
- the number of userspace applications and libraries visible in
- Buildroot menus will change: many applications and libraries require
- certain toolchain options to be enabled. Most packages show a comment
- when a certain toolchain option is required to be able to enable
- those packages. If needed, you can further refine the uClibc
- configuration by running
make uclibc-menuconfig. Note however that
- all packages in Buildroot are tested against the default uClibc
- configuration bundled in Buildroot: if you deviate from this
- configuration by removing features from uClibc, some packages may no
- longer build.
-
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, 窶弑nderstanding when a full rebuild is necessary窶.
Advantages of this backend:
-
-Well integrated with Buildroot
-
-
-Fast, only builds what窶冱 necessary
-
Drawbacks of this backend:
-
-Rebuilding the toolchain is needed when doing
make clean, which
- takes time. If you窶决e trying to reduce your build time, consider
- using the External toolchain backend.
-
6.1.2.ﾂExternal toolchain 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:
-
-Use a predefined external toolchain profile, and let Buildroot
- download, extract and install the toolchain. Buildroot already knows
- about a few CodeSourcery and Linaro toolchains. Just select the
- toolchain profile in
Toolchain from the available ones. This is
- definitely the easiest solution.
- -
-Use a predefined external toolchain profile, but instead of having
- Buildroot download and extract the toolchain, you can tell Buildroot
- where your toolchain is already installed on your system. Just
- select the toolchain profile in
Toolchain through the available
- ones, unselect Download toolchain automatically, and fill the
- Toolchain path text entry with the path to your cross-compiling
- toolchain.
- -
-Use a completely custom external toolchain. This is particularly
- useful for toolchains generated using crosstool-NG or with Buildroot
- itself. To do this, select the
Custom toolchain solution in the
- Toolchain list. You need to fill the Toolchain path, Toolchain
- prefix and External toolchain C library options. Then, you have
- to tell Buildroot what your external toolchain supports. If your
- external toolchain uses the glibc library, you only have to tell
- whether your toolchain supports C++ or not and whether it has
- built-in RPC support. If your external toolchain uses the uClibc
- library, then you have to tell Buildroot if it supports RPC,
- wide-char, locale, program invocation, threads and C++.
- At the beginning of the execution, Buildroot will tell you if
- the selected options do not match the toolchain configuration.
-
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, 窶廝uild an external toolchain with Buildroot窶) or with
-crosstool-NG.
Advantages of this backend:
-
-Allows to use well-known and well-tested cross-compilation
- toolchains.
-
-
-Avoids the build time of the cross-compilation toolchain, which is
- often very significant in the overall build time of an embedded
- Linux system.
-
Drawbacks of this backend:
-
-If your pre-built external toolchain has a bug, may be hard to get a
- fix from the toolchain vendor, unless you build your external
- toolchain by yourself using Buildroot or Crosstool-NG.
-
6.1.3.ﾂBuild an external toolchain with Buildroot
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:
-
-Select the appropriate Target options for your target CPU
- architecture
-
-
-In the Toolchain menu, keep the default of Buildroot toolchain
- for Toolchain type, and configure your toolchain as desired
-
-
-In the System configuration menu, select None as the Init
- system and none as /bin/sh
-
-
-In the Target packages menu, disable BusyBox
-
-
-In the Filesystem images menu, disable tar the root filesystem
-
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:
-
-Set Toolchain type to External toolchain
-
-
-Set Toolchain to Custom toolchain
-
-
-Set Toolchain origin to Toolchain to be downloaded and installed
-
-
-Set Toolchain URL to
file:///path/to/your/sdk/tarball.tar.gz
-
External toolchain wrapper
When using an external toolchain, Buildroot generates a wrapper program,
-that transparently passes the appropriate options (according to the
-configuration) to the external toolchain programs. In case you need to
-debug this wrapper to check exactly what arguments are passed, you can
-set the environment variable BR2_DEBUG_WRAPPER to either one of:
-
-
0, empty or not set: no debug
- -
-
1: trace all arguments on a single line
- -
-
2: trace one argument per line
-
On a Linux system, the /dev directory contains special files, called
-device files, that allow userspace applications to access the
-hardware devices managed by the Linux kernel. Without these device
-files, your userspace applications would not be able to use the
-hardware devices, even if they are properly recognized by the Linux
-kernel.
Under System configuration, /dev management, Buildroot offers four
-different solutions to handle the /dev directory :
-
-The first solution is Static using device table. This is the old
- classical way of handling device files in Linux. With this method,
- the device files are persistently stored in the root filesystem
- (i.e. they persist across reboots), and there is nothing that will
- automatically create and remove those device files when hardware
- devices are added or removed from the system. Buildroot therefore
- creates a standard set of device files using a device table, the
- default one being stored in
system/device_table_dev.txt in the
- Buildroot source code. This file is processed when Buildroot
- generates the final root filesystem image, and the device files
- are therefore not visible in the output/target directory. The
- BR2_ROOTFS_STATIC_DEVICE_TABLE option allows to change the
- default device table used by Buildroot, or to add an additional
- device table, so that additional device files are created by
- Buildroot during the build. So, if you use this method, and a
- device file is missing in your system, you can for example create
- a board/<yourcompany>/<yourproject>/device_table_dev.txt file
- that contains the description of your additional device files,
- and then you can set BR2_ROOTFS_STATIC_DEVICE_TABLE to
- system/device_table_dev.txt
- board/<yourcompany>/<yourproject>/device_table_dev.txt. For more
- details about the format of the device table file, see
- Chapterﾂ25, Makedev syntax documentation.
- -
-The second solution is Dynamic using devtmpfs only. devtmpfs is
- a virtual filesystem inside the Linux kernel that has been
- introduced in kernel 2.6.32 (if you use an older kernel, it is not
- possible to use this option). When mounted in
/dev, this virtual
- filesystem will automatically make device files appear and
- disappear as hardware devices are added and removed from the
- system. This filesystem is not persistent across reboots: it is
- filled dynamically by the kernel. Using devtmpfs requires the
- following kernel configuration options to be enabled:
- CONFIG_DEVTMPFS and CONFIG_DEVTMPFS_MOUNT. When Buildroot is in
- charge of building the Linux kernel for your embedded device, it
- makes sure that those two options are enabled. However, if you
- build your Linux kernel outside of Buildroot, then it is your
- responsibility to enable those two options (if you fail to do so,
- your Buildroot system will not boot).
- -
-The third solution is Dynamic using devtmpfs + mdev. This method
- also relies on the devtmpfs virtual filesystem detailed above (so
- the requirement to have
CONFIG_DEVTMPFS and
- CONFIG_DEVTMPFS_MOUNT enabled in the kernel configuration still
- apply), but adds the mdev userspace utility on top of it. mdev
- is a program part of BusyBox that the kernel will call every time a
- device is added or removed. Thanks to the /etc/mdev.conf
- configuration file, mdev can be configured to for example, set
- specific permissions or ownership on a device file, call a script
- or application whenever a device appears or disappear,
- etc. Basically, it allows userspace to react on device addition
- and removal events. mdev can for example be used to automatically
- load kernel modules when devices appear on the system. mdev is
- also important if you have devices that require a firmware, as it
- will be responsible for pushing the firmware contents to the
- kernel. mdev is a lightweight implementation (with fewer
- features) of udev. For more details about mdev and the syntax
- of its configuration file, see
- http://git.busybox.net/busybox/tree/docs/mdev.txt.
- -
-The fourth solution is Dynamic using devtmpfs + eudev. This
- method also relies on the devtmpfs virtual filesystem detailed
- above, but adds the
eudev userspace daemon on top of it. eudev
- is a daemon that runs in the background, and gets called by the
- kernel when a device gets added or removed from the system. It is a
- more heavyweight solution than mdev, but provides higher
- flexibility. eudev is a standalone version of udev, the
- original userspace daemon used in most desktop Linux distributions,
- which is now part of Systemd. For more details, see
- http://en.wikipedia.org/wiki/Udev.
-
The Buildroot developers recommendation is to start with the Dynamic
-using devtmpfs only solution, until you have the need for userspace
-to be notified when devices are added/removed, or if firmwares are
-needed, in which case Dynamic using devtmpfs + mdev is usually a
-good solution.
Note that if systemd is chosen as init system, /dev management will
-be performed by the udev program provided by systemd.
The init program is the first userspace program started by the
-kernel (it carries the PID number 1), and is responsible for starting
-the userspace services and programs (for example: web server,
-graphical applications, other network servers, etc.).
Buildroot allows to use three different types of init systems, which
-can be chosen from System configuration, Init system:
-
-The first solution is BusyBox. Amongst many programs, BusyBox has
- an implementation of a basic
init program, which is sufficient
- for most embedded systems. Enabling the BR2_INIT_BUSYBOX will
- ensure BusyBox will build and install its init program. This is
- the default solution in Buildroot. The BusyBox init program will
- read the /etc/inittab file at boot to know what to do. The syntax
- of this file can be found in
- http://git.busybox.net/busybox/tree/examples/inittab (note that
- BusyBox inittab syntax is special: do not use a random inittab
- documentation from the Internet to learn about BusyBox
- inittab). The default inittab in Buildroot is stored in
- system/skeleton/etc/inittab. Apart from mounting a few important
- filesystems, the main job the default inittab does is to start the
- /etc/init.d/rcS shell script, and start a getty program (which
- provides a login prompt).
- -
-The second solution is systemV. This solution uses the old
- traditional sysvinit program, packed in Buildroot in
-
package/sysvinit. This was the solution used in most desktop
- Linux distributions, until they switched to more recent
- alternatives such as Upstart or Systemd. sysvinit also works with
- an inittab file (which has a slightly different syntax than the
- one from BusyBox). The default inittab installed with this init
- solution is located in package/sysvinit/inittab.
- -
-The third solution is systemd.
systemd is the new generation
- init system for Linux. It does far more than traditional init
- programs: aggressive parallelization capabilities, uses socket and
- D-Bus activation for starting services, offers on-demand starting
- of daemons, keeps track of processes using Linux control groups,
- supports snapshotting and restoring of the system state,
- etc. systemd will be useful on relatively complex embedded
- systems, for example the ones requiring D-Bus and services
- communicating between each other. It is worth noting that systemd
- brings a fairly big number of large dependencies: dbus, udev
- and more. For more details about systemd, see
- http://www.freedesktop.org/wiki/Software/systemd.
-
The solution recommended by Buildroot developers is to use the
-BusyBox init as it is sufficient for most embedded
-systems. systemd can be used for more complex situations.
Chapterﾂ8.ﾂGeneral Buildroot usage
This is a collection of tips that help you make the most of Buildroot.
Display all commands executed by make:ﾂ
-
$ make V=1 <target>
-
Display the list of boards with a defconfig:ﾂ
-
$ make list-defconfigs
-
Display all available targets:ﾂ
-
$ make help
-
Not all targets are always available,
-some settings in the .config file may hide some targets:
-
-
busybox-menuconfig only works when busybox is enabled;
- -
-
linux-menuconfig and linux-savedefconfig only work when
- linux is enabled;
- -
-
uclibc-menuconfig is only available when the uClibc C library is
- selected in the internal toolchain backend;
- -
-
barebox-menuconfig and barebox-savedefconfig only work when the
- barebox bootloader is enabled.
- -
-
uboot-menuconfig and uboot-savedefconfig only work when the
- U-Boot bootloader is enabled.
-
Cleaning:ﾂExplicit cleaning is required when any of the architecture or toolchain
-configuration options are changed.
To delete all build products (including build directories, host, staging
-and target trees, the images and the toolchain):
$ make clean
Generating the manual:ﾂThe present manual sources are located in the docs/manual directory.
-To generate the manual:
$ make manual-clean
- $ make manual
The manual outputs will be generated in output/docs/manual.
Resetting Buildroot for a new target:ﾂTo delete all build products as well as the configuration:
$ make distclean
Notes.ﾂIf ccache is enabled, running make clean or distclean does
-not empty the compiler cache used by Buildroot. To delete it, refer
-to Sectionﾂ8.14.3, 窶弑sing ccache in Buildroot窶.
Dumping the internal make variables:ﾂOne can dump the variables known to make, along with their values:
$ make -s printvars VARS='VARIABLE1 VARIABLE2'
- VARIABLE1=value_of_variable
- VARIABLE2=value_of_variable
It is possible to tweak the output using some variables:
-
-
VARS will limit the listing to variables which names match the
- specified make-patterns - this must be set else nothing is printed
- -
-
QUOTED_VARS, if set to YES, will single-quote the value
- -
-
RAW_VARS, if set to YES, will print the unexpanded value
-
For example:
$ make -s printvars VARS=BUSYBOX_%DEPENDENCIES
- BUSYBOX_DEPENDENCIES=skeleton toolchain
- BUSYBOX_FINAL_ALL_DEPENDENCIES=skeleton toolchain
- BUSYBOX_FINAL_DEPENDENCIES=skeleton toolchain
- BUSYBOX_FINAL_PATCH_DEPENDENCIES=
- BUSYBOX_RDEPENDENCIES=ncurses util-linux
$ make -s printvars VARS=BUSYBOX_%DEPENDENCIES QUOTED_VARS=YES
- BUSYBOX_DEPENDENCIES='skeleton toolchain'
- BUSYBOX_FINAL_ALL_DEPENDENCIES='skeleton toolchain'
- BUSYBOX_FINAL_DEPENDENCIES='skeleton toolchain'
- BUSYBOX_FINAL_PATCH_DEPENDENCIES=''
- BUSYBOX_RDEPENDENCIES='ncurses util-linux'
$ make -s printvars VARS=BUSYBOX_%DEPENDENCIES RAW_VARS=YES
- BUSYBOX_DEPENDENCIES=skeleton toolchain
- BUSYBOX_FINAL_ALL_DEPENDENCIES=$(sort $(BUSYBOX_FINAL_DEPENDENCIES) $(BUSYBOX_FINAL_PATCH_DEPENDENCIES))
- BUSYBOX_FINAL_DEPENDENCIES=$(sort $(BUSYBOX_DEPENDENCIES))
- BUSYBOX_FINAL_PATCH_DEPENDENCIES=$(sort $(BUSYBOX_PATCH_DEPENDENCIES))
- BUSYBOX_RDEPENDENCIES=ncurses util-linux
The output of quoted variables can be reused in shell scripts, for example:
$ eval $(make -s printvars VARS=BUSYBOX_DEPENDENCIES QUOTED_VARS=YES)
- $ echo $BUSYBOX_DEPENDENCIES
- skeleton toolchain
8.2.ﾂUnderstanding when a full rebuild is necessary
Buildroot does not attempt to detect what parts of the system should
-be rebuilt when the system configuration is changed through make
-menuconfig, make xconfig or one of the other configuration
-tools. In some cases, Buildroot should rebuild the entire system, in
-some cases, only a specific subset of packages. But detecting this in
-a completely reliable manner is very difficult, and therefore the
-Buildroot developers have decided to simply not attempt to do this.
Instead, it is the responsibility of the user to know when a full
-rebuild is necessary. As a hint, here are a few rules of thumb that
-can help you understand how to work with Buildroot:
-
-When the target architecture configuration is changed, a complete
- rebuild is needed. Changing the architecture variant, the binary
- format or the floating point strategy for example has an impact on
- the entire system.
-
-
-When the toolchain configuration is changed, a complete rebuild
- generally is needed. Changing the toolchain configuration often
- involves changing the compiler version, the type of C library or
- its configuration, or some other fundamental configuration item,
- and these changes have an impact on the entire system.
-
-
-When an additional package is added to the configuration, a full
- rebuild is not necessarily needed. Buildroot will detect that this
- package has never been built, and will build it. However, if this
- package is a library that can optionally be used by packages that
- have already been built, Buildroot will not automatically rebuild
- those. Either you know which packages should be rebuilt, and you
- can rebuild them manually, or you should do a full rebuild. For
- example, let窶冱 suppose you have built a system with the
ctorrent
- package, but without openssl. Your system works, but you realize
- you would like to have SSL support in ctorrent, so you enable the
- openssl package in Buildroot configuration and restart the
- build. Buildroot will detect that openssl should be built and
- will be build it, but it will not detect that ctorrent should be
- rebuilt to benefit from openssl to add OpenSSL support. You will
- either have to do a full rebuild, or rebuild ctorrent itself.
- -
-When a package is removed from the configuration, Buildroot does
- not do anything special. It does not remove the files installed by
- this package from the target root filesystem or from the toolchain
- sysroot. A full rebuild is needed to get rid of this
- package. However, generally you don窶冲 necessarily need this package
- to be removed right now: you can wait for the next lunch break to
- restart the build from scratch.
-
-
-When the sub-options of a package are changed, the package is not
- automatically rebuilt. After making such changes, rebuilding only
- this package is often sufficient, unless enabling the package
- sub-option adds some features to the package that are useful for
- another package which has already been built. Again, Buildroot does
- not track when a package should be rebuilt: once a package has been
- built, it is never rebuilt unless explicitly told to do so.
-
-
-When a change to the root filesystem skeleton is made, a full
- rebuild is needed. However, when changes to the root filesystem
- overlay, a post-build script or a post-image script are made,
- there is no need for a full rebuild: a simple
make invocation
- will take the changes into account.
- -
-When a package listed in
FOO_DEPENDENCIES is rebuilt or removed,
- the package foo is not automatically rebuilt. For example, if a
- package bar is listed in FOO_DEPENDENCIES with FOO_DEPENDENCIES
- = bar and the configuration of the bar package is changed, the
- configuration change would not result in a rebuild of package foo
- automatically. In this scenario, you may need to either rebuild any
- packages in your build which reference bar in their DEPENDENCIES,
- or perform a full rebuild to ensure any bar dependent packages are
- up to date.
-
Generally speaking, when you窶决e facing a build error and you窶决e unsure
-of the potential consequences of the configuration changes you窶况e
-made, do a full rebuild. If you get the same build error, then you are
-sure that the error is not related to partial rebuilds of packages,
-and if this error occurs with packages from the official Buildroot, do
-not hesitate to report the problem! As your experience with Buildroot
-progresses, you will progressively learn when a full rebuild is really
-necessary, and you will save more and more time.
For reference, a full rebuild is achieved by running:
$ make clean all
8.3.ﾂUnderstanding how to rebuild packages
One of the most common questions asked by Buildroot users is how to
-rebuild a given package or how to remove a package without rebuilding
-everything from scratch.
Removing a package is unsupported by Buildroot without
-rebuilding from scratch. This is because Buildroot doesn窶冲 keep track
-of which package installs what files in the output/staging and
-output/target directories, or which package would be compiled differently
-depending on the availability of another package.
The easiest way to rebuild a single package from scratch is to remove
-its build directory in output/build. Buildroot will then re-extract,
-re-configure, re-compile and re-install this package from scratch. You
-can ask buildroot to do this with the make <package>-dirclean command.
On the other hand, if you only want to restart the build process of a
-package from its compilation step, you can run make <package>-rebuild. It
-will restart the compilation and installation of the package, but not from
-scratch: it basically re-executes make and make install inside the package,
-so it will only rebuild files that changed.
If you want to restart the build process of a package from its configuration
-step, you can run make <package>-reconfigure. It will restart the
-configuration, compilation and installation of the package.
While <package>-rebuild implies <package>-reinstall and
-<package>-reconfigure implies <package>-rebuild, these targets as well
-as <package> only act on the said package, and do not trigger re-creating
-the root filesystem image. If re-creating the root filesystem in necessary,
-one should in addition run make or make all.
Internally, Buildroot creates so-called stamp files to keep track of
-which build steps have been completed for each package. They are
-stored in the package build directory,
-output/build/<package>-<version>/ and are named
-.stamp_<step-name>. The commands detailed above simply manipulate
-these stamp files to force Buildroot to restart a specific set of
-steps of a package build process.
Further details about package special make targets are explained in
-Sectionﾂ8.14.5, 窶弃ackage-specific make targets窶.
If you intend to do an offline build and just want to download
-all sources that you previously selected in the configurator
-(menuconfig, nconfig, xconfig or gconfig), then issue:
$ make source
You can now disconnect or copy the content of your dl
-directory to the build-host.
8.5.ﾂBuilding out-of-tree
As default, everything built by Buildroot is stored in the directory
-output in the Buildroot tree.
Buildroot also supports building out of tree with a syntax similar to
-the Linux kernel. To use it, add O=<directory> to the make command
-line:
$ make O=/tmp/build
Or:
$ cd /tmp/build; make O=$PWD -C path/to/buildroot
All the output files will be located under /tmp/build. If the O
-path does not exist, Buildroot will create it.
Note: the O path can be either an absolute or a relative path, but if it窶冱
-passed as a relative path, it is important to note that it is interpreted
-relative to the main Buildroot source directory, not the current working
-directory.
When using out-of-tree builds, the Buildroot .config and temporary
-files are also stored in the output directory. This means that you can
-safely run multiple builds in parallel using the same source tree as
-long as they use unique output directories.
For ease of use, Buildroot generates a Makefile wrapper in the output
-directory - so after the first run, you no longer need to pass O=<窶ｦ>
-and -C <窶ｦ>, simply run (in the output directory):
$ make <target>
8.6.ﾂEnvironment variables
Buildroot also honors some environment variables, when they are passed
-to make or set in the environment:
-
-
HOSTCXX, the host C++ compiler to use
- -
-
HOSTCC, the host C compiler to use
- -
-
UCLIBC_CONFIG_FILE=<path/to/.config>, path to
- the uClibc configuration file, used to compile uClibc, if an
- internal toolchain is being built.
-
- Note that the uClibc configuration file can also be set from the
- configuration interface, so through the Buildroot .config file; this
- is the recommended way of setting it.
-
- -
-
BUSYBOX_CONFIG_FILE=<path/to/.config>, path to
- the BusyBox configuration file.
-
- Note that the BusyBox configuration file can also be set from the
- configuration interface, so through the Buildroot .config file; this
- is the recommended way of setting it.
-
- -
-
BR2_CCACHE_DIR to override the directory where
- Buildroot stores the cached files when using ccache.
-
- -
-
BR2_DL_DIR to override the directory in which
- Buildroot stores/retrieves downloaded files.
-
- Note that the Buildroot download directory can also be set from the
- configuration interface, so through the Buildroot .config file. See
- Sectionﾂ8.14.4, 窶廰ocation of downloaded packages窶 for more details on how you can set the download
- directory.
- -
-
BR2_GRAPH_ALT, if set and non-empty, to use an alternate color-scheme in
- build-time graphs
- -
-
BR2_GRAPH_OUT to set the filetype of generated graphs, either pdf (the
- default), or png.
- -
-
BR2_GRAPH_DEPS_OPTS to pass extra options to the dependency graph; see
- Sectionﾂ8.9, 窶廨raphing the dependencies between packages窶 for the accepted options
- -
-
BR2_GRAPH_DOT_OPTS is passed verbatim as options to the dot utility to
- draw the dependency graph.
- -
-
BR2_GRAPH_SIZE_OPTS to pass extra options to the size graph; see
- Sectionﾂ8.11, 窶廨raphing the filesystem size contribution of packages窶 for the acepted options
-
An example that uses config files located in the toplevel directory and
-in your $HOME:
$ make UCLIBC_CONFIG_FILE=uClibc.config BUSYBOX_CONFIG_FILE=$HOME/bb.config
If you want to use a compiler other than the default gcc
-or g++ for building helper-binaries on your host, then do
$ make HOSTCXX=g++-4.3-HEAD HOSTCC=gcc-4.3-HEAD
8.7.ﾂDealing efficiently with filesystem images
Filesystem images can get pretty big, depending on the filesystem you choose,
-the number of packages, whether you provisioned free space窶ｦ Yet, some
-locations in the filesystems images may just be empty (e.g. a long run of
-zeroes); such a file is called a sparse file.
Most tools can handle sparse files efficiently, and will only store or write
-those parts of a sparse file that are not empty.
For example:
-tar accepts the -S option to tell it to only store non-zero blocks
- of sparse files:
-
-
-
tar cf archive.tar -S [files窶ｦ] will efficiently store sparse files
- in a tarball
- -
-
tar xf archive.tar -S will efficiently store sparse files extracted
- from a tarball
-
-cp accepts the --sparse=WHEN option (WHEN is one of auto,
- never or always):
-
-
-
cp --sparse=always source.file dest.file will make dest.file a
- sparse file if source.file has long runs of zeroes
-
Other tools may have similar options. Please consult their respective man
-pages.
You can use sparse files if you need to store the filesystem images (e.g.
-to transfer from one machine to another), or if you need to send them (e.g.
-to the Q&A team).
Note however that flashing a filesystem image to a device while using the
-sparse mode of dd may result in a broken filesystem (e.g. the block bitmap
-of an ext2 filesystem may be corrupted; or, if you have sparse files in
-your filesystem, those parts may not be all-zeroes when read back). You
-should only use sparse files when handling files on the build machine, not
-when transferring them to an actual device that will be used on the target.
8.8.ﾂDetails about packages
Buildroot can produce a JSON blurb that describes the set of enabled
-packages in the current configuration, together with their
-dependencies, licenses and other metadata. This JSON blurb is produced
-by using the show-info make target:
make show-info
Buildroot can also produce details about packages as HTML and JSON
-output using the pkg-stats make target. Amongst other things, these
-details include whether known CVEs (security vulnerabilities) affect
-the packages in your current configuration. It also shows if there is
-a newer upstream version for those packages.
make pkg-stats
8.9.ﾂGraphing the dependencies between packages
One of Buildroot窶冱 jobs is to know the dependencies between packages,
-and make sure they are built in the right order. These dependencies
-can sometimes be quite complicated, and for a given system, it is
-often not easy to understand why such or such package was brought into
-the build by Buildroot.
In order to help understanding the dependencies, and therefore better
-understand what is the role of the different components in your
-embedded Linux system, Buildroot is capable of generating dependency
-graphs.
To generate a dependency graph of the full system you have compiled,
-simply run:
make graph-depends
You will find the generated graph in
-output/graphs/graph-depends.pdf.
If your system is quite large, the dependency graph may be too complex
-and difficult to read. It is therefore possible to generate the
-dependency graph just for a given package:
make <pkg>-graph-depends
You will find the generated graph in
-output/graph/<pkg>-graph-depends.pdf.
Note that the dependency graphs are generated using the dot tool
-from the Graphviz project, which you must have installed on your
-system to use this feature. In most distributions, it is available as
-the graphviz package.
By default, the dependency graphs are generated in the PDF
-format. However, by passing the BR2_GRAPH_OUT environment variable, you
-can switch to other output formats, such as PNG, PostScript or
-SVG. All formats supported by the -T option of the dot tool are
-supported.
BR2_GRAPH_OUT=svg make graph-depends
The graph-depends behaviour can be controlled by setting options in the
-BR2_GRAPH_DEPS_OPTS environment variable. The accepted options are:
-
-
--depth N, -d N, to limit the dependency depth to N levels. The
- default, 0, means no limit.
- -
-
--stop-on PKG, -s PKG, to stop the graph on the package PKG.
- PKG can be an actual package name, a glob, the keyword virtual
- (to stop on virtual packages), or the keyword host (to stop on
- host packages). The package is still present on the graph, but its
- dependencies are not.
- -
-
--exclude PKG, -x PKG, like --stop-on, but also omits PKG from
- the graph.
- -
-
--transitive, --no-transitive, to draw (or not) the transitive
- dependencies. The default is to not draw transitive dependencies.
- -
-
--colors R,T,H, the comma-separated list of colors to draw the
- root package (R), the target packages (T) and the host packages
- (H). Defaults to: lightblue,grey,gainsboro
-
BR2_GRAPH_DEPS_OPTS='-d 3 --no-transitive --colors=red,green,blue' make graph-depends
8.10.ﾂGraphing the build duration
When the build of a system takes a long time, it is sometimes useful
-to be able to understand which packages are the longest to build, to
-see if anything can be done to speed up the build. In order to help
-such build time analysis, Buildroot collects the build time of each
-step of each package, and allows to generate graphs from this data.
To generate the build time graph after a build, run:
make graph-build
This will generate a set of files in output/graphs :
-
-
build.hist-build.pdf, a histogram of the build time for each
- package, ordered in the build order.
- -
-
build.hist-duration.pdf, a histogram of the build time for each
- package, ordered by duration (longest first)
- -
-
build.hist-name.pdf, a histogram of the build time for each
- package, order by package name.
- -
-
build.pie-packages.pdf, a pie chart of the build time per package
- -
-
build.pie-steps.pdf, a pie chart of the global time spent in each
- step of the packages build process.
-
This graph-build target requires the Python Matplotlib and Numpy
-libraries to be installed (python-matplotlib and python-numpy on
-most distributions), and also the argparse module if you窶决e using a
-Python version older than 2.7 (python-argparse on most
-distributions).
By default, the output format for the graph is PDF, but a different
-format can be selected using the BR2_GRAPH_OUT environment variable. The
-only other format supported is PNG:
BR2_GRAPH_OUT=png make graph-build
8.11.ﾂGraphing the filesystem size contribution of packages
When your target system grows, it is sometimes useful to understand
-how much each Buildroot package is contributing to the overall root
-filesystem size. To help with such an analysis, Buildroot collects
-data about files installed by each package and using this data,
-generates a graph and CSV files detailing the size contribution of
-the different packages.
To generate these data after a build, run:
make graph-size
This will generate:
-
-
output/graphs/graph-size.pdf, a pie chart of the contribution of
- each package to the overall root filesystem size
- -
-
output/graphs/package-size-stats.csv, a CSV file giving the size
- contribution of each package to the overall root filesystem size
- -
-
output/graphs/file-size-stats.csv, a CSV file giving the size
- contribution of each installed file to the package it belongs, and
- to the overall filesystem size.
-
This graph-size target requires the Python Matplotlib library to be
-installed (python-matplotlib on most distributions), and also the
-argparse module if you窶决e using a Python version older than 2.7
-(python-argparse on most distributions).
Just like for the duration graph, a BR2_GRAPH_OUT environment variable
-is supported to adjust the output file format. See Sectionﾂ8.9, 窶廨raphing the dependencies between packages窶
-for details about this environment variable.
Additionally, one may set the environment variable BR2_GRAPH_SIZE_OPTS
-to further control the generated graph. Accepted options are:
-
-
--size-limit X, -l X, will group all packages which individual
- contribution is below X percent, to a single entry labelled Others
- in the graph. By default, X=0.01, which means packages each
- contributing less than 1% are grouped under Others. Accepted values
- are in the range [0.0..1.0].
- -
-
--iec, --binary, --si, --decimal, to use IEC (binary, powers
- of 1024) or SI (decimal, powers of 1000; the default) prefixes.
- -
-
--biggest-first, to sort packages in decreasing size order, rather
- than in increasing size order.
-
Note.ﾂThe collected filesystem size data is only meaningful after a complete
-clean rebuild. Be sure to run make clean all before using make
-graph-size.
To compare the root filesystem size of two different Buildroot compilations,
-for example after adjusting the configuration or when switching to another
-Buildroot release, use the size-stats-compare script. It takes two
-file-size-stats.csv files (produced by make graph-size) as input.
-Refer to the help text of this script for more details:
utils/size-stats-compare -h
8.12.ﾂTop-level parallel build
Note.ﾂThis section deals with a very experimental feature, which is known to
-break even in some non-unusual situations. Use at your own risk.
Buildroot has always been capable of using parallel build on a per
-package basis: each package is built by Buildroot using make -jN (or
-the equivalent invocation for non-make-based build systems). The level
-of parallelism is by default number of CPUs + 1, but it can be
-adjusted using the BR2_JLEVEL configuration option.
Until 2020.02, Buildroot was however building packages in a serial
-fashion: each package was built one after the other, without
-parallelization of the build between packages. As of 2020.02,
-Buildroot has experimental support for top-level parallel build,
-which allows some signicant build time savings by building packages
-that have no dependency relationship in parallel. This feature is
-however marked as experimental and is known not to work in some cases.
In order to use top-level parallel build, one must:
-
-Enable the option
BR2_PER_PACKAGE_DIRECTORIES in the Buildroot
-configuration
- -
-Use
make -jN when starting the Buildroot build
-
Internally, the BR2_PER_PACKAGE_DIRECTORIES will enable a mechanism
-called per-package directories, which will have the following
-effects:
-
-Instead of a global target directory and a global host directory
- common to all packages, per-package target and host directories
- will be used, in
$(O)/per-package/<pkg>/target/ and
- $(O)/per-package/<pkg>/host/ respectively. Those folders will be
- populated from the corresponding folders of the package dependencies
- at the beginning of <pkg> build. The compiler and all other tools
- will therefore only be able to see and access files installed by
- dependencies explicitly listed by <pkg>.
- -
-At the end of the build, the global target and host directories
- will be populated, located in
$(O)/target and $(O)/host
- respectively. This means that during the build, those folders will
- be empty and it窶冱 only at the very end of the build that they will
- be populated.
-
8.13.ﾂIntegration with Eclipse
While a part of the embedded Linux developers like classical text
-editors like Vim or Emacs, and command-line based interfaces, a number
-of other embedded Linux developers like richer graphical interfaces to
-do their development work. Eclipse being one of the most popular
-Integrated Development Environment, Buildroot integrates with Eclipse
-in order to ease the development work of Eclipse users.
Our integration with Eclipse simplifies the compilation, remote
-execution and remote debugging of applications and libraries that are
-built on top of a Buildroot system. It does not integrate the
-Buildroot configuration and build processes themselves with
-Eclipse. Therefore, the typical usage model of our Eclipse integration
-would be:
-
-Configure your Buildroot system with
make menuconfig, make
- xconfig or any other configuration interface provided with
- Buildroot.
- -
-Build your Buildroot system by running
make.
- -
-Start Eclipse to develop, execute and debug your own custom
- applications and libraries, that will rely on the libraries built
- and installed by Buildroot.
-
The Buildroot Eclipse integration installation process and usage is
-described in detail at
-https://github.com/mbats/eclipse-buildroot-bundle/wiki.
8.14.1.ﾂUsing the generated toolchain outside Buildroot
You may want to compile, for your target, your own programs or other
-software that are not packaged in Buildroot. In order to do this you
-can use the toolchain that was generated by Buildroot.
The toolchain generated by Buildroot is located by default in
-output/host/. The simplest way to use it is to add
-output/host/bin/ to your PATH environment variable and then to
-use ARCH-linux-gcc, ARCH-linux-objdump, ARCH-linux-ld, etc.
Alternatively, Buildroot can also export the toolchain and the development
-files of all selected packages, as an SDK, by running the command
-make sdk. This generates a tarball of the content of the host directory
-output/host/, named <TARGET-TUPLE>_sdk-buildroot.tar.gz (which can be
-overriden by setting the environment variable BR2_SDK_PREFIX) and
-located in the output directory output/images/.
This tarball can then be distributed to application developers, when
-they want to develop their applications that are not (yet) packaged as
-a Buildroot package.
Upon extracting the SDK tarball, the user must run the script
-relocate-sdk.sh (located at the top directory of the SDK), to make
-sure all paths are updated with the new location.
Alternatively, if you just want to prepare the SDK without generating
-the tarball (e.g. because you will just be moving the host directory,
-or will be generating the tarball on your own), Buildroot also allows
-you to just prepare the SDK with make prepare-sdk without actually
-generating a tarball.
For your convenience, by selecting the option
-BR2_PACKAGE_HOST_ENVIRONMENT_SETUP, you can get a
-environment-setup script installed in output/host/ and therefore
-in your SDK. This script can be sourced with
-. your/sdk/path/environment-setup to export a number of environment
-variables that will help cross-compile your projects using the
-Buildroot SDK: the PATH will contain the SDK binaries, standard
-autotools variables will be defined with the appropriate values, and
-CONFIGURE_FLAGS will contain basic ./configure options to
-cross-compile autotools projects. It also provides some useful
-commands. Note however that once this script is sourced, the
-environment is setup only for cross-compilation, and no longer for
-native compilation.
8.14.2.ﾂUsing gdb in Buildroot
Buildroot allows to do cross-debugging, where the debugger runs on the
-build machine and communicates with gdbserver on the target to
-control the execution of the program.
To achieve this:
-
-If you are using an internal toolchain (built by Buildroot), you
- must enable
BR2_PACKAGE_HOST_GDB, BR2_PACKAGE_GDB and
- BR2_PACKAGE_GDB_SERVER. This ensures that both the cross gdb and
- gdbserver get built, and that gdbserver gets installed to your target.
- -
-If you are using an external toolchain, you should enable
-
BR2_TOOLCHAIN_EXTERNAL_GDB_SERVER_COPY, which will copy the
- gdbserver included with the external toolchain to the target. If your
- external toolchain does not have a cross gdb or gdbserver, it is also
- possible to let Buildroot build them, by enabling the same options as
- for the internal toolchain backend.
-
Now, to start debugging a program called foo, you should run on the
-target:
gdbserver :2345 foo
This will cause gdbserver to listen on TCP port 2345 for a connection
-from the cross gdb.
Then, on the host, you should start the cross gdb using the following
-command line:
<buildroot>/output/host/bin/<tuple>-gdb -ix <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
8.14.3.ﾂUsing ccache in Buildroot
ccache is a compiler cache. It stores the
-object files resulting from each compilation process, and is able to
-skip future compilation of the same source file (with same compiler
-and same arguments) by using the pre-existing object files. When doing
-almost identical builds from scratch a number of times, it can nicely
-speed up the build process.
ccache support is integrated in Buildroot. You just have to enable
-Enable compiler cache in Build options. This will automatically
-build ccache and use it for every host and target compilation.
The cache is located in $HOME/.buildroot-ccache. It is stored
-outside of Buildroot output directory so that it can be shared by
-separate Buildroot builds. If you want to get rid of the cache, simply
-remove this directory.
You can get statistics on the cache (its size, number of hits,
-misses, etc.) by running make ccache-stats.
The make target ccache-options and the CCACHE_OPTIONS variable
-provide more generic access to the ccache. For example
# set cache limit size
-make CCACHE_OPTIONS="--max-size=5G" ccache-options
-
-# zero statistics counters
-make CCACHE_OPTIONS="--zero-stats" ccache-options
ccache makes a hash of the source files and of the compiler options.
-If a compiler option is different, the cached object file will not be
-used. Many compiler options, however, contain an absolute path to the
-staging directory. Because of this, building in a different output
-directory would lead to many cache misses.
To avoid this issue, buildroot has the Use relative paths option
-(BR2_CCACHE_USE_BASEDIR). This will rewrite all absolute paths that
-point inside the output directory into relative paths. Thus, changing
-the output directory no longer leads to cache misses.
A disadvantage of the relative paths is that they also end up to be
-relative paths in the object file. Therefore, for example, the debugger
-will no longer find the file, unless you cd to the output directory
-first.
See the
-ccache manual窶冱 section on "Compiling in different directories" for
-more details about this rewriting of absolute paths.
8.14.4.ﾂLocation of downloaded packages
The various tarballs that are downloaded by Buildroot are all stored
-in BR2_DL_DIR, which by default is the dl directory. If you want
-to keep a complete version of Buildroot which is known to be working
-with the associated tarballs, you can make a copy of this directory.
-This will allow you to regenerate the toolchain and the target
-filesystem with exactly the same versions.
If you maintain several Buildroot trees, it might be better to have a
-shared download location. This can be achieved by pointing the
-BR2_DL_DIR environment variable to a directory. If this is
-set, then the value of BR2_DL_DIR in the Buildroot configuration is
-overridden. The following line should be added to <~/.bashrc>.
export BR2_DL_DIR=<shared download location>
The download location can also be set in the .config file, with the
-BR2_DL_DIR option. Unlike most options in the .config file, this value
-is overridden by the BR2_DL_DIR environment variable.
8.14.5.ﾂPackage-specific make targets
Running make <package> builds and installs that particular package
-and its dependencies.
For packages relying on the Buildroot infrastructure, there are
-numerous special make targets that can be called independently like
-this:
make <package>-<target>
The package build targets are (in the order they are executed):
Additionally, there are some other useful make targets:
8.14.6.ﾂUsing Buildroot during development
The normal operation of Buildroot is to download a tarball, extract
-it, configure, compile and install the software component found inside
-this tarball. The source code is extracted in
-output/build/<package>-<version>, which is a temporary directory:
-whenever make clean is used, this directory is entirely removed, and
-re-created at the next make invocation. Even when a Git or
-Subversion repository is used as the input for the package source
-code, Buildroot creates a tarball out of it, and then behaves as it
-normally does with tarballs.
This behavior is well-suited when Buildroot is used mainly as an
-integration tool, to build and integrate all the components of an
-embedded Linux system. However, if one uses Buildroot during the
-development of certain components of the system, this behavior is not
-very convenient: one would instead like to make a small change to the
-source code of one package, and be able to quickly rebuild the system
-with Buildroot.
Making changes directly in output/build/<package>-<version> is not
-an appropriate solution, because this directory is removed on make
-clean.
Therefore, Buildroot provides a specific mechanism for this use case:
-the <pkg>_OVERRIDE_SRCDIR mechanism. Buildroot reads an override
-file, which allows the user to tell Buildroot the location of the
-source for certain packages.
The default location of the override file is $(CONFIG_DIR)/local.mk,
-as defined by the BR2_PACKAGE_OVERRIDE_FILE configuration option.
-$(CONFIG_DIR) is the location of the Buildroot .config file, so
-local.mk by default lives side-by-side with the .config file,
-which means:
-
-In the top-level Buildroot source directory for in-tree builds
- (i.e., when
O= is not used)
- -
-In the out-of-tree directory for out-of-tree builds (i.e., when
-
O= is used)
-
If a different location than these defaults is required, it can be
-specified through the BR2_PACKAGE_OVERRIDE_FILE configuration
-option.
In this override file, Buildroot expects to find lines of the form:
<pkg1>_OVERRIDE_SRCDIR = /path/to/pkg1/sources
-<pkg2>_OVERRIDE_SRCDIR = /path/to/pkg2/sources
For example:
LINUX_OVERRIDE_SRCDIR = /home/bob/linux/
-BUSYBOX_OVERRIDE_SRCDIR = /home/bob/busybox/
When Buildroot finds that for a given package, an
-<pkg>_OVERRIDE_SRCDIR has been defined, it will no longer attempt to
-download, extract and patch the package. Instead, it will directly use
-the source code available in the specified directory and make clean
-will not touch this directory. This allows to point Buildroot to your
-own directories, that can be managed by Git, Subversion, or any other
-version control system. To achieve this, Buildroot will use rsync to
-copy the source code of the component from the specified
-<pkg>_OVERRIDE_SRCDIR to output/build/<package>-custom/.
This mechanism is best used in conjunction with the make
-<pkg>-rebuild and make <pkg>-reconfigure targets. A make
-<pkg>-rebuild all sequence will rsync the source code from
-<pkg>_OVERRIDE_SRCDIR to output/build/<package>-custom (thanks to
-rsync, only the modified files are copied), and restart the build
-process of just this package.
In the example of the linux package above, the developer can then
-make a source code change in /home/bob/linux and then run:
make linux-rebuild all
and in a matter of seconds gets the updated Linux kernel image in
-output/images. Similarly, a change can be made to the BusyBox source
-code in /home/bob/busybox, and after:
make busybox-rebuild all
the root filesystem image in output/images contains the updated
-BusyBox.
Source trees for big projects often contain hundreds or thousands of
-files which are not needed for building, but will slow down the process
-of copying the sources with rsync. Optionally, it is possible define
-<pkg>_OVERRIDE_SRCDIR_RSYNC_EXCLUSIONS to skip syncing certain files
-from the source tree. For example, when working on the webkitgtk
-package, the following will exclude the tests and in-tree builds from
-a local WebKit source tree:
WEBKITGTK_OVERRIDE_SRCDIR = /home/bob/WebKit
-WEBKITGTK_OVERRIDE_SRCDIR_RSYNC_EXCLUSIONS = \
- --exclude JSTests --exclude ManualTests --exclude PerformanceTests \
- --exclude WebDriverTests --exclude WebKitBuild --exclude WebKitLibraries \
- --exclude WebKit.xcworkspace --exclude Websites --exclude Examples
By default, Buildroot skips syncing of VCS artifacts (e.g., the .git and
-.svn directories). Some packages prefer to have these VCS directories
-available during build, for example for automatically determining a precise
-commit reference for version information. To undo this built-in filtering at a
-cost of a slower speed, add these directories back:
LINUX_OVERRIDE_SRCDIR_RSYNC_EXCLUSIONS = --include .git
Chapterﾂ9.ﾂProject-specific customization
Typical actions you may need to perform for a given project are:
An important note regarding such project-specific customizations:
-please carefully consider which changes are indeed project-specific and
-which changes are also useful to developers outside your project. The
-Buildroot community highly recommends and encourages the upstreaming of
-improvements, packages and board support to the official Buildroot
-project. Of course, it is sometimes not possible or desirable to
-upstream because the changes are highly specific or proprietary.
This chapter describes how to make such project-specific customizations
-in Buildroot and how to store them in a way that you can build the same
-image in a reproducible way, even after running make clean. By
-following the recommended strategy, you can even use the same Buildroot
-tree to build multiple distinct projects!
9.1.ﾂRecommended directory structure
When customizing Buildroot for your project, you will be creating one or
-more project-specific files that need to be stored somewhere. While most
-of these files could be placed in any location as their path is to be
-specified in the Buildroot configuration, the Buildroot developers
-recommend a specific directory structure which is described in this
-section.
Orthogonal to this directory structure, you can choose where you place
-this structure itself: either inside the Buildroot tree, or outside of
-it using a br2-external tree. Both options are valid, the choice is up
-to you.
+-- board/
-| +-- <company>/
-| +-- <boardname>/
-| +-- linux.config
-| +-- busybox.config
-| +-- <other configuration files>
-| +-- post_build.sh
-| +-- post_image.sh
-| +-- rootfs_overlay/
-| | +-- etc/
-| | +-- <some file>
-| +-- patches/
-| +-- foo/
-| | +-- <some patch>
-| +-- libbar/
-| +-- <some other patches>
-|
-+-- configs/
-| +-- <boardname>_defconfig
-|
-+-- package/
-| +-- <company>/
-| +-- Config.in (if not using a br2-external tree)
-| +-- <company>.mk (if not using a br2-external tree)
-| +-- package1/
-| | +-- Config.in
-| | +-- package1.mk
-| +-- package2/
-| +-- Config.in
-| +-- package2.mk
-|
-+-- Config.in (if using a br2-external tree)
-+-- external.mk (if using a br2-external tree)
-+-- external.desc (if using a br2-external tree)
Details on the files shown above are given further in this chapter.
Note: if you choose to place this structure outside of the Buildroot
-tree but in a br2-external tree, the <company> and possibly <boardname>
-components may be superfluous and can be left out.
9.1.1.ﾂImplementing layered customizations
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.
9.2.ﾂKeeping customizations outside of Buildroot
As already briefly mentioned in Sectionﾂ9.1, 窶彝ecommended directory structure窶, you can
-place project-specific customizations in two locations:
-
-directly within the Buildroot tree, typically maintaining them using
- branches in a version control system so that upgrading to a newer
- Buildroot release is easy.
-
-
-outside of the Buildroot tree, using the br2-external mechanism.
- This mechanism allows to keep package recipes, board support and
- configuration files outside of the Buildroot tree, while still
- having them nicely integrated in the build logic. We call this
- location a br2-external tree. This section explains how to use
- the br2-external mechanism and what to provide in a br2-external
- tree.
-
One can tell Buildroot to use one or more br2-external trees by setting
-the BR2_EXTERNAL make variable set to the path(s) of the br2-external
-tree(s) to use. It can be passed to any Buildroot make invocation. It
-is automatically saved in the hidden .br2-external.mk file in the output
-directory. Thanks to this, there is no need to pass BR2_EXTERNAL at
-every make invocation. It can however be changed at any time by
-passing a new value, and can be removed by passing an empty value.
Note.ﾂThe path to a br2-external tree can be either absolute or relative.
-If it is passed as a relative path, it is important to note that it is
-interpreted relative to the main Buildroot source directory, not to
-the Buildroot output directory.
Note:ﾂIf using an br2-external tree from before Buildroot 2016.11, you need to
-convert it before you can use it with Buildroot 2016.11 onward. See
-Sectionﾂ27.2, 窶廴igrating to 2016.11窶 for help on doing so.
Some examples:
buildroot/ $ make BR2_EXTERNAL=/path/to/foo menuconfig
From now on, definitions from the /path/to/foo br2-external tree
-will be used:
buildroot/ $ make
-buildroot/ $ make legal-info
We can switch to another br2-external tree at any time:
buildroot/ $ make BR2_EXTERNAL=/where/we/have/bar xconfig
We can also use multiple br2-external trees:
buildroot/ $ make BR2_EXTERNAL=/path/to/foo:/where/we/have/bar menuconfig
Or disable the usage of any br2-external tree:
buildroot/ $ make BR2_EXTERNAL= xconfig
9.2.1.ﾂLayout of a br2-external tree
A br2-external tree must contain at least those three files, described
-in the following chapters:
-
-
external.desc
- -
-
external.mk
- -
-
Config.in
-
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.
That file describes the br2-external tree: the name and description
-for that br2-external tree.
The format for this file is line based, with each line starting by a
-keyword, followed by a colon and one or more spaces, followed by the
-value assigned to that keyword. There are two keywords currently
-recognised:
-name, mandatory, defines the name for that br2-external tree. That
- name must only use ASCII characters in the set [A-Za-z0-9_]; any
- other character is forbidden. Buildroot sets the variable
- BR2_EXTERNAL_$(NAME)_PATH to the absolute path of the br2-external
- tree, so that you can use it to refer to your br2-external tree. This
- variable is available both in Kconfig, so you can use it to source your
- Kconfig files (see below) and in the Makefile, so that you can use it
- to include other Makefiles (see below) or refer to other files (like
- data files) from your br2-external tree.
-
Note:ﾂSince it is possible to use multiple br2-external trees at once, this
- name is used by Buildroot to generate variables for each of those trees.
- That name is used to identify your br2-external tree, so try to come up
- with a name that really describes your br2-external tree, in order for
- it to be relatively unique, so that it does not clash with another name
- from another br2-external tree, especially if you are planning on
- somehow sharing your br2-external tree with third parties or using
- br2-external trees from third parties.
-
-
desc, optional, provides a short description for that br2-external
- tree. It shall fit on a single line, is mostly free-form (see below),
- and is used when displaying information about a br2-external tree (e.g.
- above the list of defconfig files, or as the prompt in the menuconfig);
- as such, it should relatively brief (40 chars is probably a good upper
- limit). The description is available in the BR2_EXTERNAL_$(NAME)_DESC
- variable.
-
Examples of names and the corresponding BR2_EXTERNAL_$(NAME)_PATH
-variables:
-
-
FOO 竊 BR2_EXTERNAL_FOO_PATH
- -
-
BAR_42 竊 BR2_EXTERNAL_BAR_42_PATH
-
In the following examples, it is assumed the name to be set to BAR_42.
Note:ﾂBoth BR2_EXTERNAL_$(NAME)_PATH and BR2_EXTERNAL_$(NAME)_DESC are
- available in the Kconfig files and the Makefiles. They are also
- exported in the environment so are available in post-build, post-image
- and in-fakeroot scripts.
The Config.in and external.mk files
Those files (which may each be empty) can be used to define package
-recipes (i.e. foo/Config.in and foo/foo.mk like for packages bundled
-in Buildroot itself) or other custom configuration options or make logic.
Buildroot automatically includes the Config.in from each br2-external
-tree to make it appear in the top-level configuration menu, and includes
-the external.mk from each br2-external tree with the rest of the
-makefile logic.
The main usage of this is to store package recipes. The recommended way
-to do this is to write a Config.in file that looks like:
source "$BR2_EXTERNAL_BAR_42_PATH/package/package1/Config.in"
-source "$BR2_EXTERNAL_BAR_42_PATH/package/package2/Config.in"
Then, have an external.mk file that looks like:
include $(sort $(wildcard $(BR2_EXTERNAL_BAR_42_PATH)/package/*/*.mk))
And then in $(BR2_EXTERNAL_BAR_42_PATH)/package/package1 and
-$(BR2_EXTERNAL_BAR_42_PATH)/package/package2 create normal
-Buildroot package recipes, as explained in Chapterﾂ18, Adding new packages to Buildroot.
-If you prefer, you can also group the packages in subdirectories
-called <boardname> and adapt the above paths accordingly.
You can also define custom configuration options in Config.in and
-custom make logic in external.mk.
One can store Buildroot defconfigs in the configs subdirectory of
-the br2-external tree. Buildroot will automatically show them in the
-output of make list-defconfigs and allow them to be loaded with the
-normal make <name>_defconfig command. They will be visible in the
-make list-defconfigs output, below an External configs label that
-contains the name of the br2-external tree they are defined in.
Note:ﾂIf a defconfig file is present in more than one br2-external tree, then
-the one from the last br2-external tree is used. It is thus possible
-to override a defconfig bundled in Buildroot or another br2-external
-tree.
For some packages, Buildroot provides a choice between two (or more)
-implementations of API-compatible such packages. For example, there is
-a choice to choose either libjpeg ot jpeg-turbo; there is one between
-openssl or libressl; there is one to select one of the known,
-pre-configured toolchains窶ｦ
It is possible for a br2-external to extend those choices, by providing
-a set of files that define those alternatives:
-
-
provides/toolchains.in defines the pre-configured toolchains, which
- will then be listed in the toolchain selection;
- -
-
provides/jpeg.in defines the alternative libjpeg implementations;
- -
-
provides/openssl.in defines the alternative openssl implementations;
- -
-
provides/skeleton.in defines the alternative skeleton implementations;
- -
-
provides/init.in defines the alternative init system implementations, this
- can be used to select a default skeleton for your init.
-
One can store all the board-specific configuration files there, such
-as the kernel configuration, the root filesystem overlay, or any other
-configuration file for which Buildroot allows to set the location (by
-using the BR2_EXTERNAL_$(NAME)_PATH variable). For example, you
-could set the paths to a global patch directory, to a rootfs overlay
-and to the kernel configuration file as follows (e.g. by running
-make menuconfig and filling in these options):
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
Here is an example layout using all features of br2-external (the sample
-content is shown for the file above it, when it is relevant to explain
-the br2-external tree; this is all entirely made up just for the sake of
-illustration, of course):
/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/init.in
- | |config BR2_INIT_MINE
- | | bool "my custom init"
- | | select BR2_PACKAGE_MY_INIT
- | | select BR2_PACKAGE_SKELETON_INIT_MINE if BR2_ROOTFS_SKELETON_DEFAULT
- | `----
- |
- |- provides/skeleton.in
- | |config BR2_ROOTFS_SKELETON_MINE
- | | bool "my custom skeleton"
- | | select BR2_PACKAGE_SKELETON_MINE
- | `----
- |- package/skeleton-mine/Config.in
- | |config BR2_PACKAGE_SKELETON_MINE
- | | bool
- | | select BR2_PACKAGE_HAS_SKELETON
- | |
- | |config BR2_PACKAGE_PROVIDES_SKELETON
- | | default "skeleton-mine" if BR2_PACKAGE_SKELETON_MINE
- | `----
- |- package/skeleton-mine/skeleton-mine.mk
- | |SKELETON_MINE_ADD_TOOLCHAIN_DEPENDENCY = NO
- | |SKELETON_MINE_ADD_SKELETON_DEPENDENCY = NO
- | |SKELETON_MINE_PROVIDES = skeleton
- | |SKELETON_MINE_INSTALL_STAGING = YES
- | |$(eval $(generic-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
- `----The br2-external tree will then be visible in the menuconfig (with
-the layout expanded):
External options --->
- *** Example br2-external tree (in /path/to/br2-ext-tree/)
- [ ] pkg-1
- [ ] pkg-2
- (0x10AD) my-board flash address
If you are using more than one br2-external tree, it would look like
-(with the layout expanded and the second one with name FOO_27 but no
-desc: field in external.desc):
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
Additionally, the jpeg provider will be visible in the jpeg choice:
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
And similarly for the toolchains:
Toolchain --->
- Toolchain () --->
- ( ) Custom toolchain
- *** Toolchains from: Example br2-external tree ***
- (X) my custom toolchain
Note.ﾂThe toolchain options in toolchain/toolchain-external-mine/Config.in.options
-will not appear in the Toolchain menu. They must be explicitly included
-from within the br2-external窶冱 top-level Config.in and will thus appear
-in the External options menu.
9.3.ﾂStoring the Buildroot configuration
The Buildroot configuration can be stored using the command
- make savedefconfig.
This strips the Buildroot configuration down by removing configuration
-options that are at their default value. The result is stored in a file
-called defconfig. If you want to save it in another place, change the
-BR2_DEFCONFIG option in the Buildroot configuration itself, or call
-make with make savedefconfig BR2_DEFCONFIG=<path-to-defconfig>.
The recommended place to store this defconfig is
-configs/<boardname>_defconfig. If you follow this recommendation, the
-configuration will be listed in make help and can be set again by
-running make <boardname>_defconfig.
Alternatively, you can copy the file to any other place and rebuild with
-make defconfig BR2_DEFCONFIG=<path-to-defconfig-file>.
9.4.ﾂStoring the configuration of other components
The configuration files for BusyBox, the Linux kernel, Barebox, U-Boot
-and uClibc should be stored as well if changed. For each of these
-components, a Buildroot configuration option exists to point to an input
-configuration file, e.g. BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE. To store
-their configuration, set these configuration options to a path where you
-want to save the configuration files, and then use the helper targets
-described below to actually store the configuration.
As explained in Sectionﾂ9.1, 窶彝ecommended directory structure窶, the recommended path to
-store these configuration files is
-board/<company>/<boardname>/foo.config.
Make sure that you create a configuration file before changing
-the BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE etc. options. Otherwise,
-Buildroot will try to access this config file, which doesn窶冲 exist
-yet, and will fail. You can create the configuration file by running
-make linux-menuconfig etc.
Buildroot provides a few helper targets to make the saving of
-configuration files easier.
-
-
make linux-update-defconfig saves the linux configuration to the
- path specified by BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE. It
- simplifies the config file by removing default values. However,
- this only works with kernels starting from 2.6.33. For earlier
- kernels, use make linux-update-config.
- -
-
make busybox-update-config saves the busybox configuration to the
- path specified by BR2_PACKAGE_BUSYBOX_CONFIG.
- -
-
make uclibc-update-config saves the uClibc configuration to the
- path specified by BR2_UCLIBC_CONFIG.
- -
-
make barebox-update-defconfig saves the barebox configuration to the
- path specified by BR2_TARGET_BAREBOX_CUSTOM_CONFIG_FILE.
- -
-
make uboot-update-defconfig saves the U-Boot configuration to the
- path specified by BR2_TARGET_UBOOT_CUSTOM_CONFIG_FILE.
- -
-For at91bootstrap3, no helper exists so you have to copy the config
- file manually to
BR2_TARGET_AT91BOOTSTRAP3_CUSTOM_CONFIG_FILE.
-
9.5.ﾂCustomizing the generated target filesystem
Besides changing the configuration through make *config,
-there are a few other ways to customize the resulting target filesystem.
The two recommended methods, which can co-exist, are root filesystem
-overlay(s) and post build script(s).
-
-Root filesystem overlays (
BR2_ROOTFS_OVERLAY)
- A filesystem overlay is a tree of files that is copied directly
- over the target filesystem after it has been built. To enable this
- feature, set config option BR2_ROOTFS_OVERLAY (in the System
- configuration menu) to the root of the overlay. You can even specify
- multiple overlays, space-separated. If you specify a relative path,
- it will be relative to the root of the Buildroot tree. Hidden
- directories of version control systems, like .git, .svn, .hg,
- etc., files called .empty and files ending in ~ are excluded from
- the copy.
When BR2_ROOTFS_MERGED_USR is enabled, then the overlay must not
- contain the /bin, /lib or /sbin directories, as Buildroot will
- create them as symbolic links to the relevant folders in /usr. In
- such a situation, should the overlay have any programs or libraries,
- they should be placed in /usr/bin, /usr/sbin and /usr/lib.
As shown in Sectionﾂ9.1, 窶彝ecommended directory structure窶, the recommended path for
- this overlay is board/<company>/<boardname>/rootfs-overlay.
-
-Post-build scripts (
BR2_ROOTFS_POST_BUILD_SCRIPT)
- Post-build scripts are shell scripts called after Buildroot builds
- all the selected software, but before the rootfs images are
- assembled. To enable this feature, specify a space-separated list of
- post-build scripts in config option BR2_ROOTFS_POST_BUILD_SCRIPT (in
- the System configuration menu). If you specify a relative path, it
- will be relative to the root of the Buildroot tree.
Using post-build scripts, you can remove or modify any file in your
- target filesystem. You should, however, use this feature with care.
- Whenever you find that a certain package generates wrong or unneeded
- files, you should fix that package rather than work around it with some
- post-build cleanup scripts.
As shown in Sectionﾂ9.1, 窶彝ecommended directory structure窶, the recommended path for
- this script is board/<company>/<boardname>/post_build.sh.
The post-build scripts are run with the main Buildroot tree as current
- working directory. The path to the target filesystem is passed as the
- first argument to each script. If the config option
- BR2_ROOTFS_POST_SCRIPT_ARGS is not empty, these arguments will be
- passed to the script too. All the scripts will be passed the exact
- same set of arguments, it is not possible to pass different sets of
- arguments to each script.
In addition, you may also use these environment variables:
-
-
BR2_CONFIG: the path to the Buildroot .config file
- -
-
CONFIG_DIR: the directory containing the .config file, and
- therefore the top-level Buildroot Makefile to use (which is
- correct for both in-tree and out-of-tree builds)
- -
-
HOST_DIR, STAGING_DIR, TARGET_DIR: see
- Sectionﾂ18.5.2, 窶generic-package reference窶
- -
-
BUILD_DIR: the directory where packages are extracted and built
- -
-
BINARIES_DIR: the place where all binary files (aka images) are
- stored
- -
-
BASE_DIR: the base output directory
-
Below three more methods of customizing the target filesystem are
-described, but they are not recommended.
-
-Direct modification of the target filesystem
-
For temporary modifications, you can modify the target filesystem
- directly and rebuild the image. The target filesystem is available
- under output/target/. After making your changes, run make to
- rebuild the target filesystem image.
This method allows you to do anything to the target filesystem, but if
- you need to clean your Buildroot tree using make clean, these
- changes will be lost. Such cleaning is necessary in several cases,
- refer to Sectionﾂ8.2, 窶弑nderstanding when a full rebuild is necessary窶 for details. This solution is therefore
- only useful for quick tests: changes do not survive the make clean
- command. Once you have validated your changes, you should make sure
- that they will persist after a make clean, using a root filesystem
- overlay or a post-build script.
-
-Custom target skeleton (
BR2_ROOTFS_SKELETON_CUSTOM)
- The root filesystem image is created from a target skeleton, on top of
- which all packages install their files. The skeleton is copied to the
- target directory output/target before any package is built and
- installed. The default target skeleton provides the standard Unix
- filesystem layout and some basic init scripts and configuration files.
If the default skeleton (available under system/skeleton) does not
- match your needs, you would typically use a root filesystem overlay or
- post-build script to adapt it. However, if the default skeleton is
- entirely different than what you need, using a custom skeleton may be
- more suitable.
To enable this feature, enable config option
- BR2_ROOTFS_SKELETON_CUSTOM and set BR2_ROOTFS_SKELETON_CUSTOM_PATH
- to the path of your custom skeleton. Both options are available in the
- System configuration menu. If you specify a relative path, it will
- be relative to the root of the Buildroot tree.
Custom skeletons don窶冲 need to contain the /bin, /lib or /sbin
- directories, since they are created automatically during the build.
- When BR2_ROOTFS_MERGED_USR is enabled, then the custom skeleton must
- not contain the /bin, /lib or /sbin directories, as Buildroot
- will create them as symbolic links to the relevant folders in /usr.
- In such a situation, should the skeleton have any programs or
- libraries, they should be placed in /usr/bin, /usr/sbin and
- /usr/lib.
This method is not recommended because it duplicates the entire
- skeleton, which prevents taking advantage of the fixes or improvements
- brought to the default skeleton in later Buildroot releases.
-
-Post-fakeroot scripts (
BR2_ROOTFS_POST_FAKEROOT_SCRIPT)
- When aggregating the final images, some parts of the process requires
- root rights: creating device nodes in /dev, setting permissions or
- ownership to files and directories窶ｦ To avoid requiring actual root
- rights, Buildroot uses fakeroot to simulate root rights. This is not
- a complete substitute for actually being root, but is enough for what
- Buildroot needs.
Post-fakeroot scripts are shell scripts that are called at the end of
- the fakeroot phase, right before the filesystem image generator is
- called. As such, they are called in the fakeroot context.
Post-fakeroot scripts can be useful in case you need to tweak the
- filesystem to do modifications that are usually only available to the
- root user.
Note:ﾂIt is recommended to use the existing mechanisms to set file permissions
- or create entries in /dev (see Sectionﾂ9.5.1, 窶彜etting file permissions and ownership and adding custom devices nodes窶) or
- to create users (see Sectionﾂ9.6, 窶廣dding custom user accounts窶)
Note:ﾂThe difference between post-build scripts (above) and fakeroot scripts,
- is that post-build scripts are not called in the fakeroot context.
Note:ﾂUsing fakeroot is not an absolute substitute for actually being root.
- fakeroot only ever fakes the file access rights and types (regular,
- block-or-char device窶ｦ) and uid/gid; these are emulated in-memory.
9.5.1.ﾂSetting file permissions and ownership and adding custom devices nodes
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, 窶彝ecommended 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窶冱 .mk file instead
-(see Sectionﾂ18.5.2, 窶generic-package reference窶).
9.6.ﾂAdding custom user accounts
Sometimes it is needed to add specific users in the target system.
-To cover this requirement, Buildroot provides support for so-called
-users tables. To use this feature, set config option
-BR2_ROOTFS_USERS_TABLES to a space-separated list of users tables,
-regular text files following the makeusers syntax.
As shown in Sectionﾂ9.1, 窶彝ecommended directory structure窶, the recommended location for
-such files is board/<company>/<boardname>/.
It should be noted that if the custom users are related to a specific
-application, you should set variable FOO_USERS in the package窶冱 .mk
-file instead (see Sectionﾂ18.5.2, 窶generic-package reference窶).
9.7.ﾂCustomization after the images have been created
While post-build scripts (Sectionﾂ9.5, 窶廚ustomizing the generated target filesystem窶) are run before
-building the filesystem image, kernel and bootloader, post-image
-scripts can be used to perform some specific actions after all images
-have been created.
Post-image scripts can for example be used to automatically extract your
-root filesystem tarball in a location exported by your NFS server, or
-to create a special firmware image that bundles your root filesystem and
-kernel image, or any other custom action required for your project.
To enable this feature, specify a space-separated list of post-image
-scripts in config option BR2_ROOTFS_POST_IMAGE_SCRIPT (in the System
-configuration menu). If you specify a relative path, it will be
-relative to the root of the Buildroot tree.
Just like post-build scripts, post-image scripts are run with the main
-Buildroot tree as current working directory. The path to the images
-output directory is passed as the first argument to each script. If the
-config option BR2_ROOTFS_POST_SCRIPT_ARGS is not empty, these
-arguments will be passed to the script too. All the scripts will be
-passed the exact same set of arguments, it is not possible to pass
-different sets of arguments to each script.
Again just like for the post-build scripts, the scripts have access to
-the environment variables BR2_CONFIG, HOST_DIR, STAGING_DIR,
-TARGET_DIR, BUILD_DIR, BINARIES_DIR, CONFIG_DIR and
-BASE_DIR.
The post-image scripts will be executed as the user that executes
-Buildroot, which should normally not be the root user. Therefore, any
-action requiring root permissions in one of these scripts will require
-special handling (usage of fakeroot or sudo), which is left to the
-script developer.
9.8.ﾂAdding project-specific patches
It is sometimes useful to apply extra patches to packages - on top of
-those provided in Buildroot. This might be used to support custom
-features in a project, for example, or when working on a new
-architecture.
The BR2_GLOBAL_PATCH_DIR configuration option can be used to specify
-a space separated list of one or more directories containing package
-patches.
For a specific version <packageversion> of a specific package
-<packagename>, patches are applied from BR2_GLOBAL_PATCH_DIR as
-follows:
-For every directory - <global-patch-dir> - that exists in
- BR2_GLOBAL_PATCH_DIR, a <package-patch-dir> will be determined as
- follows:
-
-
-
<global-patch-dir>/<packagename>/<packageversion>/ if the
- directory exists.
- -
-Otherwise,
<global-patch-dir>/<packagename> if the directory
- exists.
-
-Patches will then be applied from a <package-patch-dir> as
- follows:
-
-
-If a
series file exists in the package directory, then patches are
- applied according to the series file;
- -
-Otherwise, patch files matching
*.patch are applied in
- alphabetical order. So, to ensure they are applied in the right
- order, it is highly recommended to name the patch files like this:
- <number>-<description>.patch, where <number> refers to the
- apply order.
-
For information about how patches are applied for a package, see
-Sectionﾂ19.2, 窶廩ow patches are applied窶
The BR2_GLOBAL_PATCH_DIR option is the preferred method for
-specifying a custom patch directory for packages. It can be used to
-specify a patch directory for any package in buildroot. It should also
-be used in place of the custom patch directory options that are
-available for packages such as U-Boot and Barebox. By doing this, it
-will allow a user to manage their patches from one top-level
-directory.
The exception to BR2_GLOBAL_PATCH_DIR being the preferred method for
-specifying custom patches is BR2_LINUX_KERNEL_PATCH.
-BR2_LINUX_KERNEL_PATCH should be used to specify kernel patches that
-are available at a URL. Note: BR2_LINUX_KERNEL_PATCH specifies kernel
-patches that are applied after patches available in BR2_GLOBAL_PATCH_DIR,
-as it is done from a post-patch hook of the Linux package.
9.9.ﾂAdding project-specific packages
In general, any new package should be added directly in the package
-directory and submitted to the Buildroot upstream project. How to add
-packages to Buildroot in general is explained in full detail in
-Chapterﾂ18, Adding new packages to Buildroot and will not be repeated here. However, your
-project may need some proprietary packages that cannot be upstreamed.
-This section will explain how you can keep such project-specific
-packages in a project-specific directory.
As shown in Sectionﾂ9.1, 窶彝ecommended directory structure窶, the recommended location for
-project-specific packages is package/<company>/. If you are using the
-br2-external tree feature (see Sectionﾂ9.2, 窶廳eeping customizations outside of Buildroot窶) the recommended
-location is to put them in a sub-directory named package/ in your
-br2-external tree.
However, Buildroot will not be aware of the packages in this location,
-unless we perform some additional steps. As explained in
-Chapterﾂ18, Adding new packages to Buildroot, a package in Buildroot basically consists of two
-files: a .mk file (describing how to build the package) and a
-Config.in file (describing the configuration options for this
-package).
Buildroot will automatically include the .mk files in first-level
-subdirectories of the package directory (using the pattern
-package/*/*.mk). If we want Buildroot to include .mk files from
-deeper subdirectories (like package/<company>/package1/) then we
-simply have to add a .mk file in a first-level subdirectory that
-includes these additional .mk files. Therefore, create a file
-package/<company>/<company>.mk with following contents (assuming you
-have only one extra directory level below package/<company>/):
include $(sort $(wildcard package/<company>/*/*.mk))
For the Config.in files, create a file package/<company>/Config.in
-that includes the Config.in files of all your packages. An exhaustive
-list has to be provided since wildcards are not supported in the source command of kconfig.
-For example:
source "package/<company>/package1/Config.in"
-source "package/<company>/package2/Config.in"
Include this new file package/<company>/Config.in from
-package/Config.in, preferably in a company-specific menu to make
-merges with future Buildroot versions easier.
If using a br2-external tree, refer to Sectionﾂ9.2, 窶廳eeping customizations outside of Buildroot窶 for how
-to fill in those files.
9.10.ﾂQuick guide to storing your project-specific customizations
Earlier in this chapter, the different methods for making
-project-specific customizations have been described. This section will
-now summarize all this by providing step-by-step instructions to storing your
-project-specific customizations. Clearly, the steps that are not relevant to
-your project can be skipped.
-
-
make menuconfig to configure toolchain, packages and kernel.
- -
-
make linux-menuconfig to update the kernel config, similar for
- other configuration like busybox, uclibc, 窶ｦ
- -
-
mkdir -p board/<manufacturer>/<boardname>
-
-Set the following options to board/<manufacturer>/<boardname>/<package>.config
- (as far as they are relevant):
-
-
-
BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE
- -
-
BR2_PACKAGE_BUSYBOX_CONFIG
- -
-
BR2_UCLIBC_CONFIG
- -
-
BR2_TARGET_AT91BOOTSTRAP3_CUSTOM_CONFIG_FILE
- -
-
BR2_TARGET_BAREBOX_CUSTOM_CONFIG_FILE
- -
-
BR2_TARGET_UBOOT_CUSTOM_CONFIG_FILE
-
-Write the configuration files:
-
-
-
make linux-update-defconfig
- -
-
make busybox-update-config
- -
-
make uclibc-update-config
- -
-
cp <output>/build/at91bootstrap3-*/.config
- board/<manufacturer>/<boardname>/at91bootstrap3.config
- -
-
make barebox-update-defconfig
- -
-
make uboot-update-defconfig
-
-
-Create
board/<manufacturer>/<boardname>/rootfs-overlay/ and fill it
- with additional files you need on your rootfs, e.g.
- board/<manufacturer>/<boardname>/rootfs-overlay/etc/inittab.
- Set BR2_ROOTFS_OVERLAY
- to board/<manufacturer>/<boardname>/rootfs-overlay.
- -
-Create a post-build script
-
board/<manufacturer>/<boardname>/post_build.sh. Set
- BR2_ROOTFS_POST_BUILD_SCRIPT to
- board/<manufacturer>/<boardname>/post_build.sh
- -
-If additional setuid permissions have to be set or device nodes have
- to be created, create
board/<manufacturer>/<boardname>/device_table.txt
- and add that path to BR2_ROOTFS_DEVICE_TABLE.
- -
-If additional user accounts have to be created, create
-
board/<manufacturer>/<boardname>/users_table.txt and add that path
- to BR2_ROOTFS_USERS_TABLES.
- -
-To add custom patches to certain packages, set
BR2_GLOBAL_PATCH_DIR
- to board/<manufacturer>/<boardname>/patches/ and add your patches
- for each package in a subdirectory named after the package. Each
- patch should be called <packagename>-<num>-<description>.patch.
- -
-Specifically for the Linux kernel, there also exists the option
-
BR2_LINUX_KERNEL_PATCH with as main advantage that it can also
- download patches from a URL. If you do not need this,
- BR2_GLOBAL_PATCH_DIR is preferred. U-Boot, Barebox, at91bootstrap
- and at91bootstrap3 also have separate options, but these do not
- provide any advantage over BR2_GLOBAL_PATCH_DIR and will likely be
- removed in the future.
- -
-If you need to add project-specific packages, create
-
package/<manufacturer>/ and place your packages in that
- directory. Create an overall <manufacturer>.mk file that
- includes the .mk files of all your packages. Create an overall
- Config.in file that sources the Config.in files of all your
- packages. Include this Config.in file from Buildroot窶冱
- package/Config.in file.
- -
-
make savedefconfig to save the buildroot configuration.
- -
-
cp defconfig configs/<boardname>_defconfig
-
Chapterﾂ11.ﾂFrequently Asked Questions & Troubleshooting
11.1.ﾂThe boot hangs after Starting network窶ｦ
If the boot process seems to hang after the following messages
-(messages not necessarily exactly similar, depending on the list of
-packages selected):
Freeing init memory: 3972K
-Initializing random number generator... done.
-Starting network...
-Starting dropbear sshd: generating rsa key... generating dsa key... OK
then it means that your system is running, but didn窶冲 start a shell on
-the serial console. In order to have the system start a shell on your
-serial console, you have to go into the Buildroot configuration, in
-System configuration, modify Run a getty (login prompt) after boot
-and set the appropriate port and baud rate in the getty options
-submenu. This will automatically tune the /etc/inittab file of the
-generated system so that a shell starts on the correct serial port.
11.2.ﾂWhy is there no compiler on the target?
It has been decided that support for the native compiler on the
-target would be stopped from the Buildroot-2012.11 release because:
-
-this feature was neither maintained nor tested, and often broken;
-
-
-this feature was only available for Buildroot toolchains;
-
-
-Buildroot mostly targets small or very small target hardware
- with limited resource onboard (CPU, ram, mass-storage), for which
- compiling on the target does not make much sense;
-
-
-Buildroot aims at easing the cross-compilation, making native
- compilation on the target unnecessary.
-
If you need a compiler on your target anyway, then Buildroot is not
-suitable for your purpose. In such case, you need a real
-distribution and you should opt for something like:
11.3.ﾂWhy are there no development files on the target?
Since there is no compiler available on the target (see
-Sectionﾂ11.2, 窶弩hy is there no compiler on the target?窶), it does not make sense to waste
-space with headers or static libraries.
Therefore, those files are always removed from the target since the
-Buildroot-2012.11 release.
11.4.ﾂWhy is there no documentation on the target?
Because Buildroot mostly targets small or very small target
-hardware with limited resource onboard (CPU, ram, mass-storage), it
-does not make sense to waste space with the documentation data.
If you need documentation data on your target anyway, then Buildroot
-is not suitable for your purpose, and you should look for a real
-distribution (see: Sectionﾂ11.2, 窶弩hy is there no compiler on the target?窶).
11.5.ﾂWhy are some packages not visible in the Buildroot config menu?
If a package exists in the Buildroot tree and does not appear in the
-config menu, this most likely means that some of the package窶冱
-dependencies are not met.
To know more about the dependencies of a package, search for the
-package symbol in the config menu (see Sectionﾂ8.1, 窶make tips窶).
Then, you may have to recursively enable several options (which
-correspond to the unmet dependencies) to finally be able to select
-the package.
If the package is not visible due to some unmet toolchain options,
-then you should certainly run a full rebuild (see Sectionﾂ8.1, 窶make tips窶 for
-more explanations).
11.6.ﾂWhy not use the target directory as a chroot directory?
There are plenty of reasons to not use the target directory a chroot
-one, among these:
-
-file ownerships, modes and permissions are not correctly set in the
- target directory;
-
-
-device nodes are not created in the target directory.
-
For these reasons, commands run through chroot, using the target
-directory as the new root, will most likely fail.
If you want to run the target filesystem inside a chroot, or as an NFS
-root, then use the tarball image generated in images/ and extract it
-as root.
11.7.ﾂWhy doesn窶冲 Buildroot generate binary packages (.deb, .ipkg窶ｦ)?
One feature that is often discussed on the Buildroot list is the
-general topic of "package management". To summarize, the idea
-would be to add some tracking of which Buildroot package installs
-what files, with the goals of:
-
-being able to remove files installed by a package when this package
- gets unselected from the menuconfig;
-
-
-being able to generate binary packages (ipk or other format) that
- can be installed on the target without re-generating a new root
- filesystem image.
-
In general, most people think it is easy to do: just track which package
-installed what and remove it when the package is unselected. However, it
-is much more complicated than that:
-
-It is not only about the
target/ directory, but also the sysroot in
- host/<tuple>/sysroot and the host/ directory itself. All files
- installed in those directories by various packages must be tracked.
- -
-When a package is unselected from the configuration, it is not
- sufficient to remove just the files it installed. One must also
- remove all its reverse dependencies (i.e. packages relying on it)
- and rebuild all those packages. For example, package A depends
- optionally on the OpenSSL library. Both are selected, and Buildroot
- is built. Package A is built with crypto support using OpenSSL.
- Later on, OpenSSL gets unselected from the configuration, but
- package A remains (since OpenSSL is an optional dependency, this
- is possible.) If only OpenSSL files are removed, then the files
- installed by package A are broken: they use a library that is no
- longer present on the target. Although this is technically doable,
- it adds a lot of complexity to Buildroot, which goes against the
- simplicity we try to stick to.
-
-
-In addition to the previous problem, there is the case where the
- optional dependency is not even known to Buildroot. For example,
- package A in version 1.0 never used OpenSSL, but in version 2.0 it
- automatically uses OpenSSL if available. If the Buildroot .mk file
- hasn窶冲 been updated to take this into account, then package A will
- not be part of the reverse dependencies of OpenSSL and will not be
- removed and rebuilt when OpenSSL is removed. For sure, the .mk file
- of package A should be fixed to mention this optional dependency,
- but in the mean time, you can have non-reproducible behaviors.
-
-
-The request is to also allow changes in the menuconfig to be
- applied on the output directory without having to rebuild
- everything from scratch. However, this is very difficult to achieve
- in a reliable way: what happens when the suboptions of a package
- are changed (we would have to detect this, and rebuild the package
- from scratch and potentially all its reverse dependencies), what
- happens if toolchain options are changed, etc. At the moment, what
- Buildroot does is clear and simple so its behaviour is very
- reliable and it is easy to support users. If configuration changes
- done in menuconfig are applied after the next make, then it has to
- work correctly and properly in all situations, and not have some
- bizarre corner cases. The risk is to get bug reports like "I have
- enabled package A, B and C, then ran make, then disabled package
- C and enabled package D and ran make, then re-enabled package C
- and enabled package E and then there is a build failure". Or worse
- "I did some configuration, then built, then did some changes,
- built, some more changes, built, some more changes, built, and now
- it fails, but I don窶冲 remember all the changes I did and in which
- order". This will be impossible to support.
-
For all these reasons, the conclusion is that adding tracking of
-installed files to remove them when the package is unselected, or to
-generate a repository of binary packages, is something that is very
-hard to achieve reliably and will add a lot of complexity.
On this matter, the Buildroot developers make this position statement:
-
-Buildroot strives to make it easy to generate a root filesystem (hence
- the name, by the way.) That is what we want to make Buildroot good at:
- building root filesystems.
-
-
-Buildroot is not meant to be a distribution (or rather, a distribution
- generator.) It is the opinion of most Buildroot developers that this
- is not a goal we should pursue. We believe that there are other tools
- better suited to generate a distro than Buildroot is. For example,
- Open Embedded, or openWRT,
- are such tools.
-
-
-We prefer to push Buildroot in a direction that makes it easy (or even
- easier) to generate complete root filesystems. This is what makes
- Buildroot stands out in the crowd (among other things, of course!)
-
-
-We believe that for most embedded Linux systems, binary packages are
- not necessary, and potentially harmful. When binary packages are
- used, it means that the system can be partially upgraded, which
- creates an enormous number of possible combinations of package
- versions that should be tested before doing the upgrade on the
- embedded device. On the other hand, by doing complete system
- upgrades by upgrading the entire root filesystem image at once,
- the image deployed to the embedded system is guaranteed to really
- be the one that has been tested and validated.
-
11.8.ﾂHow to speed-up the build process?
Since Buildroot often involves doing full rebuilds of the entire
-system that can be quite long, we provide below a number of tips to
-help reduce the build time:
-
-Use a pre-built external toolchain instead of the default Buildroot
- internal toolchain. By using a pre-built Linaro toolchain (on ARM)
- or a Sourcery CodeBench toolchain (for ARM, x86, x86-64, MIPS,
- etc.), you will save the build time of the toolchain at each
- complete rebuild, approximately 15 to 20 minutes. Note that
- temporarily using an external toolchain does not prevent you to
- switch back to an internal toolchain (that may provide a higher
- level of customization) once the rest of your system is working;
-
-
-Use the
ccache compiler cache (see: Sectionﾂ8.14.3, 窶弑sing ccache in Buildroot窶);
- -
-Learn about rebuilding only the few packages you actually care
- about (see Sectionﾂ8.3, 窶弑nderstanding how to rebuild packages窶), but beware that sometimes full
- rebuilds are anyway necessary (see Sectionﾂ8.2, 窶弑nderstanding when a full rebuild is necessary窶);
-
-
-Make sure you are not using a virtual machine for the Linux system
- used to run Buildroot. Most of the virtual machine technologies are
- known to cause a significant performance impact on I/O, which is
- really important for building source code;
-
-
-Make sure that you窶决e using only local files: do not attempt to do
- a build over NFS, which significantly slows down the build. Having
- the Buildroot download folder available locally also helps a bit.
-
-
-Buy new hardware. SSDs and lots of RAM are key to speeding up the
- builds.
-
-
-Experiment with top-level parallel build, see
- Sectionﾂ8.12, 窶弋op-level parallel build窶.
-
Chapterﾂ13.ﾂLegal notice and licensing
13.1.ﾂComplying with open source licenses
All of the end products of Buildroot (toolchain, root filesystem, kernel,
-bootloaders) contain open source software, released under various licenses.
Using open source software gives you the freedom to build rich embedded
-systems, choosing from a wide range of packages, but also imposes some
-obligations that you must know and honour.
-Some licenses require you to publish the license text in the documentation of
-your product. Others require you to redistribute the source code of the
-software to those that receive your product.
The exact requirements of each license are documented in each package, and
-it is your responsibility (or that of your legal office) to comply with those
-requirements.
-To make this easier for you, Buildroot can collect for you some material you
-will probably need. To produce this material, after you have configured
-Buildroot with make menuconfig, make xconfig or make gconfig, run:
make legal-info
Buildroot will collect legally-relevant material in your output directory,
-under the legal-info/ subdirectory.
-There you will find:
-
-A
README file, that summarizes the produced material and contains warnings
- about material that Buildroot could not produce.
- -
-
buildroot.config: this is the Buildroot configuration file that is usually
- produced with make menuconfig, and which is necessary to reproduce the
- build.
- -
-The source code for all packages; this is saved in the
sources/ and
- host-sources/ subdirectories for target and host packages respectively.
- The source code for packages that set <PKG>_REDISTRIBUTE = NO will not be
- saved.
- Patches that were applied are also saved, along with a file named series
- that lists the patches in the order they were applied. Patches are under the
- same license as the files that they modify.
- Note: Buildroot applies additional patches to Libtool scripts of
- autotools-based packages. These patches can be found under
- support/libtool in the Buildroot source and, due to technical
- limitations, are not saved with the package sources. You may need to
- collect them manually.
- -
-A manifest file (one for host and one for target packages) listing the
- configured packages, their version, license and related information.
- Some of this information might not be defined in Buildroot; such items are
- marked as "unknown".
-
-
-The license texts of all packages, in the
licenses/ and host-licenses/
- subdirectories for target and host packages respectively.
- If the license file(s) are not defined in Buildroot, the file is not produced
- and a warning in the README indicates this.
-
Please note that the aim of the legal-info feature of Buildroot is to
-produce all the material that is somehow relevant for legal compliance with the
-package licenses. Buildroot does not try to produce the exact material that
-you must somehow make public. Certainly, more material is produced than is
-needed for a strict legal compliance. For example, it produces the source code
-for packages released under BSD-like licenses, that you are not required to
-redistribute in source form.
Moreover, due to technical limitations, Buildroot does not produce some
-material that you will or may need, such as the toolchain source code for
-some of the external toolchains and the Buildroot source code itself.
-When you run make legal-info, Buildroot produces warnings in the README
-file to inform you of relevant material that could not be saved.
Finally, keep in mind that the output of make legal-info is based on
-declarative statements in each of the packages recipes. The Buildroot
-developers try to do their best to keep those declarative statements as
-accurate as possible, to the best of their knowledge. However, it is very
-well possible that those declarative statements are not all fully accurate
-nor exhaustive. You (or your legal department) have to check the output
-of make legal-info before using it as your own compliance delivery. See
-the NO WARRANTY clauses (clauses 11 and 12) in the COPYING file at the
-root of the Buildroot distribution.
13.2.ﾂComplying with the Buildroot license
Buildroot itself is an open source software, released under the
-GNU General
-Public License, version 2 or (at your option) any later version, with
-the exception of the package patches detailed below.
-However, being a build system, it is not normally part of the end product:
-if you develop the root filesystem, kernel, bootloader or toolchain for a
-device, the code of Buildroot is only present on the development machine, not
-in the device storage.
Nevertheless, the general view of the Buildroot developers is that you should
-release the Buildroot source code along with the source code of other packages
-when releasing a product that contains GPL-licensed software.
-This is because the
-GNU GPL
-defines the "complete source code" for an executable work as "all the
-source code for all modules it contains, plus any associated interface
-definition files, plus the scripts used to control compilation and installation
-of the executable".
-Buildroot is part of the scripts used to control compilation and
-installation of the executable, and as such it is considered part of the
-material that must be redistributed.
Keep in mind that this is only the Buildroot developers' opinion, and you
-should consult your legal department or lawyer in case of any doubt.
13.2.1.ﾂPatches to packages
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ﾂ19, Patching a package for the technical details.
