0a62bb41ba
Closes #795. Signed-off-by: Grant Edwards <grant.b.edwards@gmail.com> Signed-off-by: Peter Korsgaard <jacmet@sunsite.dk>
1112 lines
50 KiB
HTML
1112 lines
50 KiB
HTML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>Buildroot - Usage and documentation</title>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
|
|
<link rel="stylesheet" type="text/css" href="stylesheet.css" />
|
|
</head>
|
|
|
|
<body>
|
|
<div class="main">
|
|
<div class="titre">
|
|
<h1>Buildroot</h1>
|
|
</div>
|
|
|
|
<p><a href="http://buildroot.net/">Buildroot</a>
|
|
usage and documentation by Thomas Petazzoni. Contributions from
|
|
Karsten Kruse, Ned Ludd, Martin Herren and others. </p>
|
|
|
|
<ul>
|
|
|
|
<li><a href="#about">About Buildroot</a></li>
|
|
<li><a href="#download">Obtaining Buildroot</a></li>
|
|
<li><a href="#using">Using Buildroot</a></li>
|
|
<li><a href="#custom_targetfs">Customizing the generated target filesystem</a></li>
|
|
<li><a href="#custom_busybox">Customizing the Busybox
|
|
configuration</a></li>
|
|
<li><a href="#custom_uclibc">Customizing the uClibc
|
|
configuration</a></li>
|
|
<li><a href="#custom_linux26">Customizing the Linux kernel
|
|
configuration</a></li>
|
|
<li><a href="#rebuilding_packages">Understanding how to rebuild packages</a></li>
|
|
<li><a href="#buildroot_innards">How Buildroot works</a></li>
|
|
<li><a href="#using_toolchain">Using the uClibc toolchain
|
|
outside Buildroot</a></li>
|
|
<li><a href="#external_toolchain">Use an external toolchain</a></li>
|
|
<li><a href="#downloaded_packages">Location of downloaded packages</a>
|
|
</li>
|
|
<li><a href="#add_software">Extending Buildroot with more
|
|
Software</a></li>
|
|
<li><a href="#board_support">Creating your own board support</a></li>
|
|
<li><a href="#links">Resources</a></li>
|
|
</ul>
|
|
|
|
<h2><a name="about" id="about"></a>About Buildroot</h2>
|
|
|
|
<p>Buildroot is a set of Makefiles and patches that allows you to
|
|
easily generate a cross-compilation toolchain, a root filesystem
|
|
and a Linux kernel image for your target. Buildroot can be used
|
|
for one, two or all of these options, independently.</p>
|
|
|
|
<p>Buildroot is useful mainly for people working with embedded systems.
|
|
Embedded systems often use processors that are not the regular x86
|
|
processors everyone is used to having in his PC. They can be PowerPC
|
|
processors, MIPS processors, ARM processors, etc. </p>
|
|
|
|
<p>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, <code>gcc</code>), binary utils like assembler and linker
|
|
(in our case, <code>binutils</code>) and a C standard library (for
|
|
example <a href="http://www.gnu.org/software/libc/libc.html">GNU
|
|
Libc</a>, <a href="http://www.uclibc.org/">uClibc</a> or <a
|
|
href="http://www.fefe.de/dietlibc/">dietlibc</a>). 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're 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're
|
|
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). </p>
|
|
|
|
<p>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. </p>
|
|
|
|
<p>Even if your embedded system uses an x86 processor, you might be interested
|
|
in Buildroot for two reasons:</p>
|
|
|
|
<ul>
|
|
<li>The compilation toolchain on your host certainly uses the GNU Libc
|
|
which is a complete but huge C standard library. Instead of using GNU
|
|
Libc on your target system, you can use uClibc which is a tiny C standard
|
|
library. If you want to use this C library, then you need a compilation
|
|
toolchain to generate binaries linked with it. Buildroot can do that for
|
|
you. </li>
|
|
|
|
<li>Buildroot automates the building of a root filesystem with all needed
|
|
tools like busybox. That makes it much easier than doing it by hand. </li>
|
|
</ul>
|
|
|
|
<p>You might wonder why such a tool is needed when you can compile
|
|
<code>gcc</code>, <code>binutils</code>, <code>uClibc</code> and all
|
|
the other tools by hand.
|
|
Of course doing so is possible. But, dealing with all of the configure options
|
|
and problems of every <code>gcc</code> or <code>binutils</code>
|
|
version is very time-consuming and uninteresting. Buildroot automates this
|
|
process through the use of Makefiles and has a collection of patches for
|
|
each <code>gcc</code> and <code>binutils</code> version to make them work
|
|
on most architectures. </p>
|
|
|
|
<p>Moreover, Buildroot provides an infrastructure for reproducing
|
|
the build process of your kernel, cross-toolchain, and embedded root filesystem. Being able to
|
|
reproduce the build process will be useful when a component needs
|
|
to be patched or updated or when another person is supposed to
|
|
take over the project.</p>
|
|
|
|
<h2><a name="download" id="download"></a>Obtaining Buildroot</h2>
|
|
|
|
<p>Buildroot releases are made approximately every 3
|
|
months. Direct Git access and daily snapshots are also
|
|
available if you want more bleeding edge.</p>
|
|
|
|
<p>Releases are available at <a
|
|
href="http://buildroot.net/downloads/">http://buildroot.net/downloads/</a>.</p>
|
|
|
|
<p>The latest snapshot is always available at <a
|
|
href="http://buildroot.net/downloads/snapshots/buildroot-snapshot.tar.bz2">http://buildroot.net/downloads/snapshots/buildroot-snapshot.tar.bz2</a>,
|
|
and previous snapshots are also available at <a
|
|
href="http://buildroot.net/downloads/snapshots/">http://buildroot.net/downloads/snapshots/</a>. </p>
|
|
|
|
<p>To download Buildroot using Git you can simply follow
|
|
the rules described on the "Accessing Git" page (<a href=
|
|
"http://buildroot.net/git.html">http://buildroot.net/git.html</a>)
|
|
of the Buildroot website (<a href=
|
|
"http://buildroot.net">http://buildroot.net</a>).
|
|
For the impatient, here's a quick
|
|
recipe:</p>
|
|
|
|
<pre>
|
|
$ git clone git://git.buildroot.net/buildroot
|
|
</pre>
|
|
|
|
<h2><a name="using" id="using"></a>Using Buildroot</h2>
|
|
|
|
<p>Buildroot has a nice configuration tool similar to the one you can find
|
|
in the Linux kernel (<a href=
|
|
"http://www.kernel.org/">http://www.kernel.org/</a>) or in Busybox
|
|
(<a href="http://www.busybox.org/">http://www.busybox.org/</a>). 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:</p>
|
|
|
|
<pre>
|
|
$ make menuconfig
|
|
</pre>
|
|
|
|
<p>to run the curses-based configurator, or</p>
|
|
|
|
<pre>
|
|
$ make xconfig
|
|
</pre>
|
|
|
|
<p>to run the Qt3-based configurator.</p>
|
|
|
|
<p>Both of these "make" commands will need to build a configuration
|
|
utility, so you may need to install "development" packages for
|
|
relevent libraries used by the configuration utilities.
|
|
On Debian-like systems, the
|
|
<code>libncurses5-dev</code> package is required to use the
|
|
<i>menuconfig</i> interface, and the <code>libqt3-mt-dev</code> is
|
|
required to use the <i>xconfig</i> interface.</p>
|
|
|
|
<p>For each menu entry in the configuration tool, you can find associated help
|
|
that describes the purpose of the entry. </p>
|
|
|
|
<p>Once everything is configured, the configuration tool generates a
|
|
<code>.config</code> file that contains the description of your
|
|
configuration. It will be used by the Makefiles to do what's needed. </p>
|
|
|
|
|
|
<p>Let's go:</p>
|
|
|
|
<pre>
|
|
$ make
|
|
</pre>
|
|
<p>This command will generally perform the following steps:</p>
|
|
<ul>
|
|
<li>Download source files (as required)</li>
|
|
<li>Configure cross-compile toolchain</li>
|
|
<li>Build/install cross-compile toolchain</li>
|
|
<li>Build/install selected target packages</li>
|
|
<li>Build a kernel image</li>
|
|
<li>Create a root filesystem in selected formats</li>
|
|
</ul>
|
|
<p>Some of the above steps might not be performed if they are not
|
|
selected in the Buildroot configuration.
|
|
</p>
|
|
|
|
<p>Buildroot output is stored in a single directory,
|
|
<code>output/</code>. This directory contains several
|
|
subdirectories:</p>
|
|
|
|
<ul>
|
|
|
|
<li><code>images/</code> where all the images (kernel image,
|
|
bootloader and root filesystem images) are stored.</li>
|
|
|
|
<li><code>build/</code> 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 <code>build/</code> directory contains one
|
|
subdirectory for each of these components.</li>
|
|
|
|
<li><code>staging/</code> 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 <i>not</i> 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.</li>
|
|
|
|
<li><code>target/</code> which contains <i>almost</i> the root
|
|
filesystem for the target: everything needed is present except
|
|
the device files in <code>/dev/</code> (Buildroot can't create
|
|
them because Buildroot doesn't run as root and does not want to
|
|
run as root). Therefore, this directory <b>should not be used on
|
|
your target</b>. Instead, you should use one of the images
|
|
built in the <code>images/</code> directory. If you need an
|
|
extracted image of the root filesystem for booting over NFS,
|
|
then use the tarball image generated in <code>images/</code> and
|
|
extract it as root.<br/>Compared to <code>staging/</code>,
|
|
<code>target/</code> contains only the files and libraries needed
|
|
to run the selected target applications: the development files
|
|
(headers, etc.) are not present.</li>
|
|
|
|
<li><code>host/</code> contains the installation of tools
|
|
compiled for the host that are needed for the proper execution
|
|
of Buildroot except for the cross-compilation toolchain which is
|
|
installed under <code>staging/</code>.</li>
|
|
|
|
<li><code>toolchain/</code> contains the build directories for
|
|
the various components of the cross-compilation toolchain.</li>
|
|
|
|
</ul>
|
|
|
|
<h3><a name="offline_builds" id="offline_builds"></a>
|
|
Offline builds</h3>
|
|
|
|
<p>If you intend to do an offline build and just want to download
|
|
all sources that you previously selected in the configurator
|
|
(<i>menuconfig</i> or <i>xconfig</i>), then issue:</p>
|
|
<pre>
|
|
$ make source
|
|
</pre>
|
|
<p>You can now disconnect or copy the content of your <code>dl</code>
|
|
directory to the build-host. </p>
|
|
|
|
<h3><a name="building_out_of_tree" id="building_out_of_tree"></a>
|
|
Building out-of-tree</h3>
|
|
|
|
<p>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:</p>
|
|
|
|
<pre>
|
|
$ make O=/tmp/build
|
|
</pre>
|
|
|
|
<p>All the output files will be located under
|
|
<code>/tmp/build</code>.</p>
|
|
|
|
<h3><a name="environment_variables" id="environment_variables"></a>
|
|
Environment variables</h3>
|
|
|
|
<p>Buildroot also honors some environment variables when they are passed
|
|
to <code>make</code>:</p>
|
|
<ul>
|
|
<li><code>HOSTCXX</code>, the host C++ compiler to use</li>
|
|
<li><code>HOSTCC</code>, the host C compiler to use</li>
|
|
<li><code>UCLIBC_CONFIG_FILE=<path/to/.config></code>, path
|
|
to the uClibc configuration file to use to compile uClibc if an
|
|
internal toolchain is being built</li>
|
|
<li><code>BUSYBOX_CONFIG_FILE=<path/to/.config></code>, path
|
|
to the Busybox configuration file</li>
|
|
<li><code>LINUX26_KCONFIG=<path/to/.config></code>, path
|
|
to the Linux kernel configuration file</li>
|
|
<li><code>BUILDROOT_COPYTO</code>, an additional location to which
|
|
the binary images of the root filesystem, kernel, etc. built by
|
|
Buildroot are copied</li>
|
|
<li><code>BUILDROOT_DL_DIR</code> to override the directory in
|
|
which Buildroot stores/retrieves downloaded files</li>
|
|
</ul>
|
|
|
|
<p>An example that uses config files located in the toplevel directory and
|
|
in your $HOME:</p>
|
|
<pre>
|
|
$ make UCLIBC_CONFIG_FILE=uClibc.config BUSYBOX_CONFIG_FILE=$HOME/bb.config
|
|
</pre>
|
|
|
|
<p>If you want to use a compiler other than the default <code>gcc</code>
|
|
or <code>g++</code> for building helper-binaries on your host, then do</p>
|
|
<pre>
|
|
$ make HOSTCXX=g++-4.3-HEAD HOSTCC=gcc-4.3-HEAD
|
|
</pre>
|
|
|
|
<p>If you want the result of your build to be copied to another directory
|
|
like /tftpboot for downloading to a board using tftp, then you
|
|
can use BUILDROOT_COPYTO to specify your location</p>
|
|
<p>Typically, this is set in your ~/.bashrc file
|
|
|
|
<pre>
|
|
$ export BUILDROOT_COPYTO=/tftpboot
|
|
</pre>
|
|
|
|
<h2><a name="custom_targetfs" id="custom_targetfs"></a>Customizing the
|
|
generated target filesystem</h2>
|
|
|
|
<p>There are a few ways to customize the resulting target filesystem:</p>
|
|
|
|
<ul>
|
|
<li>Customize the target filesystem directly and rebuild the image. The
|
|
target filesystem is available under <code>output/target/</code>.
|
|
You can simply make your changes here and run make afterwards — this will
|
|
rebuild the target filesystem image. This method allows you to do anything
|
|
to the target filesystem, but if you decide to completely rebuild your
|
|
toolchain and tools, these changes will be lost. </li>
|
|
|
|
<li>Customize the target filesystem skeleton available under
|
|
<code>target/generic/target_skeleton/</code>. You can customize
|
|
configuration files or other stuff here. However, the full file hierarchy
|
|
is not yet present because it's created during the compilation process.
|
|
Therefore, you can't do everything on this target filesystem skeleton, but
|
|
changes to it do remain even if you completely rebuild the cross-compilation
|
|
toolchain and the tools. <br />
|
|
You can also customize the <code>target/generic/device_table.txt</code>
|
|
file which is used by the tools that generate the target filesystem image
|
|
to properly set permissions and create device nodes.<br />
|
|
These customizations are deployed into
|
|
<code>output/target/</code> just before the actual image
|
|
is made. Simply rebuilding the image by running
|
|
make should propagate any new changes to the image. </li>
|
|
|
|
<li>Add support for your own target in Buildroot so that you
|
|
have your own target skeleton (see <a href="#board_support">this
|
|
section</a> for details).</li>
|
|
|
|
<li>In the Buildroot configuration, you can specify the path to a
|
|
post-build script that gets called <i>after</i> Buildroot builds
|
|
all the selected software but <i>before</i> the the rootfs
|
|
packages are assembled. The destination root filesystem folder
|
|
is given as the first argument to this script, and this script can
|
|
then be used to copy programs, static data or any other needed
|
|
file to your target filesystem.<br/>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 a post-build cleanup script.</li>
|
|
|
|
<li>A special package, <i>customize</i>, stored in
|
|
<code>package/customize</code> can be used. You can put all the
|
|
files that you want to see in the final target root filesystem
|
|
in <code>package/customize/source</code> and then enable this
|
|
special package in the configuration system.</li>
|
|
|
|
</ul>
|
|
|
|
<h2><a name="custom_busybox" id="custom_busybox"></a>Customizing the
|
|
Busybox configuration</h2>
|
|
|
|
<p><a href="http://www.busybox.net/">Busybox</a> is very configurable, and
|
|
you may want to customize it. You can
|
|
follow these simple steps to do so. This method isn't optimal, but it's
|
|
simple and it works:</p>
|
|
|
|
<ol>
|
|
<li>Do an initial compilation of Buildroot with busybox without trying to
|
|
customize it. </li>
|
|
|
|
<li>Invoke <code>make busybox-menuconfig</code>.
|
|
The nice configuration tool appears, and you can
|
|
customize everything. </li>
|
|
|
|
<li>Run the compilation of Buildroot again. </li>
|
|
</ol>
|
|
|
|
<p>Otherwise, you can simply change the
|
|
<code>package/busybox/busybox-<version>.config</code> file if you
|
|
know the options you want to change without using the configuration tool.
|
|
</p>
|
|
<p>If you want to use an existing config file for busybox, then see
|
|
section <a href="#environment_variables">environment variables</a>. </p>
|
|
|
|
<h2><a name="custom_uclibc" id="custom_uclibc"></a>Customizing the uClibc
|
|
configuration</h2>
|
|
|
|
<p>Just like <a href="#custom_busybox">BusyBox</a>, <a
|
|
href="http://www.uclibc.org/">uClibc</a> offers a lot of
|
|
configuration options. They allow you to select various
|
|
functionalities depending on your needs and limitations. </p>
|
|
|
|
<p>The easiest way to modify the configuration of uClibc is to
|
|
follow these steps:</p>
|
|
|
|
<ol>
|
|
|
|
<li>Do an initial compilation of Buildroot without trying to
|
|
customize uClibc. </li>
|
|
|
|
<li>Invoke <code>make uclibc-menuconfig</code>.
|
|
The nice configuration assistant, similar to
|
|
the one used in the Linux kernel or Buildroot, appears. Make
|
|
your configuration changes as appropriate. </li>
|
|
|
|
<li>Copy the <code>.config</code> file to
|
|
<code>toolchain/uClibc/uClibc.config</code> or
|
|
<code>toolchain/uClibc/uClibc.config-locale</code>. The former
|
|
is used if you haven't selected locale support in Buildroot
|
|
configuration, and the latter is used if you have selected
|
|
locale support. </li>
|
|
|
|
<li>Run the compilation of Buildroot again.</li>
|
|
|
|
</ol>
|
|
|
|
<p>Otherwise, you can simply change
|
|
<code>toolchain/uClibc/uClibc.config</code> or
|
|
<code>toolchain/uClibc/uClibc.config-locale</code> without running
|
|
the configuration assistant. </p>
|
|
|
|
<p>If you want to use an existing config file for uclibc, then see
|
|
section <a href="#environment_variables">environment variables</a>. </p>
|
|
|
|
<h2><a name="custom_linux26" id="custom_linux26"></a>Customizing
|
|
the Linux kernel configuration</h2>
|
|
|
|
<p>The Linux kernel configuration can be customized just like <a
|
|
href="#custom_busybox">BusyBox</a> and <a href="#custom_uclibc">uClibc</a>
|
|
using <code>make linux26-menuconfig</code>. Make sure you have
|
|
enabled the kernel build in <code>make menuconfig</code> first.
|
|
Once done, run <code>make</code> to (re)build everything.</p>
|
|
|
|
<p>If you want to use an existing config file for Linux, then see
|
|
section <a href="#environment_variables">environment variables</a>.</p>
|
|
|
|
<h2><a name="#rebuilding_packages"
|
|
id="rebuilding_packages">Understanding how to rebuild
|
|
packages</a></h2>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>Removing a package is currently unsupported by Buildroot
|
|
without rebuilding from scratch. This is because Buildroot doesn't
|
|
keep track of which package installs what files in the
|
|
<code>output/staging</code> and <code>output/target</code>
|
|
directories. However, implementing clean package removal is on the
|
|
TODO-list of Buildroot developers.</p>
|
|
|
|
<p>The easiest way to rebuild a single package from scratch is to
|
|
remove its build directory in <code>output/build</code>. Buildroot
|
|
will then re-extract, re-configure, re-compile and re-install this
|
|
package from scratch.</p>
|
|
|
|
<p>However, if you don't want to rebuild the package completely
|
|
from scratch, a better understanding of the Buildroot internals is
|
|
needed. Internally, to keep track of which steps have been done
|
|
and which steps remain to be done, Buildroot maintains stamp
|
|
files (empty files that just tell whether this or that action
|
|
has been done). The problem is that these stamp files are not
|
|
uniformely named and handled by the different packages, so some
|
|
understanding of the particular package is needed.</p>
|
|
|
|
<p>For packages relying on the <i>autotools</i> Buildroot
|
|
infrastructure (see <a href="#add_software">this section</a> for
|
|
details), the following stamp files are relevent:</p>
|
|
|
|
<ul>
|
|
|
|
<li><code>output/build/packagename-version/.stamp_configured</code>. If
|
|
removed, Buildroot will trigger the recompilation of the package
|
|
from the configuration step (execution of
|
|
<code>./configure</code>).</li>
|
|
|
|
<li><code>output/build/packagename-version/.stamp_built</code>. If
|
|
removed, Buildroot will trigger the recompilation of the package
|
|
from the compilation step (execution of <code>make</code>).</li>
|
|
|
|
</ul>
|
|
|
|
<p>For other packages, an analysis of the specific
|
|
<i>package.mk</i> file is needed. For example, the zlib Makefile
|
|
looks like:</p>
|
|
|
|
<pre>
|
|
$(ZLIB_DIR)/.configured: $(ZLIB_DIR)/.patched
|
|
(cd $(ZLIB_DIR); rm -rf config.cache; \
|
|
[...]
|
|
)
|
|
touch $@
|
|
|
|
$(ZLIB_DIR)/libz.a: $(ZLIB_DIR)/.configured
|
|
$(MAKE) -C $(ZLIB_DIR) all libz.a
|
|
touch -c $@
|
|
</pre>
|
|
|
|
<p>If you want to trigger the reconfiguration, you need to
|
|
remove <code>output/build/zlib-version/.configured</code>. If
|
|
you want to trigger only the recompilation, you need to remove
|
|
<code>output/build/zlib-version/libz.a</code>.</p>
|
|
|
|
<h2><a name="buildroot_innards" id="buildroot_innards"></a>How Buildroot
|
|
works</h2>
|
|
|
|
<p>As mentioned above, Buildroot is basically a set of Makefiles that downloads,
|
|
configures and compiles software with the correct options. It also includes
|
|
patches for various software packages — mainly the ones involved in the
|
|
cross-compilation tool chain (<code>gcc</code>, <code>binutils</code> and
|
|
<code>uClibc</code>). </p>
|
|
|
|
<p>There is basically one Makefile per software package, and they are named with
|
|
the <code>.mk</code> extension. Makefiles are split into four
|
|
sections:</p>
|
|
|
|
<ul>
|
|
<li><b>toolchain</b> (in the <code>toolchain/</code> directory) contains
|
|
the Makefiles and associated files for all software related to the
|
|
cross-compilation toolchain: <code>binutils</code>, <code>ccache</code>,
|
|
<code>gcc</code>, <code>gdb</code>, <code>kernel-headers</code> and
|
|
<code>uClibc</code>. </li>
|
|
|
|
<li><b>package</b> (in the <code>package/</code> directory) contains the
|
|
Makefiles and associated files for all user-space tools that Buildroot
|
|
can compile and add to the target root filesystem. There is one
|
|
sub-directory per tool. </li>
|
|
|
|
<li><b>target</b> (in the <code>target</code> directory) contains the
|
|
Makefiles and associated files for software related to the generation of
|
|
the target root filesystem image. Four types of filesystems are supported:
|
|
ext2, jffs2, cramfs and squashfs. For each of them there is a
|
|
sub-directory with the required files. There is also a
|
|
<code>default/</code> directory that contains the target filesystem
|
|
skeleton. </li>
|
|
</ul>
|
|
|
|
<p>Each directory contains at least 2 files:</p>
|
|
|
|
<ul>
|
|
<li><code>something.mk</code> is the Makefile that downloads, configures,
|
|
compiles and installs the package <code>something</code>. </li>
|
|
|
|
<li><code>Config.in</code> is a part of the configuration tool
|
|
description file. It describes the options related to the
|
|
package. </li>
|
|
|
|
</ul>
|
|
|
|
<p>The main Makefile performs the following steps (once the
|
|
configuration is done):</p>
|
|
|
|
<ol>
|
|
|
|
<li>Create all the output directories: <code>staging</code>,
|
|
<code>target</code>, <code>build</code>, <code>stamps</code>,
|
|
etc. in the output directory (<code>output/</code> by default,
|
|
another value can be specified using <code>O=</code>)</li>
|
|
|
|
<li>Generate all the targets listed in the
|
|
<code>BASE_TARGETS</code> variable. When an internal toolchain
|
|
is used, this means generating the cross-compilation
|
|
toolchain. When an external toolchain is used, this means checking
|
|
the features of the external toolchain and importing it into the
|
|
Buildroot environment.</li>
|
|
|
|
<li>Generate all the targets listed in the <code>TARGETS</code>
|
|
variable. This variable is filled by all the individual
|
|
components' Makefiles. Generating these targets will
|
|
trigger the compilation of the userspace packages (libraries,
|
|
programs), the kernel, the bootloader and the generation of the
|
|
root filesystem images, depending on the configuration.</li>
|
|
|
|
</ol>
|
|
|
|
<h2><a name="board_support" id="board_support"></a>
|
|
Creating your own board support</h2>
|
|
|
|
<p>Creating your own board support in Buildroot allows you to have
|
|
a convenient place to store your project's target filesystem skeleton
|
|
and configuration files for Buildroot, Busybox, uClibc, and the kernel.
|
|
|
|
<p>Follow these steps to integrate your board in Buildroot:</p>
|
|
|
|
<ol>
|
|
|
|
<li>Create a new directory in <code>target/device/</code> named
|
|
after your company or organization</li>
|
|
|
|
<li>Add a line <code>source
|
|
"target/device/yourcompany/Config.in"</code> in
|
|
<code>target/device/Config.in</code> so that your board appears
|
|
in the configuration system</li>
|
|
|
|
<li>In <code>target/device/yourcompany/</code>, create a
|
|
directory for your project. This way, you'll be able to store
|
|
several of your company's projects inside Buildroot.</li>
|
|
|
|
<li>Create a <code>target/device/yourcompany/Config.in</code>
|
|
file that looks like the following:
|
|
|
|
<pre>
|
|
menuconfig BR2_TARGET_COMPANY
|
|
bool "Company projects"
|
|
|
|
if BR2_TARGET_COMPANY
|
|
|
|
config BR2_TARGET_COMPANY_PROJECT_FOOBAR
|
|
bool "Support for Company project Foobar"
|
|
help
|
|
This option enables support for Company project Foobar
|
|
|
|
endif
|
|
</pre>
|
|
|
|
Of course, you should customize the different values to match your
|
|
company/organization and your project. This file will create a
|
|
menu entry that contains the different projects of your
|
|
company/organization.</li>
|
|
|
|
<li>Create a <code>target/device/yourcompany/Makefile.in</code>
|
|
file that looks like the following:
|
|
|
|
<pre>
|
|
ifeq ($(BR2_TARGET_COMPANY_PROJECT_FOOBAR),y)
|
|
include target/device/yourcompany/project-foobar/Makefile.in
|
|
endif
|
|
</pre>
|
|
</li>
|
|
|
|
<li>Create the
|
|
<code>target/device/yourcompany/project-foobar/Makefile.in</code>
|
|
file. It is recommended that you define a
|
|
<code>BOARD_PATH</code> variable set to
|
|
<code>target/device/yourcompany/project-foobar</code> as it
|
|
will simplify further definitions. Then, the file might define
|
|
one or several of the following variables:
|
|
|
|
<ul>
|
|
|
|
<li><code>TARGET_SKELETON</code> to a directory that contains
|
|
the target skeleton for your project. If this variable is
|
|
defined, this target skeleton will be used instead of the
|
|
default one. If defined, the convention is to define it to
|
|
<code>$(BOARD_PATH)/target_skeleton</code> so that the target
|
|
skeleton is stored in the board specific directory.</li>
|
|
|
|
<li><code>TARGET_DEVICE_TABLE</code> to a file that contains
|
|
the target device table — the list of device files (in
|
|
<code>/dev/</code>) to be created by the root filesystem build
|
|
procedure. If this variable is defined, the given device table
|
|
will be used instead of the default one. If defined, the
|
|
convention is to define it to
|
|
<code>$(BOARD_PATH)/target_device_table.txt</code>. See
|
|
<code>target/generic/device_table.txt</code> for an example
|
|
file.</li>
|
|
|
|
</ul>
|
|
|
|
</li>
|
|
|
|
<li>In the
|
|
<code>target/device/yourcompany/project-foobar/</code>
|
|
directory you can store configuration files for the kernel,
|
|
Busybox or uClibc.
|
|
|
|
You can furthermore create one or more preconfigured configuration
|
|
files, referencing those files. These config files are named
|
|
<code>something_defconfig</code> and are stored in the toplevel
|
|
<code>configs/</code> directory. Your users will then be able
|
|
to run <code>make something_defconfig</code> and get the right
|
|
configuration for your project</li>
|
|
|
|
</ol>
|
|
|
|
<h2><a name="using_toolchain" id="using_toolchain"></a>Using the
|
|
generated toolchain outside Buildroot</h2>
|
|
|
|
<p>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. </p>
|
|
|
|
<p>The toolchain generated by Buildroot is located by default in
|
|
<code>output/staging/</code>. The simplest way to use it
|
|
is to add <code>output/staging/usr/bin/</code> to your PATH
|
|
environnement variable and then to use
|
|
<code>ARCH-linux-gcc</code>, <code>ARCH-linux-objdump</code>,
|
|
<code>ARCH-linux-ld</code>, etc. </p>
|
|
|
|
<p><b>Important</b>: do not try to move a gcc-3.x toolchain to another
|
|
directory — it won't work because there are some hardcoded paths in the
|
|
gcc-3.x configuration. If you are using a current gcc-4.x, it
|
|
is possible to relocate the toolchain — but then
|
|
<code>--sysroot</code> must be passed every time the compiler is
|
|
called to tell where the libraries and header files are.</p>
|
|
|
|
<p>It is also possible to generate the Buildroot toolchain in
|
|
a directory other than <code>output/staging</code> by using the
|
|
<code>Build options -> Toolchain and header file
|
|
location</code> options. This could be useful if the toolchain
|
|
must be shared with other users.</p>
|
|
|
|
<h2><a name="downloaded_packages"
|
|
id="downloaded_packages"></a>Location of downloaded packages</h2>
|
|
|
|
<p>It might be useful to know that the various tarballs that are
|
|
downloaded by the Makefiles are all stored in the
|
|
<code>DL_DIR</code> which by default is the <code>dl</code>
|
|
directory. It's useful, for example, if you want to keep a complete
|
|
version of Buildroot which is know to be working with the
|
|
associated tarballs. This will allow you to regenerate the
|
|
toolchain and the target filesystem with exactly the same
|
|
versions. </p>
|
|
|
|
<p>If you maintain several Buildroot trees, it might be better to have
|
|
a shared download location. This can be accessed by creating a symbolic link
|
|
from the <code>dl</code> directory to the shared download location: </p>
|
|
|
|
<pre>
|
|
ln -s <shared download location> dl
|
|
</pre>
|
|
|
|
<p>Another way of accessing a shared download location is to
|
|
create the <code>BUILDROOT_DL_DIR</code> environment variable.
|
|
If this is set, then the value of DL_DIR in the project is
|
|
overridden. The following line should be added to
|
|
<code>"~/.bashrc"</code>. <p>
|
|
|
|
<pre>
|
|
export BUILDROOT_DL_DIR <shared download location>
|
|
</pre>
|
|
|
|
<h2><a name="external_toolchain" id="external_toolchain"></a>Using
|
|
an external toolchain</h2>
|
|
|
|
<p>It might be useful not to use the toolchain generated by
|
|
Buildroot, for example if you already have a toolchain that is known
|
|
to work for your specific CPU, or if the toolchain generation feature
|
|
of Buildroot is not sufficiently flexible for you (for example if you
|
|
need to generate a system with <i>glibc</i> instead of
|
|
<i>uClibc</i>). Buildroot supports using an <i>external
|
|
toolchain</i>.</p>
|
|
|
|
<p>To enable the use of an external toolchain, go in the
|
|
<code>Toolchain</code> menu, and :</p>
|
|
|
|
<ul>
|
|
<li>Select the <code>External binary toolchain</code> toolchain
|
|
type</li>
|
|
<li>Adjust the <code>External toolchain path</code>
|
|
appropriately. It should be set to a path where a bin/ directory
|
|
contains your cross-compiling tools</li>
|
|
<li>Adjust the <code>External toolchain prefix</code> so that the
|
|
prefix, suffixed with <code>-gcc</code> or <code>-ld</code> will
|
|
correspond to your cross-compiling tools</li>
|
|
</ul>
|
|
|
|
<p>If you are using an external toolchain based on <i>uClibc</i>, the
|
|
<code>Core C library from the external toolchain</code> and
|
|
<code>Libraries to copy from the external toolchain</code> options
|
|
should already have correct values. However, if your external
|
|
toolchain is based on <i>glibc</i>, you'll have to change these values
|
|
according to your cross-compiling toolchain.</p>
|
|
|
|
<p>To generate external toolchains, we recommend using <a
|
|
href="http://ymorin.is-a-geek.org/dokuwiki/projects/crosstool">Crosstool-NG</a>.
|
|
It allows generating toolchains based on <i>uClibc</i>, <i>glibc</i>
|
|
and <i>eglibc</i> for a wide range of architectures and has good
|
|
community support.</p>
|
|
|
|
<h2><a name="add_software" id="add_software"></a>Extending Buildroot with
|
|
more software</h2>
|
|
|
|
<p>This section will only consider the case in which you want to
|
|
add user-space software. </p>
|
|
|
|
<h3>Package directory</h3>
|
|
|
|
<p>First of all, create a directory under the <code>package</code>
|
|
directory for your software, for example <code>foo</code>. </p>
|
|
|
|
<h3><code>Config.in</code> file</h3>
|
|
|
|
<p>Then, create a file named <code>Config.in</code>. This file
|
|
will contain the option descriptions related to our
|
|
<code>foo</code> software that will be used and displayed in the
|
|
configuration tool. It should basically contain:</p>
|
|
|
|
<pre>
|
|
config BR2_PACKAGE_FOO
|
|
bool "foo"
|
|
help
|
|
This is a comment that explains what foo is.
|
|
|
|
http://foosoftware.org/foo/
|
|
</pre>
|
|
|
|
<p>Of course, you can add other options to configure particular
|
|
things in your software. </p>
|
|
<p>Finally you have to add your new <code>foo/Config.in</code> to
|
|
<code>package/Config.in</code>. The files included there are
|
|
<em>sorted alphabetically</em> per category and are <em>NOT</em>
|
|
supposed to contain anything but the <em>bare</em> name of the package.</p>
|
|
<pre>
|
|
source "package/procps/Config.in"
|
|
</pre>
|
|
<p><strong>Note:</strong><br>
|
|
Generally all packages should live <em>directly</em> in the
|
|
<code>package</code> directory to make it easier to find them.
|
|
</p>
|
|
<h3>The real Makefile</h3>
|
|
|
|
<p>Finally, here's the hardest part. Create a file named
|
|
<code>foo.mk</code>. It will contain the Makefile rules that
|
|
are in charge of downloading, configuring, compiling and installing
|
|
the software.</p>
|
|
|
|
<p>Two types of Makefiles can be written :</p>
|
|
|
|
<ul>
|
|
<li>Makefiles for autotools-based (autoconf, automake, etc.)
|
|
software are very easy to write thanks to the infrastructure
|
|
available in <code>package/Makefile.autotools.in</code>.</li>
|
|
<li>Makefiles for other types of packages are a little bit more
|
|
complex to write.</li>
|
|
</ul>
|
|
|
|
<p>First, let's see how to write a Makefile for an
|
|
autotools-based package, with an example :</p>
|
|
|
|
<pre>
|
|
<a name="ex1line1" id="ex1line1">1</a> #############################################################
|
|
<a name="ex1line2" id="ex1line2">2</a> #
|
|
<a name="ex1line3" id="ex1line3">3</a> # foo
|
|
<a name="ex1line4" id="ex1line4">4</a> #
|
|
<a name="ex1line5" id="ex1line5">5</a> #############################################################
|
|
<a name="ex1line6" id="ex1line6">6</a> FOO_VERSION:=1.0
|
|
<a name="ex1line7" id="ex1line7">7</a> FOO_SOURCE:=foo-$(FOO_VERSION).tar.gz
|
|
<a name="ex1line8" id="ex1line8">8</a> FOO_SITE:=http://www.foosoftware.org/downloads
|
|
<a name="ex1line9" id="ex1line9">9</a> FOO_INSTALL_STAGING = YES
|
|
<a name="ex1line10" id="ex1line10">10</a> FOO_INSTALL_TARGET = YES
|
|
<a name="ex1line11" id="ex1line11">11</a> FOO_CONF_OPT = --enable-shared
|
|
<a name="ex1line12" id="ex1line12">12</a> FOO_DEPENDENCIES = libglib2 host-pkgconfig
|
|
<a name="ex1line13" id="ex1line13">13</a> $(eval $(call AUTOTARGETS,package,foo))
|
|
</pre>
|
|
|
|
<p>On <a href="#ex1line6">line 6</a>, we declare the version of
|
|
the package. On lines <a href="#ex1line7">7</a> and <a
|
|
href="#ex1line8">8</a>, we declare the name of the tarball and the
|
|
location of the tarball on the web. Buildroot will automatically
|
|
download the tarball from this location.</p>
|
|
|
|
<p>On <a href="#ex1line9">line 9</a>, we tell Buildroot to install
|
|
the application to the staging directory. The staging directory,
|
|
located in <code>output/staging/</code> is the directory
|
|
where all the packages are installed, including their
|
|
documentation, etc. By default, packages are installed in this
|
|
location using the <code>make install</code> command.</p>
|
|
|
|
<p>On <a href="#ex1line10">line 10</a>, we tell Buildroot to also
|
|
install the application to the target directory. This directory
|
|
contains what will become the root filesystem running on the
|
|
target. Usually, we try to install stripped binaries and
|
|
to not install the documentation. By default, packages are
|
|
installed in this location using the <code>make
|
|
install-strip</code> command.</p>
|
|
|
|
<p>On <a href="#ex1line11">line 11</a>, we tell Buildroot to pass
|
|
a custom configure option to the
|
|
<code>./configure</code> script when configuring the
|
|
the package.</p>
|
|
|
|
<p>On <a href="#ex1line12">line 12</a>, we declare our
|
|
dependencies so that they are built before the build process of
|
|
our package starts.</p>
|
|
|
|
<p>Finally, on line <a href="#ex1line13">line 13</a>, we invoke
|
|
the <code>package/Makefile.autotools.in</code> magic to get things
|
|
working.</p>
|
|
|
|
<p>For more details about the available variables and options, see
|
|
the comment at the top of
|
|
<code>package/Makefile.autotools.in</code> and the examples in all
|
|
the available packages.</p>
|
|
|
|
<p>The second solution, suitable for every type of package, looks
|
|
like this :</p>
|
|
|
|
|
|
<pre>
|
|
<a name="ex2line1" id="ex2line1">1</a> #############################################################
|
|
<a name="ex2line2" id="ex2line2">2</a> #
|
|
<a name="ex2line3" id="ex2line3">3</a> # foo
|
|
<a name="ex2line4" id="ex2line4">4</a> #
|
|
<a name="ex2line5" id="ex2line5">5</a> #############################################################
|
|
<a name="ex2line6" id="ex2line6">6</a> FOO_VERSION:=1.0
|
|
<a name="ex2line7" id="ex2line7">7</a> FOO_SOURCE:=foo-$(FOO_VERSION).tar.gz
|
|
<a name="ex2line8" id="ex2line8">8</a> FOO_SITE:=http://www.foosoftware.org/downloads
|
|
<a name="ex2line9" id="ex2line9">9</a> FOO_DIR:=$(BUILD_DIR)/foo-$(FOO_VERSION)
|
|
<a name="ex2line10" id="ex2line10">10</a> FOO_BINARY:=foo
|
|
<a name="ex2line11" id="ex2line11">11</a> FOO_TARGET_BINARY:=usr/bin/foo
|
|
<a name="ex2line12" id="ex2line12">12</a>
|
|
<a name="ex2line13" id="ex2line13">13</a> $(DL_DIR)/$(FOO_SOURCE):
|
|
<a name="ex2line14" id="ex2line14">14</a> $(call DOWNLOAD,$(FOO_SITE),$(FOO_SOURCE))
|
|
<a name="ex2line15" id="ex2line15">15</a>
|
|
<a name="ex2line16" id="ex2line16">16</a> $(FOO_DIR)/.source: $(DL_DIR)/$(FOO_SOURCE)
|
|
<a name="ex2line17" id="ex2line17">17</a> $(ZCAT) $(DL_DIR)/$(FOO_SOURCE) | tar -C $(BUILD_DIR) $(TAR_OPTIONS) -
|
|
<a name="ex2line18" id="ex2line18">18</a> touch $@
|
|
<a name="ex2line19" id="ex2line19">19</a>
|
|
<a name="ex2line20" id="ex2line20">20</a> $(FOO_DIR)/.configured: $(FOO_DIR)/.source
|
|
<a name="ex2line21" id="ex2line21">21</a> (cd $(FOO_DIR); rm -rf config.cache; \
|
|
<a name="ex2line22" id="ex2line22">22</a> $(TARGET_CONFIGURE_OPTS) \
|
|
<a name="ex2line23" id="ex2line23">23</a> $(TARGET_CONFIGURE_ARGS) \
|
|
<a name="ex2line24" id="ex2line24">24</a> ./configure \
|
|
<a name="ex2line25" id="ex2line25">25</a> --target=$(GNU_TARGET_NAME) \
|
|
<a name="ex2line26" id="ex2line26">26</a> --host=$(GNU_TARGET_NAME) \
|
|
<a name="ex2line27" id="ex2line27">27</a> --build=$(GNU_HOST_NAME) \
|
|
<a name="ex2line28" id="ex2line28">28</a> --prefix=/usr \
|
|
<a name="ex2line29" id="ex2line29">29</a> --sysconfdir=/etc \
|
|
<a name="ex2line30" id="ex2line30">30</a> )
|
|
<a name="ex2line31" id="ex2line31">31</a> touch $@
|
|
<a name="ex2line32" id="ex2line32">32</a>
|
|
<a name="ex2line33" id="ex2line33">33</a> $(FOO_DIR)/$(FOO_BINARY): $(FOO_DIR)/.configured
|
|
<a name="ex2line34" id="ex2line34">34</a> $(MAKE) CC=$(TARGET_CC) -C $(FOO_DIR)
|
|
<a name="ex2line35" id="ex2line35">35</a>
|
|
<a name="ex2line36" id="ex2line36">36</a> $(TARGET_DIR)/$(FOO_TARGET_BINARY): $(FOO_DIR)/$(FOO_BINARY)
|
|
<a name="ex2line37" id="ex2line37">37</a> $(MAKE) DESTDIR=$(TARGET_DIR) -C $(FOO_DIR) install-strip
|
|
<a name="ex2line38" id="ex2line38">38</a> rm -Rf $(TARGET_DIR)/usr/man
|
|
<a name="ex2line39" id="ex2line39">39</a>
|
|
<a name="ex2line40" id="ex2line40">40</a> foo: uclibc ncurses $(TARGET_DIR)/$(FOO_TARGET_BINARY)
|
|
<a name="ex2line41" id="ex2line41">41</a>
|
|
<a name="ex2line42" id="ex2line42">42</a> foo-source: $(DL_DIR)/$(FOO_SOURCE)
|
|
<a name="ex2line43" id="ex2line43">43</a>
|
|
<a name="ex2line44" id="ex2line44">44</a> foo-clean:
|
|
<a name="ex2line45" id="ex2line45">45</a> $(MAKE) prefix=$(TARGET_DIR)/usr -C $(FOO_DIR) uninstall
|
|
<a name="ex2line46" id="ex2line46">46</a> -$(MAKE) -C $(FOO_DIR) clean
|
|
<a name="ex2line47" id="ex2line47">47</a>
|
|
<a name="ex2line48" id="ex2line48">48</a> foo-dirclean:
|
|
<a name="ex2line49" id="ex2line49">49</a> rm -rf $(FOO_DIR)
|
|
<a name="ex2line50" id="ex2line50">50</a>
|
|
<a name="ex2line51" id="ex2line51">51</a> #############################################################
|
|
<a name="ex2line52" id="ex2line52">52</a> #
|
|
<a name="ex2line53" id="ex2line53">53</a> # Toplevel Makefile options
|
|
<a name="ex2line54" id="ex2line54">54</a> #
|
|
<a name="ex2line55" id="ex2line55">55</a> #############################################################
|
|
<a name="ex2line56" id="ex2line56">56</a> ifeq ($(BR2_PACKAGE_FOO),y)
|
|
<a name="ex2line57" id="ex2line57">57</a> TARGETS+=foo
|
|
<a name="ex2line58" id="ex2line58">58</a> endif
|
|
|
|
</pre>
|
|
|
|
<p>First of all, this Makefile example works for a package which comprises a single
|
|
binary executable. For other software, such as libraries or more
|
|
complex stuff with multiple binaries, it must be adapted. For examples look at
|
|
the other <code>*.mk</code> files in the <code>package</code>
|
|
directory. </p>
|
|
|
|
<p>At lines <a href="#ex2line6">6-11</a>, a couple of useful variables are
|
|
defined:</p>
|
|
|
|
<ul>
|
|
|
|
<li><code>FOO_VERSION</code>: The version of <i>foo</i> that
|
|
should be downloaded. </li>
|
|
|
|
<li><code>FOO_SOURCE</code>: The name of the tarball of
|
|
<i>foo</i> on the download website or FTP site. As you can see
|
|
<code>FOO_VERSION</code> is used. </li>
|
|
|
|
<li><code>FOO_SITE</code>: The HTTP or FTP site from which
|
|
<i>foo</i> archive is downloaded. It must include the complete
|
|
path to the directory where <code>FOO_SOURCE</code> can be
|
|
found. </li>
|
|
|
|
<li><code>FOO_DIR</code>: The directory into which the software
|
|
will be configured and compiled. Basically, it's a subdirectory
|
|
of <code>BUILD_DIR</code> which is created upon decompression of
|
|
the tarball. </li>
|
|
|
|
<li><code>FOO_BINARY</code>: Software binary name. As said
|
|
previously, this is an example for a package with a single binary.</li>
|
|
|
|
<li><code>FOO_TARGET_BINARY</code>: The full path of the binary
|
|
inside the target filesystem. </li>
|
|
|
|
</ul>
|
|
|
|
<p>Lines <a href="#ex2line13">13-14</a> define a target that downloads the
|
|
tarball from the remote site to the download directory
|
|
(<code>DL_DIR</code>). </p>
|
|
|
|
<p>Lines <a href="#ex2line16">16-18</a> define a target and associated rules
|
|
that uncompress the downloaded tarball. As you can see, this target
|
|
depends on the tarball file so that the previous target (lines
|
|
<a href="#ex2line13">13-14</a>) is called before executing the rules of the
|
|
current target. Uncompressing is followed by <i>touching</i> a hidden file
|
|
to mark the software as having been uncompressed. This trick is
|
|
used everywhere in a Buildroot Makefile to split steps
|
|
(download, uncompress, configure, compile, install) while still
|
|
having correct dependencies. </p>
|
|
|
|
<p>Lines <a href="#ex2line20">20-31</a> define a target and associated rules
|
|
that configure the software. It depends on the previous target (the
|
|
hidden <code>.source</code> file) so that we are sure the software has
|
|
been uncompressed. In order to configure the package, it basically runs the
|
|
well-known <code>./configure</code> script. As we may be doing
|
|
cross-compilation, <code>target</code>, <code>host</code> and
|
|
<code>build</code> arguments are given. The prefix is also set to
|
|
<code>/usr</code>, not because the software will be installed in
|
|
<code>/usr</code> on your host system, but because the software will
|
|
bin installed in <code>/usr</code> on the target
|
|
filesystem. Finally it creates a <code>.configured</code> file to
|
|
mark the software as configured. </p>
|
|
|
|
<p>Lines <a href="#ex2line33">33-34</a> define a target and a rule that
|
|
compile the software. This target will create the binary file in the
|
|
compilation directory and depends on the software being already
|
|
configured (hence the reference to the <code>.configured</code>
|
|
file). It basically runs <code>make</code> inside the source
|
|
directory. </p>
|
|
|
|
<p>Lines <a href="#ex2line36">36-38</a> define a target and associated rules
|
|
that install the software inside the target filesystem. They depend on the
|
|
binary file in the source directory to make sure the software has
|
|
been compiled. They use the <code>install-strip</code> target of the
|
|
software <code>Makefile</code> by passing a <code>DESTDIR</code>
|
|
argument so that the <code>Makefile</code> doesn't try to install
|
|
the software in the host <code>/usr</code> but rather in the target
|
|
<code>/usr</code>. After the installation, the
|
|
<code>/usr/man</code> directory inside the target filesystem is
|
|
removed to save space. </p>
|
|
|
|
<p>Line <a href="#ex2line40">40</a> defines the main target of the software —
|
|
the one that will be eventually be used by the top level
|
|
<code>Makefile</code> to download, compile, and then install
|
|
this package. This target should first of all depend on all
|
|
needed dependencies of the software (in our example,
|
|
<i>uclibc</i> and <i>ncurses</i>) and also depend on the
|
|
final binary. This last dependency will call all previous
|
|
dependencies in the correct order. </p>
|
|
|
|
<p>Line <a href="#ex2line42">42</a> defines a simple target that only
|
|
downloads the code source. This is not used during normal operation of
|
|
Buildroot, but is needed if you intend to download all required sources at
|
|
once for later offline build. Note that if you add a new package providing
|
|
a <code>foo-source</code> target is <i>mandatory</i> to support
|
|
users that wish to do offline-builds. Furthermore it eases checking
|
|
if all package-sources are downloadable. </p>
|
|
|
|
<p>Lines <a href="#ex2line44">44-46</a> define a simple target to clean the
|
|
software build by calling the Makefiles with the appropriate option.
|
|
The <code>-clean</code> target should run <code>make clean</code>
|
|
on $(BUILD_DIR)/package-version and MUST uninstall all files of the
|
|
package from $(STAGING_DIR) and from $(TARGET_DIR). </p>
|
|
|
|
<p>Lines <a href="#ex2line48">48-49</a> define a simple target to completely
|
|
remove the directory in which the software was uncompressed, configured and
|
|
compiled. The <code>-dirclean</code> target MUST completely rm $(BUILD_DIR)/
|
|
package-version. </p>
|
|
|
|
<p>Lines <a href="#ex2line51">51-58</a> add the target <code>foo</code> to
|
|
the list of targets to be compiled by Buildroot by first checking if
|
|
the configuration option for this package has been enabled
|
|
using the configuration tool. If so, it then "subscribes"
|
|
this package to be compiled by adding the package to the TARGETS
|
|
global variable. The name added to the TARGETS global
|
|
variable is the name of this package's target, as defined on
|
|
line <a href="#ex2line40">40</a>, which is used by Buildroot to download,
|
|
compile, and then install this package. </p>
|
|
|
|
|
|
<h3>Conclusion</h3>
|
|
|
|
<p>As you can see, adding a software package to Buildroot is simply a
|
|
matter of writing a Makefile using an existing
|
|
example and modifying it according to the compilation process required by
|
|
the package. </p>
|
|
|
|
<p>If you package software that might be useful for other people,
|
|
don't forget to send a patch to Buildroot developers!</p>
|
|
|
|
<h2><a name="links" id="links"></a>Resources</h2>
|
|
|
|
<p>To learn more about Buildroot you can visit these
|
|
websites:</p>
|
|
|
|
<ul>
|
|
<li><a href="http://www.uclibc.org/">http://www.uclibc.org/</a></li>
|
|
<li><a href="http://www.busybox.net/">http://www.busybox.net/</a></li>
|
|
</ul>
|
|
</div>
|
|
<!--
|
|
<a href="http://validator.w3.org/check?uri=referer"><img
|
|
border="0" height="31" width="88"
|
|
src="images/valid-html401.png"
|
|
alt="Valid HTML"></img></a>
|
|
-->
|
|
|
|
</body>
|
|
</html>
|