1bb7a8ee4b
Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net> Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
314 lines
12 KiB
Plaintext
314 lines
12 KiB
Plaintext
Using Buildroot
|
|
===============
|
|
|
|
Configuration and general usage
|
|
-------------------------------
|
|
|
|
Buildroot has a nice configuration tool similar to the one you can
|
|
find in the http://www.kernel.org/[Linux kernel] or in
|
|
http://www.busybox.net/[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, so you may need to install "development" packages for
|
|
relevant libraries used by the configuration utilities. On Debian-like
|
|
systems, the +libncurses5-dev+ package is required to use the
|
|
'menuconfig' interface, +libqt4-dev+ is required to use the 'xconfig'
|
|
interface, and +libglib2.0-dev, libgtk2.0-dev and libglade2-dev+ are
|
|
needed to use the 'gconfig' 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+.
|
|
|
|
This command will generally perform the following steps:
|
|
|
|
* Download source files (as required)
|
|
* Configure, build and install the cross-compiling toolchain if an
|
|
internal toolchain is used, or import a toolchain if an external
|
|
toolchain is used
|
|
* 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). 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, unless the
|
|
+development files in target filesystem+ option is selected.
|
|
|
|
* +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.
|
|
|
|
Offline builds
|
|
--------------
|
|
|
|
If you intend to do an offline build and just want to download
|
|
all sources that you previously selected in the configurator
|
|
('menuconfig', 'xconfig' or 'gconfig'), then issue:
|
|
|
|
--------------------
|
|
$ make source
|
|
--------------------
|
|
|
|
You can now disconnect or copy the content of your +dl+
|
|
directory to the build-host.
|
|
|
|
Building out-of-tree
|
|
--------------------
|
|
|
|
Buildroot 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+.
|
|
|
|
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>
|
|
--------------------
|
|
|
|
Environment variables
|
|
---------------------
|
|
[[env-vars]]
|
|
|
|
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
|
|
* +BUSYBOX_CONFIG_FILE=<path/to/.config>+, path to
|
|
the Busybox configuration file
|
|
* +BUILDROOT_DL_DIR+ to override the directory in which
|
|
Buildroot stores/retrieves downloaded files
|
|
|
|
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
|
|
--------------------
|
|
|
|
Complying with opensource licenses
|
|
----------------------------------
|
|
[[legal-info]]
|
|
|
|
All of the end products of Buildroot (toolchain, root filesystem, kernel,
|
|
bootloaders) contain opensource software, released under various licenses.
|
|
|
|
Using opensource software gives you the freedom to build rich embedded
|
|
systems choosing from a wide range of packages, but also gives some
|
|
obligations that you must know and honour.
|
|
Some licenses require you to publish the license text in the documentation of
|
|
your product. Other require you to redistribute the source code of the
|
|
software to those that receive your product.
|
|
|
|
The exact requirements of each license is documented in each package, and it is
|
|
your (or your legal office's) responsibility to comply with these requirements.
|
|
To make this easier for you, Buildroot can collect for you some material you
|
|
will probably need. To produce this material, after you 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/+
|
|
subdirectory (except for proprietary packages, whose source code is not
|
|
saved);
|
|
patches applied to some packages by Buildroot are distributed with the
|
|
Buildroot sources and are not duplicated in the +sources/+ subdirectory.
|
|
* A manifest file listing the configured packages, their version, license and
|
|
related information.
|
|
Some of these information might be not defined in Buildroot; in this case
|
|
they are clearly marked as "unknown" or similar.
|
|
* A +licenses/+ subdirectory, which contains the license text of packages.
|
|
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. It does surely produce some more material than is
|
|
needed for a strict legal compliance. For example, it produces the source code
|
|
for packages released under BSD-like licenses, that you might not want 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 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.
|
|
|
|
Here is a list of the licenses that are most widely used by packages in
|
|
Buildroot, with the name used in the manifest file:
|
|
|
|
* +GPLv2+:
|
|
http://www.gnu.org/licenses/old-licenses/gpl-2.0.html[
|
|
GNU General Public License, version 2];
|
|
* +GPLv2++:
|
|
http://www.gnu.org/licenses/old-licenses/gpl-2.0.html[
|
|
GNU General Public License, version 2]
|
|
or (at your option) any later version;
|
|
* +GPLv3+:
|
|
http://www.gnu.org/licenses/gpl.html[
|
|
GNU General Public License, version 3];
|
|
* +GPLv3++:
|
|
http://www.gnu.org/licenses/gpl.html[
|
|
GNU General Public License, version 3]
|
|
or (at your option) any later version;
|
|
* +GPL+:
|
|
http://www.gnu.org/licenses/gpl.html[
|
|
GNU General Public License] (any version);
|
|
* +LGPLv2.1+:
|
|
http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html[
|
|
GNU Lesser General Public License, version 2.1];
|
|
* +LGPLv2.1++:
|
|
http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html[
|
|
GNU Lesser General Public License, version 2.1]
|
|
or (at your option) any later version;
|
|
* +LGPLv3+:
|
|
http://www.gnu.org/licenses/lgpl.html[
|
|
GNU Lesser General Public License, version 3];
|
|
* +LGPLv3++:
|
|
http://www.gnu.org/licenses/lgpl.html[
|
|
GNU Lesser General Public License, version 3]
|
|
or (at your option) any later version;
|
|
* +LGPL+:
|
|
http://www.gnu.org/licenses/lgpl.html[
|
|
GNU Lesser General Public License] (any version);
|
|
* +BSD-4c+: Original BSD 4-clause license;
|
|
* +BSD-3c+: BSD 3-clause license;
|
|
* +BSD-2c+: BSD 2-clause license;
|
|
* +PROPRIETARY+: marks a non-opensource package;
|
|
Buildroot does not save any licensing info or source code for these packages.
|
|
|
|
Complying with the Buildroot license
|
|
------------------------------------
|
|
|
|
Buildroot itself is an opensource software, released under the
|
|
http://www.gnu.org/licenses/old-licenses/gpl-2.0.html[GNU General Public
|
|
License, version 2] or (at your option) any later version.
|
|
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
|
|
http://www.gnu.org/licenses/old-licenses/gpl-2.0.html[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 this is only the Buildroot developers' opinion, and you should
|
|
consult your legal department or lawyer in case of any doubt.
|