Live CD

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

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

You can test your live CD image using QEMU: 

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

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

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

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

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

Chroot

If you want to chroot in a generated image, then there are few thing you should be aware of:

Part III. Developer guide

How Buildroot works

As mentioned above, Buildroot is basically a set of Makefiles that download, configure, and compile software with the correct options. It also includes patches for various software packages - mainly the ones involved in the cross-compilation toolchain (gcc, binutils and uClibc).

There is basically one Makefile per software package, and they are named with the .mk extension. Makefiles are split into many different parts.

Each directory contains at least 2 files:

The main Makefile performs the following steps (once the configuration is done):

Coding style

Overall, these coding style rules are here to help you to add new files in Buildroot or refactor existing ones.

If you slightly modify some existing file, the important thing is to keep the consistency of the whole file, so you can:

Config.in file

Config.in files contain entries for almost anything configurable in Buildroot.

An entry has the following pattern: 

config BR2_PACKAGE_LIBFOO
        bool "libfoo"
        depends on BR2_PACKAGE_LIBBAZ
        select BR2_PACKAGE_LIBBAR
        help
          This is a comment that explains what libfoo is. The help text
          should be wrapped.
          http://foosoftware.org/libfoo/

The Config.in files are the input for the configuration tool used in Buildroot, which is the regular Kconfig. For further details about the Kconfig language, refer to .

The .mk file

The documentation

The documentation uses the format.

For further details about the asciidoc syntax, refer to .

Support scripts

Some scripts in the support/ and utils/ directories are written in Python and should follow the .

Adding support for a particular board

Buildroot contains basic configurations for several publicly available hardware boards, so that users of such a board can easily build a system that is known to work. You are welcome to add support for other boards to Buildroot too.

To do so, you need to create a normal Buildroot configuration that builds a basic system for the hardware: (internal) toolchain, kernel, bootloader, filesystem and a simple BusyBox-only userspace. No specific package should be selected: the configuration should be as minimal as possible, and should only build a working basic BusyBox system for the target platform. You can of course use more complicated configurations for your internal projects, but the Buildroot project will only integrate basic board configurations. This is because package selections are highly application-specific.

Once you have a known working configuration, run make savedefconfig. This will generate a minimal defconfig file at the root of the Buildroot source tree. Move this file into the configs/ directory, and rename it <boardname>_defconfig. If the configuration is a bit more complicated, it is nice to manually reformat it and separate it into sections, with a comment before each section. Typical sections are Architecture, Toolchain options (typically just linux headers version), Firmware, Bootloader, Kernel, and Filesystem.

Always use fixed versions or commit hashes for the different components, not the "latest" version. For example, set BR2_LINUX_KERNEL_CUSTOM_VERSION=y and BR2_LINUX_KERNEL_CUSTOM_VERSION_VALUE to the kernel version you tested with.

It is recommended to use as much as possible upstream versions of the Linux kernel and bootloaders, and to use as much as possible default kernel and bootloader configurations. If they are incorrect for your board, or no default exists, we encourage you to send fixes to the corresponding upstream projects.

However, in the mean time, you may want to store kernel or bootloader configuration or patches specific to your target platform. To do so, create a directory board/<manufacturer> and a subdirectory board/<manufacturer>/<boardname>. You can then store your patches and configurations in these directories, and reference them from the main Buildroot configuration. Refer to for more details.

Adding new packages to Buildroot

This section covers how new packages (userspace libraries or applications) can be integrated into Buildroot. It also shows how existing packages are integrated, which is needed for fixing issues or tuning their configuration.

When you add a new package, be sure to test it in various conditions (see ) and also check it for coding style (see ).

Package directory

First of all, create a directory under the package directory for your software, for example libfoo.

Some packages have been grouped by topic in a sub-directory: x11r7, qt5 and gstreamer. If your package fits in one of these categories, then create your package directory in these. New subdirectories are discouraged, however.

Config files

For the package to be displayed in the configuration tool, you need to create a Config file in your package directory. There are two types: Config.in and Config.in.host.

Config.in file

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

config BR2_PACKAGE_LIBFOO
        bool "libfoo"
        help
          This is a comment that explains what libfoo is. The help text
          should be wrapped.
          http://foosoftware.org/libfoo/

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

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

  1. The type of option: bool, string… with the prompt
  2. If needed, the default value(s)
  3. Any dependencies on the target in depends on form
  4. Any dependencies on the toolchain in depends on form
  5. Any dependencies on other packages in depends on form
  6. Any dependency of the select form
  7. The help keyword and help text.

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

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

source "package/libfoo/Config.in"

Config.in.host file

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

Choosing depends on or select

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

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

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

config BR2_PACKAGE_RRDTOOL
        bool "rrdtool"
        depends on BR2_USE_WCHAR
        select BR2_PACKAGE_FREETYPE
        select BR2_PACKAGE_LIBART
        select BR2_PACKAGE_LIBPNG
        select BR2_PACKAGE_ZLIB
        help
          RRDtool is the OpenSource industry standard, high performance
          data logging and graphing system for time series data.
          http://oss.oetiker.ch/rrdtool/
comment "rrdtool needs a toolchain w/ wchar"
        depends on !BR2_USE_WCHAR

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

This means, in the following example: 

config BR2_PACKAGE_A
        bool "Package A"
config BR2_PACKAGE_B
        bool "Package B"
        depends on BR2_PACKAGE_A
config BR2_PACKAGE_C
        bool "Package C"
        depends on BR2_PACKAGE_B
config BR2_PACKAGE_D
        bool "Package D"
        select BR2_PACKAGE_B
config BR2_PACKAGE_E
        bool "Package E"
        select BR2_PACKAGE_D
config BR2_PACKAGE_D
        bool "Package D"
        select BR2_PACKAGE_B
        depends on BR2_PACKAGE_A
config BR2_PACKAGE_E
        bool "Package E"
        select BR2_PACKAGE_D
        depends on BR2_PACKAGE_A

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

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

Further formatting details: see .