1688 lines
78 KiB
HTML
1688 lines
78 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_packages">Adding new packages to Buildroot</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>
|
|
|
|
or
|
|
|
|
<pre>
|
|
$ make gconfig
|
|
</pre>
|
|
|
|
<p>to run the Qt3 or GTK-based configurators.</p>
|
|
|
|
<p>All 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, <code>libqt3-mt-dev</code> is
|
|
required to use the <i>xconfig</i> interface, and
|
|
<code>libglib2.0-dev, libgtk2.0-dev and libglade2-dev</code> are
|
|
needed to used the <i>gconfig</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. These development files are used to compile libraries
|
|
and applications for the target that depend on other
|
|
libraries.</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>
|
|
|
|
<p>When using out-of-tree builds, the Buildroot
|
|
<code>.config</code> 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.</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 Buildroot packages infrastructures (see
|
|
<a href="#add_packages">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
|
|
used to look like this (before it was converted to the generic
|
|
package infrastructure):</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>
|
|
|
|
<p>Note that most packages, if not all, will progressively be
|
|
ported over the generic or the autotools infrastructure, making it
|
|
much easier to rebuild individual packages.</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 three main
|
|
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>
|
|
|
|
</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_packages" id="add_packages"></a>Adding new
|
|
packages to Buildroot</h2>
|
|
|
|
<p>This section covers how new packages (userspace libraries or
|
|
applications) can be integrated into Buildroot. It also allows to
|
|
understand how existing packages are integrated, which is needed
|
|
to fix issues or tune their configuration.</p>
|
|
|
|
<ul>
|
|
<li><a href="#package-directory">Package directory</a></li>
|
|
<li><a href="#config-in-file"><code>Config.in</code> file</a></li>
|
|
<li><a href="#mk-file">The <code>.mk</code> file</a>
|
|
<ul>
|
|
<li><a href="#generic-tutorial">Makefile for generic
|
|
packages : tutorial</a></li>
|
|
<li><a href="#generic-reference">Makefile for
|
|
generic packages : reference</a></li>
|
|
<li><a href="#autotools-tutorial">Makefile for autotools-based
|
|
packages : tutorial</a></li>
|
|
<li><a href="#autotools-reference">Makefile for autotools-based
|
|
packages : reference</a></li>
|
|
<li><a href="#manual-tutorial">Manual Makefile : tutorial</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#gettext-integration">Gettext integration and
|
|
interaction with packages</a></li>
|
|
</ul>
|
|
|
|
<h3><a name="package-directory"></a>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>
|
|
|
|
<p>Some packages have been grouped by topic in a sub-directory:
|
|
<code>multimedia</code>, <code>java</code>,
|
|
<code>databases</code>, <code>editors</code>, <code>x11r7</code>,
|
|
<code>games</code>. If your package fits in one of these
|
|
categories, then create your package directory in these.</p>
|
|
|
|
<h3><a name="config-in-file"></a><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>libfoo</code> software that will be used and displayed in the
|
|
configuration tool. It should basically contain :</p>
|
|
|
|
<pre>
|
|
config BR2_PACKAGE_LIBFOO
|
|
bool "libfoo"
|
|
help
|
|
This is a comment that explains what libfoo is.
|
|
|
|
http://foosoftware.org/libfoo/
|
|
</pre>
|
|
|
|
<p>Of course, you can add other options 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 <a
|
|
href="http://lxr.free-electrons.com/source/Documentation/kbuild/kconfig-language.txt">http://lxr.free-electrons.com/source/Documentation/kbuild/kconfig-language.txt</a></p>
|
|
|
|
<p>Finally you have to add your new <code>libfoo/Config.in</code> to
|
|
<code>package/Config.in</code> (or in a category subdirectory if
|
|
you decided to put your package in one of the existing
|
|
categories). 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/libfoo/Config.in"
|
|
</pre>
|
|
|
|
<h3><a name="mk-file"></a>The <code>.mk</code> file</h3>
|
|
|
|
<p>Finally, here's the hardest part. Create a file named
|
|
<code>foo.mk</code>. It describes how the package should be
|
|
downloaded, configured, built, installed, etc.</p>
|
|
|
|
<p>Depending on the package type, the <code>.mk</code> file must be
|
|
written in a different way, using different infrastructures:</p>
|
|
|
|
<ul>
|
|
|
|
<li>Makefiles for generic packages (not using autotools), based
|
|
on an infrastructure similar to the one used for autotools-based
|
|
packages, but which requires a little more work from the
|
|
developer : specify what should be done at for the configuration,
|
|
compilation, installation and cleanup of the package. This
|
|
infrastructure must be used for all packages that do not use the
|
|
autotools as their build system. In the future, other specialized
|
|
infrastructures might be written for other build systems.<br/>We
|
|
cover them through a <a
|
|
href="#generic-tutorial">tutorial</a> and a <a
|
|
href="#generic-reference">reference</a>.</li>
|
|
|
|
<li>Makefiles for autotools-based (autoconf, automake, etc.)
|
|
softwares. We provide a dedicated infrastructure for such
|
|
packages, since autotools is a very common build system. This
|
|
infrastructure <i>must</i> be used for new packages that rely on
|
|
the autotools as their build system.<br/>We cover them through a
|
|
<a href="#autotools-tutorial">tutorial</a> and a <a
|
|
href="#autotools-reference">reference</a>.</li>
|
|
|
|
<li>Manual Makefiles. These are currently obsolete and no new
|
|
manual Makefiles should be added. However, since there are still
|
|
many of them in the tree and because the , we keep them documented in a <a
|
|
href="#manual-tutorial">tutorial</a>.</li>
|
|
|
|
</ul>
|
|
|
|
<h4><a name="generic-tutorial"></a>Makefile for generic packages :
|
|
tutorial</h4>
|
|
|
|
<pre><tt><span style="color: #000000">01:</span> <span style="font-style: italic"><span style="color: #9A1900">#############################################################</span></span>
|
|
<span style="color: #000000">02:</span> <span style="font-style: italic"><span style="color: #9A1900">#</span></span>
|
|
<span style="color: #000000">03:</span> <span style="font-style: italic"><span style="color: #9A1900"># libfoo</span></span>
|
|
<span style="color: #000000">04:</span> <span style="font-style: italic"><span style="color: #9A1900">#</span></span>
|
|
<span style="color: #000000">05:</span> <span style="font-style: italic"><span style="color: #9A1900">#############################################################</span></span>
|
|
<span style="color: #000000">06:</span> <span style="color: #990000">LIBFOO_VERSION:=</span>1.0
|
|
<span style="color: #000000">07:</span> <span style="color: #990000">LIBFOO_SOURCE:=</span>libfoo-<span style="color: #009900">$(LIBFOO_VERSION)</span>.tar.gz
|
|
<span style="color: #000000">08:</span> <span style="color: #990000">LIBFOO_SITE:=</span>http<span style="color: #990000">:</span>//www.foosoftware.org/download
|
|
<span style="color: #000000">09:</span> <span style="color: #009900">LIBFOO_INSTALL_STAGING=</span>YES
|
|
<span style="color: #000000">10:</span> <span style="color: #009900">LIBFOO_DEPENDENCIES =</span> host-libaaa libbbb
|
|
<span style="color: #000000">11:</span>
|
|
<span style="color: #000000">12:</span> define LIBFOO_BUILD_CMDS
|
|
<span style="color: #000000">13:</span> <span style="color: #009900">$(MAKE)</span> <span style="color: #009900">CC</span><span style="color: #990000">=</span><span style="color: #009900">$(TARGET_CC)</span> <span style="color: #009900">LD</span><span style="color: #990000">=</span><span style="color: #009900">$(TARGET_LD)</span> -C <span style="color: #009900">$(@D)</span> all
|
|
<span style="color: #000000">14:</span> endef
|
|
<span style="color: #000000">15:</span>
|
|
<span style="color: #000000">16:</span> define LIBFOO_INSTALL_STAGING_CMDS
|
|
<span style="color: #000000">17:</span> <span style="color: #009900">$(INSTALL)</span> -D <span style="color: #009900">$(@D)</span>/libfoo.a <span style="color: #009900">$(STAGING_DIR)</span>/usr/lib/libfoo.a
|
|
<span style="color: #000000">18:</span> <span style="color: #009900">$(INSTALL)</span> -D <span style="color: #009900">$(@D)</span>/foo.h <span style="color: #009900">$(STAGING_DIR)</span>/usr/include/foo.h
|
|
<span style="color: #000000">19:</span> cp -dpf <span style="color: #009900">$(@D)</span>/libfoo.so<span style="color: #990000">*</span> <span style="color: #009900">$(STAGING_DIR)</span>/usr/lib
|
|
<span style="color: #000000">20:</span> endef
|
|
<span style="color: #000000">21:</span>
|
|
<span style="color: #000000">22:</span> define LIBFOO_INSTALL_TARGET_CMDS
|
|
<span style="color: #000000">23:</span> cp -dpf <span style="color: #009900">$(@D)</span>/libfoo.so<span style="color: #990000">*</span> <span style="color: #009900">$(TARGET_DIR)</span>/usr/lib
|
|
<span style="color: #000000">24:</span> -<span style="color: #009900">$(STRIPCMP)</span> <span style="color: #009900">$(STRIP_STRIP_UNNEEDED)</span> <span style="color: #009900">$(TARGET_DIR)</span>/isr/lib/libfoo.so<span style="color: #990000">*</span>
|
|
<span style="color: #000000">25:</span> endef
|
|
<span style="color: #000000">26:</span>
|
|
<span style="color: #000000">27:</span> <span style="color: #009900">$(</span><span style="font-weight: bold"><span style="color: #0000FF">eval</span></span> <span style="color: #009900">$(</span>call GENTARGETS<span style="color: #990000">,</span>package<span style="color: #990000">,</span>libfoo<span style="color: #990000">))</span></tt></pre>
|
|
|
|
<p>The Makefile begins on line 6 to 8 by metadata informations: the
|
|
version of the package (<code>LIBFOO_VERSION</code>), the name of
|
|
the tarball containing the package (<code>LIBFOO_SOURCE</code>) and
|
|
the Internet location at which the tarball can be downloaded
|
|
(<code>LIBFOO_SITE</code>). All variables must start with the same
|
|
prefix, <code>LIBFOO_</code> in this case. This prefix is always
|
|
the uppercased version of the package name (see below to understand
|
|
where the package name is defined).</p>
|
|
|
|
<p>On line 9, we specify that this package wants to install
|
|
something to the staging space. This is often needed for libraries
|
|
since they must install header files and other development files in
|
|
the staging space. This will ensure that the commands listed in the
|
|
<code>LIBFOO_INSTALL_STAGING_CMDS</code> variable will be
|
|
executed.</p>
|
|
|
|
<p>On line 10, we specify the list of dependencies this package
|
|
relies on. These dependencies are listed in terms of lower-case
|
|
package names, which can be packages for the target (without the
|
|
<code>host-</code> prefix) or packages for the host (with the
|
|
<code>host-</code>) prefix). Buildroot will ensure that all these
|
|
packages are built and installed <i>before</i> the current package
|
|
starts its configuration.</p>
|
|
|
|
<p>The rest of the Makefile defines what should be done at the
|
|
different steps of the package configuration, compilation and
|
|
installation. <code>LIBFOO_BUILD_CMDS</code> tells what steps
|
|
should be performed to build the
|
|
package. <code>LIBFOO_INSTALL_STAGING_CMDS</code> tells what steps
|
|
should be performed to install the package in the staging
|
|
space. <code>LIBFOO_INSTALL_TARGET_CMDS</code> tells what steps
|
|
should be performed to install the package in the target space.</p>
|
|
|
|
<p>All these steps rely on the <code>$(@D)</code> variable, which
|
|
contains the directory where the source code of the package has
|
|
been extracted.</p>
|
|
|
|
<p>Finally, on line 27, we call the <code>GENTARGETS</code> which
|
|
generates, according to the variables defined previously, all the
|
|
Makefile code necessary to make your package working.</p>
|
|
|
|
<h4><a name="generic-reference"></a>Makefile for generic packages :
|
|
reference</h4>
|
|
|
|
<p>The <code>GENTARGETS</code> macro takes three arguments:</p>
|
|
|
|
<ul>
|
|
|
|
<li>The first argument is the package directory prefix. If your
|
|
package is in <code>package/libfoo</code>, then the directory
|
|
prefix is <code>package</code>. If your package is in
|
|
<code>package/editors/foo</code>, then the directory prefix must
|
|
be <code>package/editors</code>.</li>
|
|
|
|
<li>The second argument is the lower-cased package name. It must
|
|
match the prefix of the variables in the <code>.mk</code> file
|
|
and must match the configuration option name in the
|
|
<code>Config.in</code> file. For example, if the package name is
|
|
<code>libfoo</code>, so the variables in the <code>.mk</code>
|
|
must start with <code>LIBFOO_</code> and the configuration option
|
|
in the <code>Config.in</code> file must be
|
|
<code>BR2_PACKAGE_LIBFOO</code>.</li>
|
|
|
|
<li>The third argument is optional. It can be used to tell if the
|
|
package if a target package (cross-compiled for the target) or a
|
|
host package (natively compiled for the host). If unspecified, it
|
|
is assumed that it is a target package. See below for
|
|
details.</li>
|
|
|
|
</ul>
|
|
|
|
<p>For a given package, in a single <code>.mk</code> file, it is
|
|
possible to call GENTARGETS twice, once to create the rules to
|
|
generate a target package and once to create the rules to generate
|
|
a host package:</p>
|
|
|
|
<pre>
|
|
$(eval $(call GENTARGETS,package,libfoo))
|
|
$(eval $(call GENTARGETS,package,libfoo,host))
|
|
</pre>
|
|
|
|
<p>This might be useful if the compilation of the target package
|
|
requires some tools to be installed on the host. If the package
|
|
name is <code>libfoo</code>, then the name of the package for the
|
|
target is also <code>libfoo</code>, while the name of the package
|
|
for the host is <code>host-libfoo</code>. These names should be
|
|
used in the DEPENDENCIES variables of other packages if they depend
|
|
on <code>libfoo</code> or <code>host-libfoo</code>.</p>
|
|
|
|
<p>The call to the <code>GENTARGETS</code> macro <b>must</b> be at
|
|
the end of the <code>.mk</code> file, after all variable
|
|
definitions.</p>
|
|
|
|
<p>For the target package, the <code>GENTARGETS</code> uses the
|
|
variables defined by the .mk file and prefixed by the uppercased
|
|
package name: <code>LIBFOO_*</code>. For target package, it uses
|
|
the <code>HOST_LIBFOO_*</code>. For <i>some</i> variables, if the
|
|
<code>HOST_LIBFOO_</code> prefixed variable doesn't exist, the
|
|
package infrastructure uses the corresponding variable prefixed by
|
|
<code>LIBFOO_</code>. This is done for variables that are likely to
|
|
have the same value for both the target and host packages. See
|
|
below for details.</p>
|
|
|
|
<p>The list of variables that can be set in a <code>.mk</code> file
|
|
to give metadata informations is (assuming the package name is
|
|
<code>libfoo</code>) :</p>
|
|
|
|
<ul>
|
|
|
|
<li><code>LIBFOO_VERSION</code>, mandatory, must contain the
|
|
version of the package. Note that if
|
|
<code>HOST_LIBFOO_VERSION</code> doesn't exist, it is assumed to
|
|
be the same as <code>LIBFOO_VERSION</code>.<br/>Example:
|
|
<code>LIBFOO_VERSION=0.1.2</code></li>
|
|
|
|
<li><code>LIBFOO_SOURCE</code> may contain the name of the
|
|
tarball of the package. If <code>HOST_LIBFOO_SOURCE</code> is not
|
|
specified, it defaults to <code>LIBFOO_VERSION</code>. If none
|
|
are specified, then the value is assumed to be
|
|
<code>packagename-$(LIBFOO_VERSION).tar.gz</code>.<br/>Example:
|
|
<code>LIBFOO_SOURCE =
|
|
foobar-$(LIBFOO_VERSION).tar.bz2</code></li>
|
|
|
|
<li><code>LIBFOO_PATCH</code> may contain the name of a patch,
|
|
that will be downloaded from the same location as the tarball
|
|
indicated in <code>LIBFOO_SOURCE</code>. If
|
|
<code>HOST_LIBFOO_PATCH</code> is not specified, it defaults to
|
|
<code>LIBFOO_PATCH</code>. Also note that another mechanism is
|
|
available to patch a package: all files of the form
|
|
<code>packagename-packageversion-description.patch</code> present
|
|
in the package directory inside Buildroot will be applied to the
|
|
package after extraction.</li>
|
|
|
|
<li><code>LIBFOO_SITE</code> may contain the Internet location of
|
|
the tarball of the package. If <code>HOST_LIBFOO_SITE</code> is
|
|
not specified, it defaults to <code>LIBFOO_SITE</code>. If none
|
|
are specified, then the location is assumed to be
|
|
<code>http://$$(BR2_SOURCEFORGE_MIRROR).dl.sourceforge.net/sourceforge/packagename</code>.<br/>Example:
|
|
<code>LIBFOO_SITE=http://www.foosoftware.org/libfoo</code>.</li>
|
|
|
|
<li><code>LIBFOO_DEPENDENCIES</code> lists the dependencies (in
|
|
terms of package name) that are required for the current target
|
|
package to compile. These dependencies are guaranteed to be
|
|
compiled and installed before the configuration of the current
|
|
package starts. In a similar way,
|
|
<code>HOST_LIBFOO_DEPENDENCIES</code> lists the dependency for
|
|
the current host package.</li>
|
|
|
|
<li><code>LIBFOO_INSTALL_STAGING</code> can be set to
|
|
<code>YES</code> or <code>NO</code> (default). If set to
|
|
<code>YES</code>, then the commands in the
|
|
<code>LIBFOO_INSTALL_STAGING_CMDS</code> variables are executed
|
|
to install the package into the staging directory.</p>
|
|
|
|
<li><code>LIBFOO_INSTALL_TARGET</code> can be set to
|
|
<code>YES</code> (default) or <code>NO</code>. If set to
|
|
<code>YES</code>, then the commands in the
|
|
<code>LIBFOO_INSTALL_TARGET_CMDS</code> variables are executed
|
|
to install the package into the target directory.</p>
|
|
|
|
</ul>
|
|
|
|
<p>The recommended way to define these variables is to use the
|
|
following syntax:</p>
|
|
|
|
<pre>
|
|
LIBFOO_VERSION=2.32
|
|
</pre>
|
|
|
|
<p>Now, the variables that define what should be performed at the
|
|
different steps of the build process.</p>
|
|
|
|
<ul>
|
|
|
|
<li><code>LIBFOO_CONFIGURE_CMDS</code>, used to list the
|
|
actions to be performed to configure the package before its
|
|
compilation</li>
|
|
|
|
<li><code>LIBFOO_BUILD_CMDS</code>, used to list the actions to
|
|
be performed to compile the package</li>
|
|
|
|
<li><code>HOST_LIBFOO_INSTALL_CMDS</code>, used to list the
|
|
actions to be performed to install the package, when the
|
|
package is a host package. The package must install its files
|
|
to the directory given by <code>$(HOST_DIR)</code>. All files,
|
|
including development files such as headers should be
|
|
installed, since other packages might be compiled on top of
|
|
this package.</li>
|
|
|
|
<li><code>LIBFOO_INSTALL_TARGET_CMDS</code>, used to list the
|
|
actions to be performed to install the package to the target
|
|
directory, when the package is a target package. The package
|
|
must install its files to the directory given by
|
|
<code>$(TARGET_DIR)</code>. Only the files required for
|
|
<i>execution</i> of the package should be installed. Header
|
|
files and documentation should not be installed.</li>
|
|
|
|
<li><code>LIBFOO_INSTALL_STAGING_CMDS</code>, used to list the
|
|
actions to be performed to install the package to the staging
|
|
directory, when the package is a target package. The package
|
|
must install its files to the directory given by
|
|
<code>$(STAGING_DIR)</code>. All development files should be
|
|
installed, since they might be needed to compile other
|
|
packages.</li>
|
|
|
|
<li><code>LIBFOO_CLEAN_CMDS</code>, used to list the actions to
|
|
perform to clean up the build directory of the package.</li>
|
|
|
|
<li><code>LIBFOO_UNINSTALL_TARGET_CMDS</code>, used to list the
|
|
actions to uninstall the package from the target directory
|
|
<code>$(TARGET_DIR)</code></li>
|
|
|
|
<li><code>LIBFOO_UNINSTALL_STAGING_CMDS</code></li>, used to
|
|
list the actions to uninstall the package from the staging
|
|
directory <code>$(STAGING_DIR)</code>.</li>
|
|
|
|
</ul>
|
|
|
|
<p>The preferred way to define these variables is:</p>
|
|
|
|
<pre>
|
|
define LIBFOO_CONFIGURE_CMDS
|
|
action 1
|
|
action 2
|
|
action 3
|
|
endef</pre>
|
|
|
|
<p>In the action definitions, you can use the following
|
|
variables:</p>
|
|
|
|
<ul>
|
|
|
|
<li><code>$(@D)</code>, which contains the directory in which
|
|
the package source code has been uncompressed.</li>
|
|
|
|
<li><code>$(TARGET_CC)</code>, <code>$(TARGET_LD)</code>,
|
|
etc. to get the target cross-compilation utilities</li>
|
|
|
|
<li><code>$(TARGET_CROSS)</code> to get the cross-compilation
|
|
toolchain prefix</li>
|
|
|
|
<li>Of course the <code>$(HOST_DIR)</code>,
|
|
<code>$(STAGING_DIR)</code> and <code>$(TARGET_DIR)</code>
|
|
variables to install the packages properly.</li>
|
|
|
|
</ul>
|
|
|
|
|
|
<p>The last feature of the generic infrastructure is the ability
|
|
to add hook more actions after existing steps. These hooks aren't
|
|
really useful for generic packages, since the <code>.mk</code>
|
|
file already has full control over the actions performed in each
|
|
step of the package construction. The hooks are more useful for
|
|
packages using the autotools infrastructure described below. But
|
|
since they are provided by the generic infrastructure, they are
|
|
documented here.</p>
|
|
|
|
<p>The following hook points are available:</p>
|
|
|
|
<ul>
|
|
<li><code>LIBFOO_POST_PATCH_HOOKS</code></li>
|
|
<li><code>LIBFOO_POST_CONFIGURE_HOOKS</code></li>
|
|
<li><code>LIBFOO_POST_BUILD_HOOKS</code></li>
|
|
<li><code>LIBFOO_POST_INSTALL_HOOKS</code> (for host packages only)</li>
|
|
<li><code>LIBFOO_POST_INSTALL_STAGING_HOOKS</code> (for target packages only)</li>
|
|
<li><code>LIBFOO_POST_INSTALL_TARGET_HOOKS</code> (for target packages only)</li>
|
|
</ul>
|
|
|
|
<p>This variables are <i>lists</i> of variable names containing
|
|
actions to be performed at this hook point. This allows several
|
|
hooks to be registered at a given hook point. Here is an
|
|
example:</p>
|
|
|
|
<pre>
|
|
define LIBFOO_POST_PATCH_FIXUP
|
|
action1
|
|
action2
|
|
endef
|
|
|
|
LIBFOO_POST_PATCH_HOOKS += LIBFOO_POST_PATCH_FIXUP
|
|
</pre>
|
|
|
|
<h4><a name="autotools-tutorial"></a>Makefile for autotools-based
|
|
packages : tutorial</h4>
|
|
|
|
<p>First, let's see how to write a <code>.mk</code> file for an
|
|
autotools-based package, with an example :</p>
|
|
|
|
<pre><tt><span style="color: #000000">01:</span> <span style="font-style: italic"><span style="color: #9A1900">#############################################################</span></span>
|
|
<span style="color: #000000">02:</span> <span style="font-style: italic"><span style="color: #9A1900">#</span></span>
|
|
<span style="color: #000000">03:</span> <span style="font-style: italic"><span style="color: #9A1900"># foo</span></span>
|
|
<span style="color: #000000">04:</span> <span style="font-style: italic"><span style="color: #9A1900">#</span></span>
|
|
<span style="color: #000000">05:</span> <span style="font-style: italic"><span style="color: #9A1900">#############################################################</span></span>
|
|
<span style="color: #000000">06:</span>
|
|
<span style="color: #000000">07:</span> <span style="color: #990000">FOO_VERSION:=</span>1.0
|
|
<span style="color: #000000">08:</span> <span style="color: #990000">FOO_SOURCE:=</span>foo-<span style="color: #009900">$(FOO_VERSION)</span>.tar.gz
|
|
<span style="color: #000000">09:</span> <span style="color: #990000">FOO_SITE:=</span>http<span style="color: #990000">:</span>//www.foosoftware.org/downloads
|
|
<span style="color: #000000">10:</span> <span style="color: #009900">FOO_INSTALL_STAGING =</span> YES
|
|
<span style="color: #000000">11:</span> <span style="color: #009900">FOO_INSTALL_TARGET =</span> YES
|
|
<span style="color: #000000">12:</span> <span style="color: #009900">FOO_CONF_OPT =</span> --enable-shared
|
|
<span style="color: #000000">13:</span> <span style="color: #009900">FOO_DEPENDENCIES =</span> libglib2 host-pkg-config
|
|
<span style="color: #000000">14:</span>
|
|
<span style="color: #000000">15:</span> <span style="color: #009900">$(</span><span style="font-weight: bold"><span style="color: #0000FF">eval</span></span> <span style="color: #009900">$(</span>call AUTOTARGETS<span style="color: #990000">,</span>package<span style="color: #990000">,</span>foo<span style="color: #990000">))</span></tt></pre>
|
|
|
|
<p>On line 7, we declare the version of the package. On line 8 and
|
|
9, 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 line 10, we tell Buildroot to install the package to the
|
|
staging directory. The staging directory, located in
|
|
<code>output/staging/</code> is the directory where all the
|
|
packages are installed, including their development files, etc. By
|
|
default, packages are not installed to the staging directory,
|
|
since usually, only libraries need to be installed in the staging
|
|
directory: their development files are needed to compile other
|
|
libraries or applications depending on them. Also by default, when
|
|
staging installation is enabled, packages are installed in this
|
|
location using the <code>make install</code> command.</p>
|
|
|
|
<p>On line 11, we tell Buildroot to also install the package to
|
|
the target directory. This directory contains what will become the
|
|
root filesystem running on the target. Usually, we try not to
|
|
install the documentation and to install stripped versions of the
|
|
binary. By default, target installation is enabled, so in fact,
|
|
this line is not strictly necessary. Also by default, packages are
|
|
installed in this location using the <code>make
|
|
install-strip</code> command.</p>
|
|
|
|
<p>On line 12, we tell Buildroot to pass a custom configure
|
|
option, that will be passed to the <code>./configure</code> script
|
|
before configuring and building the package.</p>
|
|
|
|
<p>On line 13, we declare our dependencies, so that they are built
|
|
before the build process of our package starts.</p>
|
|
|
|
<p>Finally, on line line 14, we invoke the
|
|
<code>AUTOTARGETS</code> macro that generates all the Makefile
|
|
rules that actually allows the package to be built.</p>
|
|
|
|
<h4><a name="autotools-reference"></a>Makefile for autotools
|
|
packages : reference</h4>
|
|
|
|
<p>The main macro of the autotools package infrastructure is
|
|
<code>AUTOTARGETS</code>. It has the same number of arguments and
|
|
the same semantic as the <code>GENTARGETS</code> macro, which is
|
|
the main macro of the generic package infrastructure. For
|
|
autotools packages, the ability to have target and host packages
|
|
is also available (and is actually widely used).</p>
|
|
|
|
<p>Just like the generic infrastructure, the autotools
|
|
infrastructure works by defining a number of variables before
|
|
calling the <code>AUTOTARGETS</code> macro.</p>
|
|
|
|
<p>First, all the package meta-information variables that exist in
|
|
the generic infrastructure also exist in the autotools
|
|
infrastructure: <code>LIBFOO_VERSION</code>,
|
|
<code>LIBFOO_SOURCE</code>, <code>LIBFOO_PATCH</code>,
|
|
<code>LIBFOO_SITE</code>, <code>LIBFOO_SUBDIR</code>,
|
|
<code>LIBFOO_DEPENDENCIES</code>,
|
|
<code>LIBFOO_INSTALL_STAGING</code>,
|
|
<code>LIBFOO_INSTALL_TARGET</code>.</p>
|
|
|
|
<p>A few additional variables, specific to the autotools
|
|
infrastructure, can also be defined. Many of them are only useful
|
|
in very specific cases, typical packages will therefore only use a
|
|
few of them.</p>
|
|
|
|
<ul>
|
|
|
|
<li><code>LIBFOO_SUBDIR</code> may contain the name of a
|
|
subdirectory inside the package that contains the configure
|
|
script. This is useful, if for example, the main configure
|
|
script is not at the root of the tree extracted by the
|
|
tarball. If <code>HOST_LIBFOO_SUBDIR</code> is not specified, it
|
|
defaults to <code>LIBFOO_SUBDIR</code>.</li>
|
|
|
|
<li><code>LIBFOO_CONF_ENV</code>, to specify additional
|
|
environment variables to pass to the configure script. By
|
|
default, empty.</li>
|
|
|
|
<li><code>LIBFOO_CONF_OPT</code>, to specify additional
|
|
configure options to pass to the configure script. By default,
|
|
empty.</li>
|
|
|
|
<li><code>LIBFOO_MAKE</code>, to specify an
|
|
alternate <code>make</code> command. This is typically useful
|
|
when parallel make it enabled in the configuration
|
|
(using <code>BR2_JLEVEL</code>) but that this feature should be
|
|
disabled for the given package, for one reason or another. By
|
|
default, set to <code>$(MAKE)</code>. If parallel building is
|
|
not supported by the package, then it should
|
|
do <code>LIBFOO_MAKE=$(MAKE1)</code>.</li>
|
|
|
|
<li><code>LIBFOO_MAKE_ENV</code>, to specify additional
|
|
environment variables to pass to make in the build step. These
|
|
are passed before the <code>make</code> command. By default,
|
|
empty.</li>
|
|
|
|
<li><code>LIBFOO_MAKE_OPT</code>, to specify additional
|
|
variables to pass to make in the build step. These are passed
|
|
after the <code>make</code> command. By default, empty.</li>
|
|
|
|
<li><code>LIBFOO_AUTORECONF</code>, tells whether the package
|
|
should be autoreconfigured or not (i.e, if the configure script
|
|
and Makefile.in files should be re-generated by re-running
|
|
autoconf, automake, libtool, etc.). Valid values
|
|
are <code>YES</code> and <code>NO</code>. By default, the value
|
|
is <code>NO</code></li>
|
|
|
|
<li><code>LIBFOO_AUTORECONF_OPT</code> to specify additional
|
|
options passed to the <i>autoreconf</i> program
|
|
if <code>LIBFOO_AUTORECONF=YES</code>. By default, empty.</li>
|
|
|
|
<li><code>LIBFOO_LIBTOOL_PATCH</code> tells whether the
|
|
Buildroot patch to fix libtool cross-compilation issues should
|
|
be applied or not. Valid values are <code>YES</code>
|
|
and <code>NO</code>. By default, the value
|
|
is <code>YES</code></li>
|
|
|
|
<li><code>LIBFOO_USE_CONFIG_CACHE</code> tells whether the
|
|
configure script should really on a cache file that caches test
|
|
results from previous configure script. Usually, this variable
|
|
should be left to its default value. Only for specific packages
|
|
having issues with the configure cache can set this variable to
|
|
the <code>NO</code> value (but this is more a work-around than a
|
|
really fix)</li>
|
|
|
|
<li><code>LIBFOO_INSTALL_STAGING_OPT</code> contains the make
|
|
options used to install the package to the staging directory. By
|
|
default, the value is <code>DESTDIR=$$(STAGING_DIR)
|
|
install</code>, which is correct for most autotools packages. It
|
|
is still possible to override it.</li>
|
|
|
|
<li><code>LIBFOO_INSTALL_TARGET_OPT</code> contains the make
|
|
options used to install the package to the target directory. By
|
|
default, the value is <code>DESTDIR=$$(TARGET_DIR)
|
|
install-strip</code> if <code>BR2_ENABLE_DEBUG</code> is not
|
|
set, and <code>DESTDIR=$$(TARGET_DIR) install-exec</code>
|
|
if <code>BR2_ENABLE_DEBUG</code> is set. These default values
|
|
are correct for most autotools packages, but it is still
|
|
possible to override them if needed.</li>
|
|
|
|
<li><code>LIBFOO_CLEAN_OPT</code> contains the make options used
|
|
to clean the package. By default, the value
|
|
is <code>clean</code>.</li>
|
|
|
|
<li><code>LIBFOO_UNINSTALL_STAGING_OPT</code>, contains the make
|
|
options used to uninstall the package from the staging
|
|
directory. By default, the value is
|
|
<code>DESTDIR=$$(STAGING_DIR) uninstall</code>.</li>
|
|
|
|
<li><code>LIBFOO_UNINSTALL_TARGET_OPT</code>, contains the make
|
|
options used to uninstall the package from the target
|
|
directory. By default, the value is
|
|
<code>DESTDIR=$$(TARGET_DIR) uninstall</code>.</li>
|
|
|
|
</ul>
|
|
|
|
<p>With the autotools infrastructure, all the steps required to
|
|
build and install the packages are already defined, and they
|
|
generally work well for most autotools-based packages. However,
|
|
when required, it is still possible to customize what is done in
|
|
particular step:</p>
|
|
|
|
<ul>
|
|
|
|
<li>By adding a post-operation hook (after extract, patch,
|
|
configure, build or install). See the reference documentation of
|
|
the generic infrastructure for details.</li>
|
|
|
|
<li>By overriding one of the steps. For example, even if the
|
|
autotools infrastructure is used, if the package
|
|
<code>.mk</code> defines its own
|
|
<code>LIBFOO_CONFIGURE_CMDS</code> variable, it will be used
|
|
instead of the default autotools one. However, using this method
|
|
should be restricted to very specific cases. Do not use it in
|
|
the general case.</li>
|
|
|
|
</ul>
|
|
|
|
<h4><a name="manual-tutorial"></a>Manual Makefile : tutorial</h4>
|
|
|
|
<p><b>NOTE: new manual makefiles should not be created, and
|
|
existing manual makefiles should be converted either to the
|
|
generic infrastructure or the autotools infrastructure. This
|
|
section is only kept to document the existing manual makefiles and
|
|
help understanding how they work.</b></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><a name="gettext-integration"></a>Gettext integration and
|
|
interaction with packages</h3>
|
|
|
|
<p>Many packages that support internationalization use the gettext
|
|
library. Dependency on this library are fairly complicated and
|
|
therefore deserves a few explanations.</p>
|
|
|
|
<p>The <i>uClibc</i> C library doesn't implement gettext
|
|
functionality, therefore with this C library, a separate gettext
|
|
must be compiled. On the other hand, the <i>glibc</i> C library
|
|
does integrate its own gettext, and in this case, the separate
|
|
gettext library should not be compiled, because it creates various
|
|
kind of build failures.</p>
|
|
|
|
<p>Additionnaly, some packages (such as libglib2) do require
|
|
gettext unconditionnally, while other packages (those who
|
|
support <code>--disable-nls</code> in general) only require
|
|
gettext when locale support is enabled.</p>
|
|
|
|
<p>Therefore, Buildroot defines two configuration options:</p>
|
|
|
|
<ul>
|
|
<li><code>BR2_NEEDS_GETTEXT</code>, which is true as soon as the
|
|
toolchain doesn't provide its own gettext implementation</li>
|
|
|
|
<li><code>BR2_NEEDS_GETTEXT_IF_LOCALE</code>, which is true if
|
|
the toolchain doesn't provide its own gettext implementation and
|
|
if locale support is enabled</li>
|
|
|
|
</ul>
|
|
|
|
<p>Therefore, packages that unconditionnally need gettext should:</p>
|
|
|
|
<ol>
|
|
<li>Use <code>select BR2_PACKAGE_GNUTTEXT if
|
|
BR2_NEEDS_GETTEXT</code> and possibly <code>select
|
|
BR2_PACKAGE_LIBINTL if BR2_NEEDS_GETTEXT</code> if libintl is
|
|
also needed</li>
|
|
|
|
<li>Use <code>$(if $(BR2_NEEDS_GETTEXT),gettext)</code> in the
|
|
package <code>DEPENDENCIES</code> variable</li>
|
|
</ol>
|
|
|
|
<p>Packages that need gettext only when locale support is enabled
|
|
should:</p>
|
|
|
|
<ol>
|
|
<li>Use <code>select BR2_PACKAGE_GNUTTEXT if
|
|
BR2_NEEDS_GETTEXT_IF_LOCALE</code> and possibly <code>select
|
|
BR2_PACKAGE_LIBINTL if BR2_NEEDS_GETTEXT_IF_LOCALE</code> if
|
|
libintl is also needed</li>
|
|
|
|
<li>Use <code>$(if
|
|
$(BR2_NEEDS_GETTEXT_IF_LOCALE),gettext)</code> in the
|
|
package <code>DEPENDENCIES</code> variable</li>
|
|
</ol>
|
|
|
|
<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>
|