|
@@ -13,8 +13,8 @@
|
|
|
<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
|
|
|
+ <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>
|
|
@@ -53,39 +53,39 @@
|
|
|
<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
|
|
|
+ <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
|
|
|
+ <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
|
|
|
+ <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
|
|
|
+ <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
|
|
@@ -94,17 +94,17 @@
|
|
|
|
|
|
<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>
|
|
|
+ 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
|
|
|
+ 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 id="download">Obtaining Buildroot</h2>
|
|
@@ -113,18 +113,18 @@
|
|
|
months. Direct Git access and daily snapshots are also
|
|
|
available, if you want more bleeding edge.</p>
|
|
|
|
|
|
- <p>Releases are available at
|
|
|
+ <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
|
|
|
+ <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
|
|
|
+ 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
|
|
|
+ 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
|
|
|
+ of the Buildroot website
|
|
|
(<a href="http://buildroot.net">http://buildroot.net</a>).
|
|
|
For the impatient, here's a quick recipe:</p>
|
|
|
|
|
@@ -135,11 +135,11 @@
|
|
|
<h2 id="using">Using Buildroot</h2>
|
|
|
|
|
|
<p>Buildroot has a nice configuration tool similar to the one you can find
|
|
|
- in the Linux kernel
|
|
|
+ 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
|
|
|
+ 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>
|
|
@@ -160,15 +160,15 @@
|
|
|
|
|
|
<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 relevant
|
|
|
- libraries used by the configuration utilities. On Debian-like systems,
|
|
|
+ <p>All of these "make" commands will need to build a configuration
|
|
|
+ utility, so you may need to install "development" packages for relevant
|
|
|
+ libraries used by the configuration utilities. On Debian-like systems,
|
|
|
the <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
|
|
|
+ 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 use the <i>gconfig</i> interface.</p>
|
|
|
|
|
|
- <p>For each menu entry in the configuration tool, you can find associated
|
|
|
+ <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
|
|
@@ -195,50 +195,50 @@
|
|
|
selected in the Buildroot configuration.
|
|
|
</p>
|
|
|
|
|
|
- <p>Buildroot output is stored in a single directory, <code>output/</code>.
|
|
|
+ <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,
|
|
|
+ <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
|
|
|
+ <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
|
|
|
+ <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 complete
|
|
|
- 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 doesn't want to run as
|
|
|
+ <li><code>target/</code> which contains <i>almost</i> the complete
|
|
|
+ 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 doesn't 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:
|
|
|
+ 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, unless the
|
|
|
<code>development files in target filesystem</code> option is selected.
|
|
|
</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
|
|
|
+ <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
|
|
|
+ <li><code>toolchain/</code> contains the build directories for the
|
|
|
various components of the cross-compilation toolchain.</li>
|
|
|
</ul>
|
|
|
|
|
@@ -257,8 +257,8 @@
|
|
|
|
|
|
<h3 id="building_out_of_tree">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
|
|
|
+ <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>
|
|
@@ -273,14 +273,14 @@
|
|
|
|
|
|
<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
|
|
|
+ <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>
|
|
|
|
|
|
- <p>For ease of use, Buildroot generates a Makefile wrapper in the output
|
|
|
- directory - So after the first run, you no longer need to pass
|
|
|
- <code>O=..</code> and <code>-C ..</code>, simply run (in the output
|
|
|
+ <p>For ease of use, Buildroot generates a Makefile wrapper in the output
|
|
|
+ directory - So after the first run, you no longer need to pass
|
|
|
+ <code>O=..</code> and <code>-C ..</code>, simply run (in the output
|
|
|
directory):</p>
|
|
|
|
|
|
<pre>
|
|
@@ -294,12 +294,12 @@
|
|
|
<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, used to compile uClibc, if an
|
|
|
+ <li><code>UCLIBC_CONFIG_FILE=<path/to/.config></code>, path to
|
|
|
+ the uClibc configuration file, used to compile uClibc, if an
|
|
|
internal toolchain is being built</li>
|
|
|
- <li><code>BUSYBOX_CONFIG_FILE=<path/to/.config></code>, path to
|
|
|
+ <li><code>BUSYBOX_CONFIG_FILE=<path/to/.config></code>, path to
|
|
|
the Busybox configuration file</li>
|
|
|
- <li><code>BUILDROOT_DL_DIR</code> to override the directory in which
|
|
|
+ <li><code>BUILDROOT_DL_DIR</code> to override the directory in which
|
|
|
Buildroot stores/retrieves downloaded files</li>
|
|
|
</ul>
|
|
|
|
|
@@ -322,41 +322,41 @@
|
|
|
<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
|
|
|
+ <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>
|
|
|
- fs/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
|
|
|
+ fs/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
|
|
|
+ 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 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
|
|
|
+ <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 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
|
|
@@ -368,12 +368,12 @@
|
|
|
|
|
|
<h2 id="custom_busybox">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
|
|
|
+ <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
|
|
|
+ <li>Do an initial compilation of Buildroot, with busybox, without
|
|
|
trying to customize it.</li>
|
|
|
|
|
|
<li>Invoke <code>make busybox-menuconfig</code>.
|
|
@@ -387,13 +387,13 @@
|
|
|
<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 id="custom_uclibc">Customizing the uClibc configuration</h2>
|
|
|
|
|
|
- <p>Just like <a href="#custom_busybox">BusyBox</a>,
|
|
|
+ <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>
|
|
@@ -430,11 +430,11 @@
|
|
|
|
|
|
<h2 id="custom_linux26">Customizing the Linux kernel configuration</h2>
|
|
|
|
|
|
- <p>The Linux kernel configuration can be customized just like
|
|
|
- <a href="#custom_busybox">BusyBox</a> and
|
|
|
+ <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
|
|
|
+ </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
|
|
@@ -482,8 +482,8 @@
|
|
|
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
|
|
|
+ <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>
|
|
@@ -509,14 +509,14 @@ $(ZLIB_DIR)/libz.a: $(ZLIB_DIR)/.configured
|
|
|
|
|
|
<h2 id="buildroot_innards">How Buildroot works</h2>
|
|
|
|
|
|
- <p>As mentioned above, Buildroot is basically a set of Makefiles that
|
|
|
- download, configure, and compile software with the correct options. It
|
|
|
- also includes patches for various software packages — mainly the
|
|
|
- ones involved in the cross-compilation tool chain (<code>gcc</code>,
|
|
|
+ <p>As mentioned above, Buildroot is basically a set of Makefiles that
|
|
|
+ download, configure, and compile software with the correct options. It
|
|
|
+ also includes patches for various software packages — mainly the
|
|
|
+ ones involved in the cross-compilation 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
|
|
|
+ <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>
|
|
@@ -547,7 +547,7 @@ $(ZLIB_DIR)/libz.a: $(ZLIB_DIR)/.configured
|
|
|
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
|
|
|
+ description file. It describes the options related to the
|
|
|
package.</li>
|
|
|
</ul>
|
|
|
|
|
@@ -661,40 +661,40 @@ endif
|
|
|
|
|
|
<h2 id="using_toolchain">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
|
|
|
+ <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 environment variable and
|
|
|
- then to use <code>ARCH-linux-gcc</code>, <code>ARCH-linux-objdump</code>,
|
|
|
+ <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 environment 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
|
|
|
+ <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
|
|
|
+ <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.
|
|
|
+ Build options -> Toolchain and header file location</code> options.
|
|
|
This could be useful if the toolchain must be shared with other users.</p>
|
|
|
|
|
|
<h2 id="downloaded_packages">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
|
|
|
- known to be working with the associated tarballs. This will allow you to
|
|
|
- regenerate the toolchain and the target filesystem with exactly the same
|
|
|
+ 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
|
|
|
+ known 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
|
|
|
+ <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>
|
|
@@ -742,7 +742,7 @@ endif
|
|
|
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
|
|
|
+ <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
|
|
@@ -751,8 +751,8 @@ endif
|
|
|
<h2 id="add_packages">Adding new packages to Buildroot</h2>
|
|
|
|
|
|
<p>This section covers how new packages (userspace libraries or
|
|
|
- applications) can be integrated into Buildroot. It also shows how existing
|
|
|
- packages are integrated, which is needed for fixing issues or tuning their
|
|
|
+ applications) can be integrated into Buildroot. It also shows how existing
|
|
|
+ packages are integrated, which is needed for fixing issues or tuning their
|
|
|
configuration.</p>
|
|
|
|
|
|
<ul>
|
|
@@ -800,7 +800,7 @@ config BR2_PACKAGE_LIBFOO
|
|
|
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
|
|
|
+ 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>
|
|
|
|
|
@@ -825,28 +825,28 @@ source "package/libfoo/Config.in"
|
|
|
written in a different way, using different infrastructures:</p>
|
|
|
|
|
|
<ul>
|
|
|
- <li><b>Makefiles for generic packages</b> (not using autotools): These
|
|
|
- are based on an infrastructure similar to the one used for
|
|
|
- autotools-based packages, but requires a little more work from the
|
|
|
- developer. They specify what should be done 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
|
|
|
+ <li><b>Makefiles for generic packages</b> (not using autotools): These
|
|
|
+ are based on an infrastructure similar to the one used for
|
|
|
+ autotools-based packages, but requires a little more work from the
|
|
|
+ developer. They specify what should be done 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><b>Makefiles for autotools-based software</b> (autoconf, automake,
|
|
|
- etc.): We provide a dedicated infrastructure for such packages, since
|
|
|
+ <li><b>Makefiles for autotools-based software</b> (autoconf, automake,
|
|
|
+ etc.): 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
|
|
|
+ </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><b>Manual Makefiles:</b> These are currently obsolete, and no new
|
|
|
- manual Makefiles should be added. However, since there are still many
|
|
|
- of them in the tree, we keep them documented in a
|
|
|
+ <li><b>Manual Makefiles:</b> These are currently obsolete, and no new
|
|
|
+ manual Makefiles should be added. However, since there are still many
|
|
|
+ of them in the tree, we keep them documented in a
|
|
|
<a href="#manual-tutorial">tutorial</a>.</li>
|
|
|
</ul>
|
|
|
|
|
@@ -863,61 +863,61 @@ source "package/libfoo/Config.in"
|
|
|
<span style="color: #000000">08:</span><span style="color: #009900"> LIBFOO_SITE</span> = http://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">11:</span>
|
|
|
<span style="color: #000000">12:</span> define LIBFOO_BUILD_CMDS
|
|
|
<span style="color: #000000">13:</span> <span style="color: #009900">$(MAKE)</span> CC=<span style="color: #009900">$(TARGET_CC)</span> LD=<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">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 -m 0755 <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 -m 0644 <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> <span style="color: #009900">$(INSTALL)</span> -D -m 0755 <span style="color: #009900">$(@D)</span>/libfoo.so* <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">21:</span>
|
|
|
<span style="color: #000000">22:</span> define LIBFOO_INSTALL_TARGET_CMDS
|
|
|
<span style="color: #000000">23:</span> <span style="color: #009900">$(INSTALL)</span> -D -m 0755 <span style="color: #009900">$(@D)</span>/libfoo.so* <span style="color: #009900">$(TARGET_DIR)</span>/usr/lib
|
|
|
<span style="color: #000000">24:</span> <span style="color: #009900">$(INSTALL)</span> -d -m 0755 <span style="color: #009900">$(TARGET_DIR)</span>/etc/foo.d
|
|
|
<span style="color: #000000">25:</span> endef
|
|
|
-<span style="color: #000000">26:</span>
|
|
|
+<span style="color: #000000">26:</span>
|
|
|
<span style="color: #000000">27:</span><span style="color: #009900"> $(eval $(call GENTARGETS,package,libfoo))</span>
|
|
|
</pre>
|
|
|
|
|
|
- <p>The Makefile begins on line 6 to 8 with metadata information: 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
|
|
|
+ <p>The Makefile begins on line 6 to 8 with metadata information: 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
|
|
|
+ <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
|
|
|
+ <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
|
|
|
+ <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
|
|
|
+ <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
|
|
|
+ <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 id="generic-reference">Makefile for generic packages : reference</h4>
|
|
@@ -925,28 +925,28 @@ source "package/libfoo/Config.in"
|
|
|
<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
|
|
|
+ <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>, then the
|
|
|
- variables in the <code>.mk</code> file must start with
|
|
|
- <code>LIBFOO_</code> and the configuration option in the
|
|
|
+ <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>, then the
|
|
|
+ variables in the <code>.mk</code> file 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 is a target package (cross-compiled for the target) or a host
|
|
|
- package (natively compiled for the host). If unspecified, it is
|
|
|
+ <li>The third argument is optional. It can be used to tell if the
|
|
|
+ package is 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
|
|
|
+ <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>
|
|
|
|
|
@@ -955,128 +955,128 @@ $(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
|
|
|
+ <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
|
|
|
+ <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 the host 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
|
|
|
+ <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 the host 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 information is (assuming the package name is
|
|
|
+ <p>The list of variables that can be set in a <code>.mk</code> file to
|
|
|
+ give metadata information 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
|
|
|
+ <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:
|
|
|
+ <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
|
|
|
+ <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
|
|
|
+ <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:
|
|
|
+ <br/>Example:
|
|
|
<code>LIBFOO_SITE=http://www.libfoosoftware.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
|
|
|
+ <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
|
|
|
+ <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.</li>
|
|
|
|
|
|
- <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
|
|
|
+ <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.</li> </ul>
|
|
|
|
|
|
- <p>The recommended way to define these variables is to use the following
|
|
|
+ <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
|
|
|
+ <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
|
|
|
+ <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
|
|
|
+ <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
|
|
|
+ <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>documentation</i> and <i>execution</i> of the package
|
|
|
- should be installed. Header files should not be installed, they will
|
|
|
- be copied to the target, if the
|
|
|
+ <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>documentation</i> and <i>execution</i> of the package
|
|
|
+ should be installed. Header files should not be installed, they will
|
|
|
+ be copied to the target, if the
|
|
|
<code>development files in target filesystem</code> option is selected.
|
|
|
</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
|
|
|
+ <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
|
|
|
+ <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
|
|
|
+ <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>, used to list the
|
|
|
- actions to uninstall the package from the staging directory
|
|
|
+ <li><code>LIBFOO_UNINSTALL_STAGING_CMDS</code>, used to list the
|
|
|
+ actions to uninstall the package from the staging directory
|
|
|
<code>$(STAGING_DIR)</code>.</li>
|
|
|
</ul>
|
|
|
|
|
@@ -1093,29 +1093,29 @@ endef
|
|
|
<p>In the action definitions, you can use the following variables:</p>
|
|
|
|
|
|
<ul>
|
|
|
- <li><code>$(@D)</code>, which contains the directory in which the
|
|
|
+ <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
|
|
|
+ <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
|
|
|
+ <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
|
|
|
+ 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
|
|
|
- hooks. These define further actions to perform after existing steps.
|
|
|
- Most 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.
|
|
|
- However, since they are provided by the generic infrastructure, they are
|
|
|
- documented here. The exception is <code>LIBFOO_POST_PATCH_HOOKS</code>.
|
|
|
- Patching the package is not user definable, so
|
|
|
+ <p>The last feature of the generic infrastructure is the ability to add
|
|
|
+ hooks. These define further actions to perform after existing steps.
|
|
|
+ Most 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.
|
|
|
+ However, since they are provided by the generic infrastructure, they are
|
|
|
+ documented here. The exception is <code>LIBFOO_POST_PATCH_HOOKS</code>.
|
|
|
+ Patching the package is not user definable, so
|
|
|
<code>LIBFOO_POST_PATCH_HOOKS</code> will be userful for generic packages.
|
|
|
</p>
|
|
|
|
|
@@ -1130,8 +1130,8 @@ endef
|
|
|
<li><code>LIBFOO_POST_INSTALL_TARGET_HOOKS</code> (for target packages only)</li>
|
|
|
</ul>
|
|
|
|
|
|
- <p>These variables are <i>lists</i> of variable names containing actions
|
|
|
- to be performed at this hook point. This allows several hooks to be
|
|
|
+ <p>These 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>
|
|
@@ -1145,7 +1145,7 @@ LIBFOO_POST_PATCH_HOOKS += LIBFOO_POST_PATCH_FIXUP
|
|
|
|
|
|
<h4 id="autotools-tutorial">Makefile for autotools-based packages : tutorial</h4>
|
|
|
|
|
|
- <p>First, let's see how to write a <code>.mk</code> file for an
|
|
|
+ <p>First, let's see how to write a <code>.mk</code> file for an
|
|
|
autotools-based package, with an example :</p>
|
|
|
|
|
|
<pre>
|
|
@@ -1166,163 +1166,163 @@ LIBFOO_POST_PATCH_HOOKS += LIBFOO_POST_PATCH_FIXUP
|
|
|
</pre>
|
|
|
|
|
|
<p>On line 6, we declare the version of the package.</p>
|
|
|
-
|
|
|
- <p>On line 7 and 8, we declare the name of the tarball and the location
|
|
|
- of the tarball on the Web. Buildroot will automatically download the
|
|
|
+
|
|
|
+ <p>On line 7 and 8, 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 9, we tell Buildroot to install the package to the staging
|
|
|
+ <p>On line 9, 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
|
|
|
+ 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 10, 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 header
|
|
|
- files 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
|
|
|
+ <p>On line 10, 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 header
|
|
|
+ files 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</code> command.</p>
|
|
|
|
|
|
- <p>On line 11, we tell Buildroot to pass a custom configure option, that
|
|
|
- will be passed to the <code>./configure</code> script before configuring
|
|
|
+ <p>On line 11, 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 12, we declare our dependencies, so that they are built
|
|
|
+ <p>On line 12, 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
|
|
|
+ <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 id="autotools-reference">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
|
|
|
+ <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
|
|
|
+ <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 metadata 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>,
|
|
|
+ <p>First, all the package metadata 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
|
|
|
+ <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
|
|
|
+ <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
|
|
|
+ <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
|
|
|
+ <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 is 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 be set to
|
|
|
+ command. This is typically useful when parallel make is 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 be set to
|
|
|
<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
|
|
|
+ <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
|
|
|
+ <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
|
|
|
+ <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
|
|
|
+ <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
|
|
|
+ <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 use the central configure cache, which caches test
|
|
|
- results from previous configure scripts. Usually, this variable should
|
|
|
- be left to its default value. Only packages having issues with the
|
|
|
- configure cache, can set this variable to the <code>NO</code> value
|
|
|
+ <li><code>LIBFOO_USE_CONFIG_CACHE</code> tells whether the configure
|
|
|
+ script should use the central configure cache, which caches test
|
|
|
+ results from previous configure scripts. Usually, this variable should
|
|
|
+ be left to its default value. Only packages having issues with the
|
|
|
+ configure cache, can set this variable to the <code>NO</code> value
|
|
|
(but this is more of a work-around than a 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
|
|
|
+ <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</code>. The default
|
|
|
- value is correct for most autotools packages, but it is still possible
|
|
|
+ <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</code>. The default
|
|
|
+ value is correct for most autotools packages, but it is still possible
|
|
|
to override it if needed.</li>
|
|
|
|
|
|
- <li><code>LIBFOO_CLEAN_OPT</code> contains the make options used to
|
|
|
+ <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
|
|
|
+ <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
|
|
|
+ <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
|
|
|
+ <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 any 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
|
|
|
+ <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> file 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
|
|
|
+ <li>By overriding one of the steps. For example, even if the autotools
|
|
|
+ infrastructure is used, if the package <code>.mk</code> file 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 id ="manual-tutorial">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 to help understand
|
|
|
+ <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 to help understand
|
|
|
how they work.</b></p>
|
|
|
|
|
|
<pre>
|
|
@@ -1386,134 +1386,134 @@ LIBFOO_POST_PATCH_HOOKS += LIBFOO_POST_PATCH_FIXUP
|
|
|
58: 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
|
|
|
+ <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>LIBFOO_VERSION</code>: The version of <i>libfoo</i> that
|
|
|
+ <li><code>LIBFOO_VERSION</code>: The version of <i>libfoo</i> that
|
|
|
should be downloaded.</li>
|
|
|
|
|
|
- <li><code>LIBFOO_SOURCE</code>: The name of the tarball of <i>libfoo</i>
|
|
|
- on the download website or FTP site. As you can see
|
|
|
+ <li><code>LIBFOO_SOURCE</code>: The name of the tarball of <i>libfoo</i>
|
|
|
+ on the download website or FTP site. As you can see
|
|
|
<code>LIBFOO_VERSION</code> is used.</li>
|
|
|
|
|
|
- <li><code>LIBFOO_SITE</code>: The HTTP or FTP site from which
|
|
|
- <i>libfoo</i> archive is downloaded. It must include the complete path to
|
|
|
+ <li><code>LIBFOO_SITE</code>: The HTTP or FTP site from which
|
|
|
+ <i>libfoo</i> archive is downloaded. It must include the complete path to
|
|
|
the directory where <code>LIBFOO_SOURCE</code> can be found.</li>
|
|
|
|
|
|
- <li><code>LIBFOO_DIR</code>: The directory into which the software will
|
|
|
- be configured and compiled. Basically, it's a subdirectory of
|
|
|
+ <li><code>LIBFOO_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>LIBFOO_BINARY</code>: Software binary name. As said previously,
|
|
|
+ <li><code>LIBFOO_BINARY</code>: Software binary name. As said previously,
|
|
|
this is an example for a package with a single binary.</li>
|
|
|
|
|
|
- <li><code>LIBFOO_TARGET_BINARY</code>: The full path of the binary inside
|
|
|
+ <li><code>LIBFOO_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
|
|
|
+ <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
|
|
|
+ <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 be
|
|
|
- installed in <code> /usr</code> on the target filesystem. Finally it
|
|
|
- creates a <code>.configured</code> file to mark the software as
|
|
|
+ <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 be
|
|
|
+ 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).
|
|
|
+ <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
|
|
|
+ <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 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
|
|
|
+ <p>Line <a href="#ex2line40">40</a> defines the main target of the
|
|
|
+ software — the one that will 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>libfoo-source</code> target is <i>mandatory</i> to
|
|
|
- support users that wish to do offline-builds. Furthermore, it eases
|
|
|
+ <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>libfoo-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 Makefile with the appropriate options.
|
|
|
- The <code>-clean</code> target should run <code>make clean</code> on
|
|
|
- $(BUILD_DIR)/package-version and MUST uninstall all files of the package
|
|
|
+ <p>Lines <a href="#ex2line44">44-46</a> define a simple target to clean
|
|
|
+ the software build by calling the Makefile with the appropriate options.
|
|
|
+ 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
|
|
|
+ <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>libfoo</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
|
|
|
+ <p>Lines <a href="#ex2line51">51-58</a> add the target <code>libfoo</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 id="gettext-integration">Gettext integration and interaction with packages</h3>
|
|
|
|
|
|
- <p>Many packages that support internationalization use the gettext
|
|
|
- library. Dependencies for this library are fairly complicated and therefore,
|
|
|
+ <p>Many packages that support internationalization use the gettext
|
|
|
+ library. Dependencies for this library are fairly complicated and therefore,
|
|
|
deserves some explanation.</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
|
|
|
+ <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 kinds of build failures.</p>
|
|
|
|
|
|
- <p>Additionally, some packages (such as libglib2) do require gettext
|
|
|
- unconditionally, while other packages (those who support
|
|
|
- <code>--disable-nls</code> in general) only require gettext when locale
|
|
|
+ <p>Additionally, some packages (such as libglib2) do require gettext
|
|
|
+ unconditionally, 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>
|
|
@@ -1522,18 +1522,18 @@ LIBFOO_POST_PATCH_HOOKS += LIBFOO_POST_PATCH_FIXUP
|
|
|
<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
|
|
|
+ <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 unconditionally need gettext should:</p>
|
|
|
|
|
|
<ol>
|
|
|
- <li>Use <code>select BR2_PACKAGE_GETTEXT if BR2_NEEDS_GETTEXT</code>
|
|
|
- and possibly <code>select BR2_PACKAGE_LIBINTL if BR2_NEEDS_GETTEXT</code>,
|
|
|
+ <li>Use <code>select BR2_PACKAGE_GETTEXT 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
|
|
|
+ <li>Use <code>$(if $(BR2_NEEDS_GETTEXT),gettext)</code> in the package
|
|
|
<code>DEPENDENCIES</code> variable</li>
|
|
|
</ol>
|
|
|
|
|
@@ -1541,23 +1541,23 @@ LIBFOO_POST_PATCH_HOOKS += LIBFOO_POST_PATCH_FIXUP
|
|
|
</p>
|
|
|
|
|
|
<ol>
|
|
|
- <li>Use
|
|
|
- <code>select BR2_PACKAGE_GETTEXT if BR2_NEEDS_GETTEXT_IF_LOCALE</code>
|
|
|
- and possibly
|
|
|
- <code>select BR2_PACKAGE_LIBINTL if BR2_NEEDS_GETTEXT_IF_LOCALE</code>,
|
|
|
+ <li>Use
|
|
|
+ <code>select BR2_PACKAGE_GETTEXT 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
|
|
|
+ <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
|
|
|
+ <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
|
|
|
+ <p>If you package software that might be useful for other people, don't
|
|
|
forget to send a patch to Buildroot developers!</p>
|
|
|
|
|
|
<h2 id="links">Resources</h2>
|