Chapter 2. Starting up

2.1. System requirements

Buildroot is designed to run on Linux systems.

Buildroot needs some software to be already installed on the host system; here are the lists of the mandatory and optional packages (package names may vary between distributions).

Take care to install both runtime and development data, especially for the libraries that may be packaged in 2 distinct packages.

2.1.1. Mandatory packages

  • Build tools:

    • which
    • sed
    • make (version 3.81 or any later)
    • binutils
    • build-essential (only for Debian based systems)
    • gcc (version 2.95 or any later)
    • g++ (version 2.95 or any later)
    • bash
    • patch
    • gzip
    • bzip2
    • perl
    • tar
    • cpio
    • python (version 2.6 or 2.7)
    • unzip
    • rsync
  • Source fetching tools:

    • wget

2.1.2. Optional packages

  • Source fetching tools:

    In the official tree, most of the package sources are retrieved using wget; a few are only available through their git, mercurial, or svn repository.

    All other source fetching methods are implemented and may be used in a development context (further details: refer to Section 6.4, “Download infrastructure”).

    • bazaar
    • cvs
    • git
    • mercurial
    • rsync
    • scp
    • subversion
  • Configuration interface dependencies (requires development libraries):

    • ncurses5 to use the menuconfig interface
    • qt4 to use the xconfig interface
    • glib2, gtk2 and glade2 to use the gconfig interface
  • Java-related packages, if the Java Classpath needs to be built for the target system:

    • The javac compiler
    • The jar tool
  • Documentation generation tools:

    • asciidoc

2.2. Getting Buildroot

Buildroot releases are made approximately every 3 months. Direct Git access and daily snapshots are also available, if you want more bleeding edge.

Releases are available at http://buildroot.net/downloads/.

The latest snapshot is always available at http://buildroot.net/downloads/snapshots/buildroot-snapshot.tar.bz2, and previous snapshots are also available at http://buildroot.net/downloads/snapshots/.

To download Buildroot using Git, you can simply follow the rules described on the "Accessing Git" page (http://buildroot.net/git.html) of the Buildroot website (http://buildroot.net). For the impatient, here’s a quick recipe:

 $ git clone git://git.buildroot.net/buildroot

2.3. Using Buildroot

Buildroot has a nice configuration tool similar to the one you can find in the Linux kernel or in Busybox. Note that you can and should build everything as a normal user. There is no need to be root to configure and use Buildroot. The first step is to run the configuration assistant:

 $ make menuconfig

to run the curses-based configurator, or

 $ make xconfig

or

 $ make gconfig

to run the Qt or GTK-based configurators.

All of these "make" commands will need to build a configuration utility (including the interface), so you may need to install "development" packages for relevant libraries used by the configuration utilities. Check Section 2.1, “System requirements” to know what Buildroot needs, and specifically the optional requirements Section 2.1.2, “Optional packages” to get the dependencies of your favorite interface.

For each menu entry in the configuration tool, you can find associated help that describes the purpose of the entry.

Once everything is configured, the configuration tool generates a .config file that contains the description of your configuration. It will be used by the Makefiles to do what’s needed.

Let’s go:

 $ make

You should never use make -jN with Buildroot: it does not support top-level parallel make. Instead, use the BR2_JLEVEL option to tell Buildroot to run each package compilation with make -jN.

The make command will generally perform the following steps:

  • download source files (as required);
  • configure, build and install the cross-compiling toolchain using the appropriate toolchain backend, or simply import an external toolchain;
  • build/install selected target packages;
  • build a kernel image, if selected;
  • build a bootloader image, if selected;
  • create a root filesystem in selected formats.

Buildroot output is stored in a single directory, output/. This directory contains several subdirectories:

  • images/ where all the images (kernel image, bootloader and root filesystem images) are stored.
  • build/ where all the components except for the cross-compilation toolchain are built (this includes tools needed to run Buildroot on the host and packages compiled for the target). The build/ directory contains one subdirectory for each of these components.
  • staging/ which contains a hierarchy similar to a root filesystem hierarchy. This directory contains the installation of the cross-compilation toolchain and all the userspace packages selected for the target. However, this directory is not intended to be the root filesystem for the target: it contains a lot of development files, unstripped binaries and libraries that make it far too big for an embedded system. These development files are used to compile libraries and applications for the target that depend on other libraries.
  • target/ which contains almost the complete root filesystem for the target: everything needed is present except the device files in /dev/ (Buildroot can’t create them because Buildroot doesn’t run as root and doesn’t want to run as root). Also, it doesn’t have the correct permissions (e.g. setuid for the busybox binary). Therefore, this directory should not be used on your target. Instead, you should use one of the images built in the images/ directory. If you need an extracted image of the root filesystem for booting over NFS, then use the tarball image generated in images/ and extract it as root. Compared to staging/, target/ contains only the files and libraries needed to run the selected target applications: the development files (headers, etc.) are not present, the binaries are stripped.
  • host/ contains the installation of tools compiled for the host that are needed for the proper execution of Buildroot, including the cross-compilation toolchain.
  • toolchain/ contains the build directories for the various components of the cross-compilation toolchain.

These commands, make menuconfig|gconfig|xconfig and make, are the basic ones that allow to easily and quickly generate images fitting your needs, with all the supports and applications you enabled.

More details about the "make" command usage are given in Section 3.2, “make tips”.