[Buildroot] [PATCH 3/4] remove the old buildroot.html documentation

Thomas De Schampheleire patrickdepinguin+buildroot at gmail.com
Mon Oct 10 09:03:30 UTC 2011


On Mon, Oct 10, 2011 at 10:46 AM, Thomas Petazzoni
<thomas.petazzoni at free-electrons.com> wrote:
> Signed-off-by: Thomas Petazzoni <thomas.petazzoni at free-electrons.com>
> Acked-by: "Yann E. MORIN" <yann.morin.1998 at anciens.enib.fr>
> ---
>  docs/buildroot.html | 1819 ---------------------------------------------------
>  1 files changed, 0 insertions(+), 1819 deletions(-)
>  delete mode 100644 docs/buildroot.html
>
> diff --git a/docs/buildroot.html b/docs/buildroot.html
> deleted file mode 100644
> index 2314d10..0000000
> --- a/docs/buildroot.html
> +++ /dev/null
> @@ -1,1819 +0,0 @@
> -<!DOCTYPE html>
> -<html lang="en">
> -
> -<head>
> -  <title>Buildroot - Usage and documentation</title>
> -  <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
> -  <link rel="stylesheet" href="stylesheet.css">
> -</head>
> -
> -<body>
> -  <div class="main">
> -    <div class="titre">
> -      <h1>Buildroot</h1>
> -    </div>
> -
> -    <p><a href="http://buildroot.net/">Buildroot</a> usage and documentation
> -    by Thomas Petazzoni. Contributions from Karsten Kruse, Ned Ludd, Martin
> -    Herren and others.</p>
> -
> -    <ul>
> -      <li><a href="#about">About Buildroot</a></li>
> -      <li><a href="#download">Obtaining Buildroot</a></li>
> -      <li><a href="#using">Using Buildroot</a></li>
> -      <li><a href="#custom_targetfs">Customizing the generated target filesystem</a></li>
> -      <li><a href="#custom_busybox">Customizing the Busybox configuration</a></li>
> -      <li><a href="#custom_uclibc">Customizing the uClibc configuration</a></li>
> -      <li><a href="#custom_linux26">Customizing the Linux kernel configuration</a></li>
> -      <li><a href="#rebuilding_packages">Understanding how to rebuild packages</a></li>
> -      <li><a href="#buildroot_innards">How Buildroot works</a></li>
> -      <li><a href="#using_toolchain">Using the uClibc toolchain outside Buildroot</a></li>
> -      <li><a href="#external_toolchain">Use an external toolchain</a></li>
> -      <li><a href="#ccache-support">Using <code>ccache</code> in Buildroot</li>
> -      <li><a href="#downloaded_packages">Location of downloaded packages</a></li>
> -      <li><a href="#add_packages">Adding new packages to Buildroot</a></li>
> -      <li><a href="#board_support">Creating your own board support</a></li>
> -      <li><a href="#faq">Frequently asked questions</a></li>
> -      <li><a href="#links">Resources</a></li>
> -    </ul>
> -
> -    <h2 id="about">About Buildroot</h2>
> -
> -    <p>Buildroot is a set of Makefiles and patches that allows you to easily
> -    generate a cross-compilation toolchain, a root filesystem and a Linux
> -    kernel image for your target. Buildroot can be used for one, two or all
> -    of these options, independently.</p>
> -
> -    <p>Buildroot is useful mainly for people working with embedded systems.
> -    Embedded systems often use processors that are not the regular x86
> -    processors everyone is used to having in his PC. They can be PowerPC
> -    processors, MIPS processors, ARM processors, etc.</p>
> -
> -    <p>A compilation toolchain is the set of tools that allows you to
> -    compile code for your system. It consists of a compiler (in our case,
> -    <code>gcc</code>), binary utils like assembler and linker (in our case,
> -    <code>binutils</code>) and a C standard library (for example
> -    <a href="http://www.gnu.org/software/libc/libc.html">GNU Libc</a>,
> -    <a href="http://www.uclibc.org/">uClibc</a> or
> -    <a href="http://www.fefe.de/dietlibc/">dietlibc</a>). The system installed
> -    on your development station certainly already has a compilation
> -    toolchain that you can use to compile an application that runs on your
> -    system. If you're using a PC, your compilation toolchain runs on an x86
> -    processor and generates code for an x86 processor. Under most Linux
> -    systems, the compilation toolchain uses the GNU libc (glibc) as the C
> -    standard library.  This compilation toolchain is called the "host
> -    compilation toolchain". The machine on which it is running, and on
> -    which you're working, is called the "host system". The
> -    compilation toolchain is provided by your distribution, and Buildroot
> -    has nothing to do with it (other than using it to build a
> -    cross-compilation toolchain and other tools that are run on the
> -    development host).</p>
> -
> -    <p>As said above, the compilation toolchain that comes with your system
> -    runs on and generates code for the processor in your host system. As
> -    your embedded system has a different processor, you need a
> -    cross-compilation toolchain — a compilation toolchain that runs on
> -    your host system but generates code for your target system (and target
> -    processor). For example, if your host system uses x86 and your target
> -    system uses ARM, the regular compilation toolchain on your host runs on
> -    x86 and generates code for x86, while the cross-compilation toolchain
> -    runs on x86 and generates code for ARM.</p>
> -
> -    <p>Even if your embedded system uses an x86 processor, you might be
> -    interested in Buildroot for two reasons:</p>
> -
> -    <ul>
> -      <li>The compilation toolchain on your host certainly uses the GNU Libc
> -      which is a complete but huge C standard library. Instead of using GNU
> -      Libc on your target system, you can use uClibc which is a tiny C
> -      standard library. If you want to use this C library, then you need a
> -      compilation toolchain to generate binaries linked with it. Buildroot
> -      can do that for you.</li>
> -
> -      <li>Buildroot automates the building of a root filesystem with all needed
> -      tools like busybox. That makes it much easier than doing it by hand.</li>
> -    </ul>
> -
> -    <p>You might wonder why such a tool is needed when you can compile
> -    <code>gcc</code>, <code>binutils</code>, <code>uClibc</code> and all
> -    the other tools by hand. Of course doing so is possible but, dealing with
> -    all of the configure options and problems of every <code>gcc</code> or
> -    <code>binutils</code> version is very time-consuming and uninteresting.
> -    Buildroot automates this process through the use of Makefiles and has a
> -    collection of patches for each <code>gcc</code> and <code>binutils</code>
> -    version to make them work on most architectures.</p>
> -
> -    <p>Moreover, Buildroot provides an infrastructure for reproducing
> -    the build process of your kernel, cross-toolchain, and embedded root
> -    filesystem. Being able to reproduce the build process will be useful when a
> -    component needs to be patched or updated or when another person is supposed
> -    to take over the project.</p>
> -
> -    <h2 id="download">Obtaining Buildroot</h2>
> -
> -    <p>Buildroot releases are made approximately every 3
> -    months. Direct Git access and daily snapshots are also
> -    available, if you want more bleeding edge.</p>
> -
> -    <p>Releases are available at
> -    <a href="http://buildroot.net/downloads/">http://buildroot.net/downloads/</a>.</p>
> -
> -    <p>The latest snapshot is always available at
> -    <a href="http://buildroot.net/downloads/snapshots/buildroot-snapshot.tar.bz2">http://buildroot.net/downloads/snapshots/buildroot-snapshot.tar.bz2</a>,
> -    and previous snapshots are also available at
> -    <a href="http://buildroot.net/downloads/snapshots/">http://buildroot.net/downloads/snapshots/</a>.</p>
> -
> -    <p>To download Buildroot using Git, you can simply follow
> -    the rules described on the "Accessing Git" page
> -    (<a href= "http://buildroot.net/git.html">http://buildroot.net/git.html</a>)
> -    of the Buildroot website
> -    (<a href="http://buildroot.net">http://buildroot.net</a>).
> -    For the impatient, here's a quick recipe:</p>
> -
> -<pre>
> - $ git clone git://git.buildroot.net/buildroot
> -</pre>
> -
> -    <h2 id="using">Using Buildroot</h2>
> -
> -    <p>Buildroot has a nice configuration tool similar to the one you can find
> -    in the Linux kernel
> -    (<a href="http://www.kernel.org/">http://www.kernel.org/</a>) or in Busybox
> -    (<a href="http://www.busybox.org/">http://www.busybox.org/</a>). Note that
> -    you can (and should) build everything as a normal user. There is no need to
> -    be root to configure and use Buildroot. The first step is to run the
> -    configuration assistant:</p>
> -
> -<pre>
> - $ make menuconfig
> -</pre>
> -
> -    <p>to run the curses-based configurator, or</p>
> -
> -<pre>
> - $ make xconfig
> -</pre>
> -
> -    <p>or</p>
> -
> -<pre>
> - $ make gconfig
> -</pre>
> -
> -    <p>to run the Qt 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,
> -    the <code>libncurses5-dev</code> package is required to use the <i>
> -    menuconfig</i> interface, <code>libqt4-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
> -    help that describes the purpose of the entry.</p>
> -
> -    <p>Once everything is configured, the configuration tool generates a
> -    <code>.config</code> file that contains the description of your
> -    configuration. It will be used by the Makefiles to do what's needed.</p>
> -
> -
> -    <p>Let's go:</p>
> -
> -<pre>
> - $ make
> -</pre>
> -
> -    <p>You <b>should never</b> use <code>make -jN</code> with
> -    Buildroot: it does not support <i>top-level parallel
> -    make</i>. Instead, use the <code>BR2_JLEVEL</code> option to tell
> -    Buildroot to run each package compilation with <code>make
> -    -jN</code>.</p>
> -
> -    <p>This command will generally perform the following steps:</p>
> -    <ul>
> -      <li>Download source files (as required)</li>
> -      <li>Configure, build and install the cross-compiling toolchain
> -      if an internal toolchain is used, or import a toolchain if an
> -      external toolchain is used</li>
> -      <li>Build/install selected target packages</li>
> -      <li>Build a kernel image, if selected</li>
> -      <li>Build a bootloader image, if selected</li>
> -      <li>Create a root filesystem in selected formats</li>
> -    </ul>
> -
> -    <p>Buildroot output is stored in a single directory, <code>output/</code>.
> -    This directory contains several subdirectories:</p>
> -
> -    <ul>
> -      <li><code>images/</code> where all the images (kernel image,
> -      bootloader and root filesystem images) are stored.</li>
> -
> -      <li><code>build/</code> where all the components except for the
> -      cross-compilation toolchain are built (this includes tools needed to
> -      run Buildroot on the host and packages compiled for the target). The
> -      <code>build/</code> directory contains one subdirectory for each of
> -      these components.</li>
> -
> -      <li><code>staging/</code> which contains a hierarchy similar to a root
> -      filesystem hierarchy. This directory contains the installation of the
> -      cross-compilation toolchain and all the userspace packages selected
> -      for the target. However, this directory is <i>not</i> intended to be
> -      the root filesystem for the target: it contains a lot of development
> -      files, unstripped binaries and libraries that make it far too big for
> -      an embedded system. These development files are used to compile
> -      libraries and applications for the target that depend on other
> -      libraries.</li>
> -
> -      <li><code>target/</code> which contains <i>almost</i> the 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:
> -      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,
> -      including the cross-compilation toolchain.</li>
> -
> -      <li><code>toolchain/</code> contains the build directories for the
> -      various components of the cross-compilation toolchain.</li>
> -    </ul>
> -
> -    <h3 id="offline_builds">Offline builds</h3>
> -
> -    <p>If you intend to do an offline build and just want to download
> -    all sources that you previously selected in the configurator
> -    (<i>menuconfig</i>, <i>xconfig</i> or <i>gconfig</i>), then issue:</p>
> -
> -<pre>
> - $ make source
> -</pre>
> -
> -    <p>You can now disconnect or copy the content of your <code>dl</code>
> -    directory to the build-host.</p>
> -
> -    <h3 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
> -    line:</p>
> -
> -<pre>
> - $ make O=/tmp/build
> -</pre>
> -
> -    <p>Or:</p>
> -
> -<pre>
> - $ cd /tmp/build; make O=$PWD -C path/to/buildroot
> -</pre>
> -
> -    <p>All the output files will be located under <code>/tmp/build</code>.</p>
> -
> -    <p>When using out-of-tree builds, the Buildroot <code>.config</code> and
> -    temporary files are also stored in the output directory. This means that
> -    you can safely run multiple builds in parallel using the same source
> -    tree as long as they use unique output directories.</p>
> -
> -    <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>
> - $ make <target>
> -</pre>
> -
> -    <h3 id="environment_variables">Environment variables</h3>
> -
> -    <p>Buildroot also honors some environment variables, when they are passed
> -    to <code>make</code> or set in the environment:</p>
> -    <ul>
> -      <li><code>HOSTCXX</code>, the host C++ compiler to use</li>
> -      <li><code>HOSTCC</code>, the host C compiler to use</li>
> -      <li><code>UCLIBC_CONFIG_FILE=<path/to/.config></code>, path to
> -      the uClibc configuration file, used to compile uClibc, if an
> -      internal toolchain is being built</li>
> -      <li><code>BUSYBOX_CONFIG_FILE=<path/to/.config></code>, path to
> -      the Busybox configuration file</li>
> -      <li><code>BUILDROOT_DL_DIR</code> to override the directory in which
> -      Buildroot stores/retrieves downloaded files</li>
> -    </ul>
> -
> -    <p>An example that uses config files located in the toplevel directory and
> -    in your $HOME:</p>
> -
> -<pre>
> - $ make UCLIBC_CONFIG_FILE=uClibc.config BUSYBOX_CONFIG_FILE=$HOME/bb.config
> -</pre>
> -
> -    <p>If you want to use a compiler other than the default <code>gcc</code>
> -    or <code>g++</code> for building helper-binaries on your host, then do</p>
> -
> -<pre>
> - $ make HOSTCXX=g++-4.3-HEAD HOSTCC=gcc-4.3-HEAD
> -</pre>
> -
> -       <h2 id="custom_targetfs">Customizing the generated target filesystem</h2>
> -
> -    <p>There are a few ways to customize the resulting target filesystem:</p>
> -
> -    <ul>
> -      <li>Customize the target filesystem directly and rebuild the image.
> -      The target filesystem is available under <code>output/target/</code>.
> -      You can simply make your changes here and run make afterwards —
> -      this will rebuild the target filesystem image. This method allows you
> -      to do anything to the target filesystem, but if you decide to
> -      completely rebuild your toolchain and tools, these changes will be
> -      lost.</li>
> -
> -      <li>Create your own <i>target skeleton</i>. You can start with
> -      the default skeleton available under <code>fs/skeleton</code>
> -      and then customize it to suit your
> -      needs. The <code>BR2_ROOTFS_SKELETON_CUSTOM</code>
> -      and <code>BR2_ROOTFS_SKELETON_CUSTOM_PATH</code> will allow you
> -      to specify the location of your custom skeleton. At build time,
> -      the contents of the skeleton are copied to output/target before
> -      any package installation.</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
> -      post-build cleanup script.</li>
> -
> -      <li>A special package, <i>customize</i>, stored in
> -      <code>package/customize</code> can be used. You can put all the
> -      files that you want to see in the final target root filesystem
> -      in <code>package/customize/source</code>, and then enable this
> -      special package in the configuration system.</li>
> -    </ul>
> -
> -    <h2 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
> -    do so. This method isn't optimal, but it's simple, and it works:</p>
> -
> -    <ol>
> -      <li>Do an initial compilation of Buildroot, with busybox, without
> -      trying to customize it.</li>
> -
> -      <li>Invoke <code>make busybox-menuconfig</code>.
> -      The nice configuration tool appears, and you can
> -      customize everything.</li>
> -
> -      <li>Run the compilation of Buildroot again.</li>
> -    </ol>
> -
> -    <p>Otherwise, you can simply change the
> -    <code>package/busybox/busybox-<version>.config</code> file, if you
> -    know the options you want to change, without using the configuration tool.
> -    </p>
> -
> -    <p>If you want to use an existing config file for busybox, then see
> -    section <a href="#environment_variables">environment variables</a>.</p>
> -
> -    <h2 id="custom_uclibc">Customizing the uClibc configuration</h2>
> -
> -    <p>Just like <a href="#custom_busybox">BusyBox</a>,
> -    <a href="http://www.uclibc.org/">uClibc</a> offers a lot of
> -    configuration options. They allow you to select various
> -    functionalities depending on your needs and limitations.</p>
> -
> -    <p>The easiest way to modify the configuration of uClibc is to
> -    follow these steps:</p>
> -
> -    <ol>
> -      <li>Do an initial compilation of Buildroot without trying to
> -      customize uClibc.</li>
> -
> -      <li>Invoke <code>make uclibc-menuconfig</code>.
> -      The nice configuration assistant, similar to
> -      the one used in the Linux kernel or Buildroot, appears. Make
> -      your configuration changes as appropriate.</li>
> -
> -      <li>Copy the <code>$(O)/toolchain/uclibc-VERSION/.config</code>
> -      file to a different place
> -      (like <code>toolchain/uClibc/uClibc-myconfig.config</code>,
> -      or <code>board/mymanufacturer/myboard/uClibc.config</code>) and
> -      adjust the uClibc configuration (configuration
> -      option <code>BR2_UCLIBC_CONFIG</code>) to use this configuration
> -      instead of the default one.</li>
> -
> -      <li>Run the compilation of Buildroot again.</li>
> -    </ol>
> -
> -    <p>Otherwise, you can simply change
> -    <code>toolchain/uClibc/uClibc.config</code>, without running the
> -    configuration assistant.</p>
> -
> -    <p>If you want to use an existing config file for uclibc, then see
> -    section <a href="#environment_variables">environment variables</a>.</p>
> -
> -    <h2 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
> -    <a href="#custom_uclibc">uClibc</a> using <code>make linux-menuconfig
> -    </code>. Make sure you have enabled the kernel build in <code>make
> -    menuconfig</code> first. Once done, run <code>make</code> to (re)build
> -    everything.</p>
> -
> -    <p>If you want to use an existing config file for Linux, then see
> -    section <a href="#environment_variables">environment variables</a>.</p>
> -
> -    <h2 id="rebuilding_packages">Understanding how to rebuild packages</h2>
> -
> -    <p>One of the most common questions asked by Buildroot
> -    users is how to rebuild a given package or how to
> -    remove a package without rebuilding everything from scratch.</p>
> -
> -    <p>Removing a package is currently unsupported by Buildroot
> -    without rebuilding from scratch. This is because Buildroot doesn't
> -    keep track of which package installs what files in the
> -    <code>output/staging</code> and <code>output/target</code>
> -    directories. However, implementing clean package removal is on the
> -    TODO-list of Buildroot developers.</p>
> -
> -    <p>The easiest way to rebuild a single package from scratch is to
> -    remove its build directory in <code>output/build</code>. Buildroot
> -    will then re-extract, re-configure, re-compile and re-install this
> -    package from scratch.</p>
> -
> -    <p>However, if you don't want to rebuild the package completely
> -    from scratch, a better understanding of the Buildroot internals is
> -    needed. Internally, to keep track of which steps have been done
> -    and which steps remain to be done, Buildroot maintains stamp
> -    files (empty files that just tell whether this or that action
> -    has been done). The problem is that these stamp files are not
> -    uniformly named and handled by the different packages, so some
> -    understanding of the particular package is needed.</p>
> -
> -    <p>For packages relying on Buildroot packages infrastructures (see
> -    <a href="#add_packages">this section</a> for details), the
> -    following stamp files are relevant:</p>
> -
> -    <ul>
> -      <li><code>output/build/packagename-version/.stamp_configured</code>. If
> -      removed, Buildroot will trigger the recompilation of the package
> -      from the configuration step (execution of
> -      <code>./configure</code>).</li>
> -
> -      <li><code>output/build/packagename-version/.stamp_built</code>. If
> -      removed, Buildroot will trigger the recompilation of the package
> -      from the compilation step (execution of <code>make</code>).</li>
> -    </ul>
> -
> -    <p>For other packages, an analysis of the specific <i>package.mk</i>
> -    file is needed. For example, the zlib Makefile used to look like this
> -    (before it was converted to the generic package infrastructure):</p>
> -
> -<pre>
> -$(ZLIB_DIR)/.configured: $(ZLIB_DIR)/.patched
> -       (cd $(ZLIB_DIR); rm -rf config.cache; \
> -               [...]
> -       )
> -       touch $@
> -
> -$(ZLIB_DIR)/libz.a: $(ZLIB_DIR)/.configured
> -       $(MAKE) -C $(ZLIB_DIR) all libz.a
> -       touch -c $@
> -</pre>
> -
> -    <p>If you want to trigger the reconfiguration, you need to
> -    remove <code>output/build/zlib-version/.configured</code>. If
> -    you want to trigger only the recompilation, you need to remove
> -    <code>output/build/zlib-version/libz.a</code>.</p>
> -
> -    <p>Note that most packages, if not all, will progressively be
> -    ported over to the generic or autotools infrastructure, making it
> -    much easier to rebuild individual packages.</p>
> -
> -    <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>,
> -    <code>binutils</code> and <code>uClibc</code>).</p>
> -
> -    <p>There is basically one Makefile per software package, and they are
> -    named with the <code>.mk</code> extension. Makefiles are split into
> -    three main sections:</p>
> -
> -    <ul>
> -      <li><b>toolchain</b> (in the <code>toolchain/</code> directory) contains
> -      the Makefiles and associated files for all software related to the
> -      cross-compilation toolchain: <code>binutils</code>, <code>gcc</code>,
> -      <code>gdb</code>, <code>kernel-headers</code> and <code>uClibc</code>.</li>
> -
> -      <li><b>package</b> (in the <code>package/</code> directory) contains the
> -      Makefiles and associated files for all user-space tools that Buildroot
> -      can compile and add to the target root filesystem. There is one
> -      sub-directory per tool.</li>
> -
> -      <li><b>target</b> (in the <code>target</code> directory) contains the
> -      Makefiles and associated files for software related to the generation of
> -      the target root filesystem image. Four types of filesystems are supported:
> -      ext2, jffs2, cramfs and squashfs. For each of them there is a
> -      sub-directory with the required files. There is also a
> -      <code>default/</code> directory that contains the target filesystem
> -      skeleton.</li>
> -    </ul>
> -
> -    <p>Each directory contains at least 2 files:</p>
> -
> -    <ul>
> -      <li><code>something.mk</code> is the Makefile that downloads, configures,
> -      compiles and installs the package <code>something</code>.</li>
> -
> -      <li><code>Config.in</code> is a part of the configuration tool
> -      description file. It describes the options related to the
> -      package.</li>
> -    </ul>
> -
> -    <p>The main Makefile performs the following steps (once the
> -    configuration is done):</p>
> -
> -    <ol>
> -      <li>Create all the output directories: <code>staging</code>,
> -      <code>target</code>, <code>build</code>, <code>stamps</code>,
> -      etc. in the output directory (<code>output/</code> by default,
> -      another value can be specified using <code>O=</code>)</li>
> -
> -      <li>Generate all the targets listed in the
> -      <code>BASE_TARGETS</code> variable. When an internal toolchain
> -      is used, this means generating the cross-compilation
> -      toolchain. When an external toolchain is used, this means checking
> -      the features of the external toolchain and importing it into the
> -      Buildroot environment.</li>
> -
> -      <li>Generate all the targets listed in the <code>TARGETS</code>
> -      variable. This variable is filled by all the individual
> -      components' Makefiles. Generating these targets will
> -      trigger the compilation of the userspace packages (libraries,
> -      programs), the kernel, the bootloader and the generation of the
> -      root filesystem images, depending on the configuration.</li>
> -    </ol>
> -
> -    <h2 id="board_support"> Creating your own board support</h2>
> -
> -    <p>Creating your own board support in Buildroot allows users of a
> -    particular hardware platform to easily build a system that is
> -    known to work.</p>
> -
> -    <p>To do so, you need to create a normal Buildroot configuration
> -    that builds a basic system for the hardware: toolchain, kernel,
> -    bootloader, filesystem and a simple Busybox-only userspace. No
> -    specific package should be selected: the configuration should be
> -    as minimal as possible, and should only build a working basic
> -    Busybox system for the target platform. You can of course use more
> -    complicated configurations for your internal projects, but the
> -    Buildroot project will only integrate basic board
> -    configurations. This is because package selections are highly
> -    application-specific.</p>
> -
> -    <p>Once you have a known working configuration, run <code>make
> -    savedefconfig</code>. This will generate a
> -    minimal <code>defconfig</code> file at the root of the Buildroot
> -    source tree. Move this file into the <code>configs/</code>
> -    directory, and rename it <code>MYBOARD_defconfig</code>.</p>
> -
> -    <p>It is recommended to use as much as possible upstream versions
> -    of the Linux kernel and bootloaders, and to use as much as
> -    possible default kernel and bootloader configurations. If they are
> -    incorrect for your platform, we encourage you to send fixes to the
> -    corresponding upstream projects.</p>
> -
> -    <p>However, in the mean time, you may want to store kernel or
> -    bootloader configuration or patches specific to your target
> -    platform. To do so, create a
> -    directory <code>board/MANUFACTURER</code> and a
> -    subdirectory <code>board/MANUFACTURER/BOARDNAME</code> (after
> -    replacing, of course, MANUFACTURER and BOARDNAME with the
> -    appropriate values, in lower case letters). You can then store
> -    your patches and configurations in these directories, and
> -    reference them from the main Buildroot configuration.</p>
> -
> -    <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
> -    use the toolchain that was generated by Buildroot.</p>
> -
> -    <p>The toolchain generated by Buildroot is located by default in
> -    <code>output/host/</code>. The simplest way to use it is to add
> -    <code>output/host/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>It is possible to relocate the toolchain — but
> -    then <code>--sysroot</code> must be passed every time the compiler
> -    is called to tell where the libraries and header files are.</p>
> -
> -    <p>It is also possible to generate the Buildroot toolchain in a
> -    directory other than <code>output/host</code> by using the <code>
> -    Build options -> Host dir</code> option.
> -    This could be useful if the toolchain must be shared with other users.</p>
> -
> -    <h2 id="ccache-support">Using <code>ccache</code> in Buildroot</h2>
> -
> -    <p><a href="http://ccache.samba.org">ccache</a> is a compiler
> -    cache. It stores the object files resulting from each compilation
> -    process, and is able to skip future compilation of the same source
> -    file (with same compiler and same arguments) by using the
> -    pre-existing object files. When doing almost identical builds from
> -    scratch a number of times, it can nicely speed up the build
> -    process.</p>
> -
> -    <p><code>ccache</code> support is integrated in Buildroot. You
> -    just have to enable <code>Enable compiler cache</code>
> -    in <code>Build options</code>. This will automatically build
> -    <code>ccache</code> and use it for every host and target
> -    compilation.</p>
> -
> -    <p>The cache is located
> -    in <code>$HOME/.buildroot-ccache</code>. It is stored outside of
> -    Buildroot output directory so that it can be shared by separate
> -    Buildroot builds. If you want to get rid of the cache, simply
> -    remove this directory.</p>
> -
> -    <p>You can get statistics on the cache (its size, number of hits,
> -    misses, etc.) by running <code>make ccache-stats</code>.</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
> -    versions.</p>
> -
> -    <p>If you maintain several Buildroot trees, it might be better to have a
> -    shared download location. This can be accessed by creating a symbolic
> -    link from the <code>dl</code> directory to the shared download location:</p>
> -
> -<pre>
> - $ ln -s <shared download location> dl
> -</pre>
> -
> -    <p>Another way of accessing a shared download location is to
> -    create the <code>BUILDROOT_DL_DIR</code> environment variable.
> -    If this is set, then the value of DL_DIR in the project is
> -    overridden. The following line should be added to
> -    <code>"~/.bashrc"</code>.</p>
> -
> -<pre>
> - $ export BUILDROOT_DL_DIR <shared download location>
> -</pre>
> -
> -    <h2 id="external_toolchain">Using an external toolchain</h2>
> -
> -    <p>Using an already existing toolchain is useful for different
> -    reasons:</p>
> -
> -    <ul>
> -      <li>you already have a toolchain that is known to work for your
> -       specific CPU</li>
> -      <li>you want to speed up the Buildroot build process by skipping
> -      the long toolchain build part</li>
> -      <li>the toolchain generation feature of Buildroot is not
> -       sufficiently flexible for you (for example if you need to
> -       generate a system with <i>glibc</i> instead of
> -       <i>uClibc</i>)</li>
> -    </ul>
> -
> -    <p>Buildroot supports using existing toolchains through a
> -    mechanism called <i>external toolchain</i>. The external toolchain
> -    mechanism is enabled in the <code>Toolchain</code> menu, by
> -    selecting <code>External toolchain</code> in <code>Toolchain
> -    type</code>.</p>
> -
> -    <p>Then, you have three solutions to use an external
> -    toolchain:</p>
> -
> -    <ul>
> -
> -      <li>Use a predefined external toolchain profile, and let
> -      Buildroot download, extract and install the toolchain. Buildroot
> -      already knows about a few CodeSourcery toolchains for ARM,
> -      PowerPC, MIPS and SuperH. Just select the toolchain profile
> -      in <code>Toolchain</code> through the available ones. This is
> -      definitely the easiest solution.</li>
> -
> -      <li>Use a predefined external toolchain profile, but instead of
> -      having Buildroot download and extract the toolchain, you can
> -      tell Buildroot where your toolchain is already installed on your
> -      system. Just select the toolchain profile
> -      in <code>Toolchain</code> through the available ones,
> -      unselect <code>Download toolchain automatically</code>, and fill
> -      the <code>Toolchain path</code> text entry with the path to your
> -      cross-compiling toolchain.</li>
> -
> -      <li>Use a completely custom external toolchain. This is
> -      particularly useful for toolchains generated using
> -      Crosstool-NG. To do this, select the <code>Custom
> -      toolchain</code> solution in the <code>Toolchain</code>
> -      list. You need to fill the <code>Toolchain
> -      path</code>, <code>Toolchain prefix</code> and <code>External
> -      toolchain C library</code> options. Then, you have to tell
> -      Buildroot what your external toolchain supports. If your
> -      external toolchain uses the <i>glibc</i> library, you only have
> -      to tell whether your toolchain supports C++ or not. If your
> -      external toolchain uses the <i>uclibc</i> library, then you have
> -      to tell Buildroot if it supports largefile, IPv6, RPC,
> -      wide-char, locale, program invocation, threads and C++. At the
> -      beginning of the execution, Buildroot will tell you if the
> -      selected options do not match the toolchain configuration.</li>
> -
> -    </ul>
> -
> -    <p>Our external toolchain support has been tested with toolchains
> -    from CodeSourcery, toolchains generated
> -    by <a href="http://ymorin.is-a-geek.org/dokuwiki/projects/crosstool">Crosstool-NG</a>,
> -    and toolchains generated by Buildroot itself. In general, all
> -    toolchains that support the <i>sysroot</i> feature should
> -    work. If not, do not hesitate to contact the developers.</p>
> -
> -    <p>We do not support toolchains from
> -    the <a href="http://www.denx.de/wiki/DULG/ELDK">ELDK of Denx</a>,
> -    for two reasons:</p>
> -
> -    <ul>
> -
> -      <li>The ELDK does not contain a pure toolchain (i.e just the
> -      compiler, binutils, the C and C++ libraries), but a toolchain
> -      that comes with a very large set of pre-compiled libraries and
> -      programs. Therefore, Buildroot cannot import the <i>sysroot</i>
> -      of the toolchain, as it would contain hundreds of megabytes of
> -      pre-compiled libraries that are normally built by
> -      Buildroot.</li>
> -
> -      <li>The ELDK toolchains have a completely non-standard custom
> -      mechanism to handle multiple library variants. Instead of using
> -      the standard GCC <i>multilib</i> mechanism, the ARM ELDK uses
> -      different symbolic links to the compiler to differentiate
> -      between library variants (for ARM soft-float and ARM VFP), and
> -      the PowerPC ELDK compiler uses a <code>CROSS_COMPILE</code>
> -      environment variable. This non-standard behaviour makes it
> -      difficult to support ELDK in Buildroot.</li>
> -
> -    </ul>
> -
> -    <p>We also do not support using the distribution toolchain (i.e
> -    the gcc/binutils/C library installed by your distribution) as the
> -    toolchain to build software for the target. This is because your
> -    distribution toolchain is not a "pure" toolchain (i.e only with
> -    the C/C++ library), so we cannot import it properly into the
> -    Buildroot build environment. So even if you are building a system
> -    for a x86 or x86_64 target, you have to generate a
> -    cross-compilation toolchain with Buildroot or Crosstool-NG.</p>
> -
> -    <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
> -    configuration.</p>
> -
> -    <ul>
> -      <li><a href="#package-directory">Package directory</a></li>
> -      <li><a href="#config-in-file"><code>Config.in</code> file</a></li>
> -      <li><a href="#mk-file">The <code>.mk</code> file</a>
> -        <ul>
> -          <li><a href="#generic-tutorial">Makefile for generic packages : tutorial</a></li>
> -          <li><a href="#generic-reference">Makefile for generic packages : reference</a></li>
> -          <li><a href="#autotools-tutorial">Makefile for autotools-based packages : tutorial</a></li>
> -          <li><a href="#autotools-reference">Makefile for autotools-based packages : reference</a></li>
> -          <li><a href="#cmake-tutorial">Makefile for CMake-based packages : tutorial</a></li>
> -          <li><a href="#cmake-reference">Makefile for CMake-based packages : reference</a></li>
> -          <li><a href="#manual-tutorial">Manual Makefile : tutorial</a></li>
> -        </ul>
> -      </li>
> -      <li><a href="#gettext-integration">Gettext integration and interaction with packages</a></li>
> -    </ul>
> -
> -    <h3 id="package-directory">Package directory</h3>
> -
> -    <p>First of all, create a directory under the <code>package</code>
> -    directory for your software, for example <code>libfoo</code>.</p>
> -
> -    <p>Some packages have been grouped by topic in a sub-directory:
> -    <code>multimedia</code>, <code>java</code>, <code>x11r7</code>, and
> -    <code>games</code>. If your package fits in one of these
> -    categories, then create your package directory in these.</p>
> -
> -    <h3 id="config-in-file"><code>Config.in</code> file</h3>
> -
> -    <p>Then, create a file named <code>Config.in</code>. This file
> -    will contain the option descriptions related to our
> -    <code>libfoo</code> software that will be used and displayed in the
> -    configuration tool. It should basically contain :</p>
> -
> -<pre>
> -config BR2_PACKAGE_LIBFOO
> -       bool "libfoo"
> -       help
> -         This is a comment that explains what libfoo is.
> -
> -         http://foosoftware.org/libfoo/
> -</pre>
> -
> -    <p>Of course, you can add other options to configure particular
> -    things in your software. You can look at examples in other
> -    packages. The syntax of the Config.in file is the same as the one
> -    for the kernel Kconfig file. The documentation for this syntax is
> -    available at
> -    <a href="http://lxr.free-electrons.com/source/Documentation/kbuild/kconfig-language.txt">http://lxr.free-electrons.com/source/Documentation/kbuild/kconfig-language.txt</a>
> -    </p>
> -
> -    <p>Finally you have to add your new <code>libfoo/Config.in</code> to
> -    <code>package/Config.in</code> (or in a category subdirectory if
> -    you decided to put your package in one of the existing
> -    categories). The files included there are <em>sorted
> -    alphabetically</em> per category and are <em>NOT</em> supposed to
> -    contain anything but the <em>bare</em> name of the package.</p>
> -
> -<pre>
> -source "package/libfoo/Config.in"
> -</pre>
> -
> -    <h3 id="mk-file">The <code>.mk</code> file</h3>
> -
> -    <p>Finally, here's the hardest part. Create a file named
> -    <code>libfoo.mk</code>. It describes how the package should be
> -    downloaded, configured, built, installed, etc.</p>
> -
> -    <p>Depending on the package type, the <code>.mk</code> file must be
> -    written in a different way, using different infrastructures:</p>
> -
> -    <ul>
> -      <li><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
> -      autotools is a very common build system. This infrastructure <i>must
> -      </i> be used for new packages that rely on the autotools as their
> -      build system.<br/>We cover them through a
> -      <a href="#autotools-tutorial">tutorial</a> and a
> -      <a href="#autotools-reference">reference</a>.</li>
> -
> -      <li><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>
> -
> -    <h4 id="generic-tutorial">Makefile for generic packages : tutorial</h4>
> -
> -<pre>
> -<span style="color: #000000">01:</span><span style="font-style: italic; color: #9A1900"> #############################################################</span>
> -<span style="color: #000000">02:</span><span style="font-style: italic; color: #9A1900"> #</span>
> -<span style="color: #000000">03:</span><span style="font-style: italic; color: #9A1900"> # libfoo</span>
> -<span style="color: #000000">04:</span><span style="font-style: italic; color: #9A1900"> #</span>
> -<span style="color: #000000">05:</span><span style="font-style: italic; color: #9A1900"> #############################################################</span>
> -<span style="color: #000000">06:</span><span style="color: #009900"> LIBFOO_VERSION</span> = 1.0
> -<span style="color: #000000">07:</span><span style="color: #009900"> LIBFOO_SOURCE</span> = libfoo-<span style="color: #009900">$(LIBFOO_VERSION)</span>.tar.gz
> -<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">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">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">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">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
> -    name is defined).</p>
> -
> -    <p>On line 9, we specify that this package wants to install something to
> -    the staging space. This is often needed for libraries, since they must
> -    install header files and other development files in the staging space.
> -    This will ensure that the commands listed in the
> -    <code>LIBFOO_INSTALL_STAGING_CMDS</code> variable will be executed.</p>
> -
> -    <p>On line 10, we specify the list of dependencies this package relies
> -    on. These dependencies are listed in terms of lower-case package names,
> -    which can be packages for the target (without the <code>host-</code>
> -    prefix) or packages for the host (with the <code>host-</code>) prefix).
> -    Buildroot will ensure that all these packages are built and installed
> -    <i>before</i> the current package starts its configuration.</p>
> -
> -    <p>The rest of the Makefile defines what should be done at the different
> -    steps of the package configuration, compilation and installation.
> -    <code>LIBFOO_BUILD_CMDS</code> tells what steps should be performed to
> -    build the package. <code>LIBFOO_INSTALL_STAGING_CMDS</code> tells what
> -    steps should be performed to install the package in the staging space.
> -    <code>LIBFOO_INSTALL_TARGET_CMDS</code> tells what steps should be
> -    performed to install the package in the target space.</p>
> -
> -    <p>All these steps rely on the <code>$(@D)</code> variable, which
> -    contains the directory where the source code of the package has been
> -    extracted.</p>
> -
> -    <p>Finally, on line 27, we call the <code>GENTARGETS</code> which
> -    generates, according to the variables defined previously, all the
> -    Makefile code necessary to make your package working.</p>
> -
> -    <h4 id="generic-reference">Makefile for generic packages : reference</h4>
> -
> -    <p>The <code>GENTARGETS</code> macro takes three arguments:</p>
> -
> -    <ul>
> -      <li>The first argument is the package directory prefix. If your
> -      package is in <code>package/libfoo</code>, then the directory prefix
> -      is <code>package</code>. If your package is in
> -      <code>package/editors/foo</code>, then the directory prefix must be
> -      <code>package/editors</code>.</li>
> -
> -      <li>The second argument is the lower-cased package name. It must match
> -      the prefix of the variables in the <code>.mk</code> file and must
> -      match the configuration option name in the <code>Config.in</code>
> -      file. For example, if the package name is <code>libfoo</code>, 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
> -      assumed that it is a target package. See below for details.</li>
> -    </ul>
> -
> -    <p>For a given package, in a single <code>.mk</code> file, it is
> -    possible to call GENTARGETS twice, once to create the rules to generate
> -    a target package and once to create the rules to generate a host package:
> -    </p>
> -
> -<pre>
> -$(eval $(call GENTARGETS,package,libfoo))
> -$(eval $(call GENTARGETS,package,libfoo,host))
> -</pre>
> -
> -    <p>This might be useful if the compilation of the target package
> -    requires some tools to be installed on the host. If the package name is
> -    <code>libfoo</code>, then the name of the package for the target is also
> -    <code>libfoo</code>, while the name of the package for the host is
> -    <code>host-libfoo</code>. These names should be used in the DEPENDENCIES
> -    variables of other packages, if they depend on <code>libfoo</code> or
> -    <code>host-libfoo</code>.</p>
> -
> -    <p>The call to the <code>GENTARGETS</code> macro <b>must</b> be at the
> -    end of the <code>.mk</code> file, after all variable definitions.</p>
> -
> -    <p>For the target package, the <code>GENTARGETS</code> uses the
> -    variables defined by the .mk file and prefixed by the uppercased package
> -    name: <code>LIBFOO_*</code>. For 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
> -    <code>libfoo</code>) :</p>
> -
> -    <ul>
> -      <li><code>LIBFOO_VERSION</code>, mandatory, must contain the
> -      version of the package. Note that
> -      if <code>HOST_LIBFOO_VERSION</code> doesn't exist, it is assumed
> -      to be the same as <code>LIBFOO_VERSION</code>. It can also be a
> -      Subversion or Git branch or tag, for packages that are fetched
> -      directly from their revision control system.<br/>
> -      Example: <code>LIBFOO_VERSION = 0.1.2</code></li>
> -
> -      <li><code>LIBFOO_SOURCE</code> may contain the name of the tarball of
> -      the package. If <code>HOST_LIBFOO_SOURCE</code> is not specified, it
> -      defaults to <code>LIBFOO_VERSION</code>. If none are specified, then
> -      the value is assumed to be
> -      <code>packagename-$(LIBFOO_VERSION).tar.gz</code>.<br/>Example:
> -      <code>LIBFOO_SOURCE = foobar-$(LIBFOO_VERSION).tar.bz2</code></li>
> -
> -      <li><code>LIBFOO_PATCH</code> may contain the name of a patch, that
> -      will be downloaded from the same location as the tarball indicated in
> -      <code>LIBFOO_SOURCE</code>. If <code>HOST_LIBFOO_PATCH</code> is not
> -      specified, it defaults to <code>LIBFOO_PATCH</code>. Also note that
> -      another mechanism is available to patch a package: all files of the
> -      form <code>packagename-packageversion-description.patch</code> present
> -      in the package directory inside Buildroot will be applied to the
> -      package after extraction.</li>
> -
> -      <li><code>LIBFOO_SITE</code> may contain the Internet location
> -      of the package. It can either be the HTTP or FTP location of a
> -      tarball, or the URL of a Git or Subversion repository
> -      (see <code>LIBFOO_SITE_METHOD</code>
> -      below). 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/>Examples:<br/>
> -      <code>LIBFOO_SITE=http://www.libfoosoftware.org/libfoo</code><br/>
> -      <code>LIBFOO_SITE=http://svn.xiph.org/trunk/Tremor/</code></li>
> -
> -      <li><code>LIBFOO_SITE_METHOD</code> may contain the method to
> -      fetch the package source code. It can either
> -      be <code>wget</code> (for normal FTP/HTTP downloads of
> -      tarballs), <code>svn</code>, <code>git</code> or <code>bzr</code>.
> -      When not specified, it is guessed from the URL given
> -      in <code>LIBFOO_SITE</code>: <code>svn://</code>, <code>git://</code>
> -      and <code>bzr://</code> URLs will use the <code>svn</code>,
> -      <code>git</code> and <code>bzr</code> methods respectively. All other
> -      URL-types will use the <code>wget</code> method. So for example, in the
> -      case of a package whose source code is available through
> -      Subversion repository on HTTP, one <i>must</i>
> -      specifiy <code>LIBFOO_SITE_METHOD=svn</code>. For <code>svn</code>
> -      and <code>git</code> methods, what Buildroot does is a
> -      checkout/clone of the repository which is then tarballed and
> -      stored into the download cache. Next builds will not
> -      checkout/clone again, but will use the tarball
> -      directly. When <code>HOST_LIBFOO_SITE_METHOD</code> is not
> -      specified, it defaults to the value
> -      of <code>LIBFOO_SITE_METHOD</code>. See <code>package/multimedia/tremor/</code>
> -      for an example.</li>
> -
> -      <li><code>LIBFOO_DEPENDENCIES</code> lists the dependencies (in terms
> -      of package name) that are required for the current target package to
> -      compile. These dependencies are guaranteed to be compiled and
> -      installed before the configuration of the current package starts. In a
> -      similar way, <code>HOST_LIBFOO_DEPENDENCIES</code> lists the
> -      dependency for the current host package.</li>
> -
> -      <li><code>LIBFOO_INSTALL_STAGING</code> can be set to <code>YES</code>
> -      or <code>NO</code> (default). If set to <code>YES</code>, then the
> -      commands in the <code>LIBFOO_INSTALL_STAGING_CMDS</code> variables are
> -      executed to install the package into the staging directory.</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
> -      executed to install the package into the target directory.</li> </ul>
> -
> -    <p>The recommended way to define these variables is to use the following
> -    syntax:</p>
> -
> -<pre>
> -LIBFOO_VERSION = 2.32
> -</pre>
> -
> -    <p>Now, the variables that define what should be performed at the
> -    different steps of the build process.</p>
> -
> -    <ul>
> -      <li><code>LIBFOO_CONFIGURE_CMDS</code>, used to list the actions to be
> -      performed to configure the package before its compilation</li>
> -
> -      <li><code>LIBFOO_BUILD_CMDS</code>, used to list the actions to be
> -      performed to compile the package</li>
> -
> -      <li><code>HOST_LIBFOO_INSTALL_CMDS</code>, used to list the actions to
> -      be performed to install the package, when the package is a host
> -      package. The package must install its files to the directory given by
> -      <code>$(HOST_DIR)</code>. All files, including development files such
> -      as headers should be installed, since other packages might be compiled
> -      on top of this package.</li>
> -
> -      <li><code>LIBFOO_INSTALL_TARGET_CMDS</code>, used to list the actions
> -      to be performed to install the package to the target directory, when
> -      the package is a target package. The package must install its files to
> -      the directory given by <code>$(TARGET_DIR)</code>. Only the files
> -      required for <i>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
> -      packages.</li>
> -
> -      <li><code>LIBFOO_CLEAN_CMDS</code>, used to list the actions to
> -      perform to clean up the build directory of the package.</li>
> -
> -      <li><code>LIBFOO_UNINSTALL_TARGET_CMDS</code>, used to list the actions
> -      to uninstall the package from the target directory
> -      <code>$(TARGET_DIR)</code></li>
> -
> -      <li><code>LIBFOO_UNINSTALL_STAGING_CMDS</code>, used to list the
> -      actions to uninstall the package from the staging directory
> -      <code>$(STAGING_DIR)</code>.</li>
> -    </ul>
> -
> -    <p>The preferred way to define these variables is:</p>
> -
> -<pre>
> -define LIBFOO_CONFIGURE_CMDS
> -       action 1
> -       action 2
> -       action 3
> -endef
> -</pre>
> -
> -    <p>In the action definitions, you can use the following variables:</p>
> -
> -    <ul>
> -      <li><code>$(@D)</code>, which contains the directory in which the
> -      package source code has been uncompressed.</li>
> -
> -      <li><code>$(TARGET_CC)</code>, <code>$(TARGET_LD)</code>, etc. to get
> -      the target cross-compilation utilities</li>
> -
> -      <li><code>$(TARGET_CROSS)</code> to get the cross-compilation
> -      toolchain prefix</li>
> -
> -      <li>Of course the <code>$(HOST_DIR)</code>, <code>$(STAGING_DIR)</code>
> -      and <code>$(TARGET_DIR)</code> variables to install the packages
> -      properly.</li>
> -    </ul>
> -
> -    <p>The last feature of the generic infrastructure is the ability to add
> -    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>
> -
> -    <p>The following hook points are available:</p>
> -
> -    <ul>
> -      <li><code>LIBFOO_POST_PATCH_HOOKS</code></li>
> -      <li><code>LIBFOO_PRE_CONFIGURE_HOOKS</code></li>
> -      <li><code>LIBFOO_POST_CONFIGURE_HOOKS</code></li>
> -      <li><code>LIBFOO_POST_BUILD_HOOKS</code></li>
> -      <li><code>LIBFOO_POST_INSTALL_HOOKS</code> (for host packages only)</li>
> -      <li><code>LIBFOO_POST_INSTALL_STAGING_HOOKS</code> (for target packages only)</li>
> -      <li><code>LIBFOO_POST_INSTALL_TARGET_HOOKS</code> (for target packages only)</li>
> -    </ul>
> -
> -    <p>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>
> -define LIBFOO_POST_PATCH_FIXUP
> -       action1
> -       action2
> -endef
> -
> -LIBFOO_POST_PATCH_HOOKS += LIBFOO_POST_PATCH_FIXUP
> -</pre>
> -
> -   <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
> -   autotools-based package, with an example :</p>
> -
> -<pre>
> -<span style="color: #000000">01:</span><span style="font-style: italic; color: #9A1900"> #############################################################</span>
> -<span style="color: #000000">02:</span><span style="font-style: italic; color: #9A1900"> #</span>
> -<span style="color: #000000">03:</span><span style="font-style: italic; color: #9A1900"> # libfoo</span>
> -<span style="color: #000000">04:</span><span style="font-style: italic; color: #9A1900"> #</span>
> -<span style="color: #000000">05:</span><span style="font-style: italic; color: #9A1900"> #############################################################</span>
> -<span style="color: #000000">06:</span><span style="color: #009900"> LIBFOO_VERSION</span> = 1.0
> -<span style="color: #000000">07:</span><span style="color: #009900"> LIBFOO_SOURCE</span> = libfoo-<span style="color: #009900">$(LIBFOO_VERSION)</span>.tar.gz
> -<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_INSTALL_TARGET</span> = YES
> -<span style="color: #000000">11:</span><span style="color: #009900"> LIBFOO_CONF_OPT</span> = --enable-shared
> -<span style="color: #000000">12:</span><span style="color: #009900"> LIBFOO_DEPENDENCIES</span> = libglib2 host-pkg-config
> -<span style="color: #000000">13:</span>
> -<span style="color: #000000">14:</span><span style="color: #009900"> $(eval $(call AUTOTARGETS,package,libfoo))</span>
> -</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
> -    tarball from this location.</p>
> -
> -    <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
> -    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
> -    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
> -    and building the package.</p>
> -
> -    <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
> -    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
> -    actually widely used).</p>
> -
> -    <p>Just like the generic infrastructure, the autotools infrastructure
> -    works by defining a number of variables before calling the
> -    <code>AUTOTARGETS</code> macro.</p>
> -
> -    <p>First, all the package 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
> -    cases, typical packages will therefore only use a few of them.</p>
> -
> -    <ul>
> -      <li><code>LIBFOO_SUBDIR</code> may contain the name of a subdirectory
> -      inside the package that contains the configure script. This is useful,
> -      if for example, the main configure script is not at the root of the
> -      tree extracted by the tarball. If <code>HOST_LIBFOO_SUBDIR</code> is
> -      not specified, it defaults to <code>LIBFOO_SUBDIR</code>.</li>
> -
> -      <li><code>LIBFOO_CONF_ENV</code>, to specify additional environment
> -      variables to pass to the configure script. By default, empty.</li>
> -
> -      <li><code>LIBFOO_CONF_OPT</code>, to specify additional configure
> -      options to pass to the configure script. By default, empty.</li>
> -
> -      <li><code>LIBFOO_MAKE</code>, to specify an alternate <code>make</code>
> -      command. This is typically useful when parallel make 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
> -      the <code>make</code> command. By default, empty.</li>
> -
> -      <li><code>LIBFOO_MAKE_OPT</code>, to specify additional variables to
> -      pass to make in the build step. These are passed after the
> -      <code>make</code> command. By default, empty.</li>
> -
> -      <li><code>LIBFOO_AUTORECONF</code>, tells whether the package should
> -      be autoreconfigured or not (i.e, if the configure script and
> -      Makefile.in files should be re-generated by re-running autoconf,
> -      automake, libtool, etc.). Valid values are <code>YES</code> and
> -      <code>NO</code>. By default, the value is <code>NO</code></li>
> -
> -      <li><code>LIBFOO_AUTORECONF_OPT</code> to specify additional options
> -      passed to the <i>autoreconf</i> program if
> -      <code>LIBFOO_AUTORECONF=YES</code>. By default, empty.</li>
> -
> -      <li><code>LIBFOO_LIBTOOL_PATCH</code> tells whether the Buildroot
> -      patch to fix libtool cross-compilation issues should be applied or
> -      not. Valid values are <code>YES</code> and <code>NO</code>. By
> -      default, the value is <code>YES</code></li>
> -
> -      <li><code>LIBFOO_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
> -      to override it if needed.</li>
> -
> -      <li><code>LIBFOO_CLEAN_OPT</code> contains the make options used to
> -      clean the package. By default, the value is <code>clean</code>.</li>
> -
> -      <li><code>LIBFOO_UNINSTALL_STAGING_OPT</code>, contains the make
> -      options used to uninstall the package from the staging directory. By
> -      default, the value is <code>DESTDIR=$$(STAGING_DIR) uninstall</code>.</li>
> -
> -      <li><code>LIBFOO_UNINSTALL_TARGET_OPT</code>, contains the make
> -      options used to uninstall the package from the target directory. By
> -      default, the value is <code>DESTDIR=$$(TARGET_DIR) uninstall</code>.</li>
> -    </ul>
> -
> -    <p>With the autotools infrastructure, all the steps required to build
> -    and install the packages are already defined, and they generally work
> -    well for most autotools-based packages. However, when required, it is
> -    still possible to customize what is done in 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
> -      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
> -      general case.</li>
> -    </ul>
> -
> -    <h4 id="cmake-tutorial">Makefile for CMake-based packages : tutorial</h4>
> -
> -    <p>First, let's see how to write a <code>.mk</code> file for a CMake-based
> -    package, with an example :</p>
> -
> -<pre>
> -<span style="color: #000000">01:</span><span style="font-style: italic; color: #9A1900"> #############################################################</span>
> -<span style="color: #000000">02:</span><span style="font-style: italic; color: #9A1900"> #</span>
> -<span style="color: #000000">03:</span><span style="font-style: italic; color: #9A1900"> # libfoo</span>
> -<span style="color: #000000">04:</span><span style="font-style: italic; color: #9A1900"> #</span>
> -<span style="color: #000000">05:</span><span style="font-style: italic; color: #9A1900"> #############################################################</span>
> -<span style="color: #000000">06:</span><span style="color: #009900"> LIBFOO_VERSION</span> = 1.0
> -<span style="color: #000000">07:</span><span style="color: #009900"> LIBFOO_SOURCE</span> = libfoo-<span style="color: #009900">$(LIBFOO_VERSION)</span>.tar.gz
> -<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_INSTALL_TARGET</span> = YES
> -<span style="color: #000000">11:</span><span style="color: #009900"> LIBFOO_CONF_OPT</span> = -DBUILD_DEMOS=ON
> -<span style="color: #000000">12:</span><span style="color: #009900"> LIBFOO_DEPENDENCIES</span> = libglib2 host-pkg-config
> -<span style="color: #000000">13:</span>
> -<span style="color: #000000">14:</span><span style="color: #009900"> $(eval $(call CMAKETARGETS,package,libfoo))</span>
> -</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
> -    tarball from this location.</p>
> -
> -    <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
> -    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
> -    using the <code>make install</code> command.</p>
> -
> -    <p>On line 11, we tell Buildroot to pass custom options to CMake when it is
> -    configuring the package.</p>
> -
> -    <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>CMAKETARGETS</code>
> -    macro that generates all the Makefile rules that actually allows the
> -    package to be built.</p>
> -
> -    <h4 id="cmake-reference">Makefile for CMake packages : reference</h4>
> -
> -    <p>The main macro of the CMake package infrastructure is
> -    <code>CMAKETARGETS</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 CMake packages, the
> -    ability to have target and host packages is also available.</p>
> -
> -    <p>Just like the generic infrastructure, the CMake infrastructure
> -    works by defining a number of variables before calling the
> -    <code>CMAKETARGETS</code> macro.</p>
> -
> -    <p>First, all the package metadata information variables that exist in the
> -    generic infrastructure also exist in the CMake 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 CMake 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 main CMakeLists.txt file. This is
> -      useful, if for example, the main CMakeLists.txt file is not at the root
> -      of the tree extracted by the tarball. If <code>HOST_LIBFOO_SUBDIR</code>
> -      is not specified, it defaults to <code>LIBFOO_SUBDIR</code>.</li>
> -
> -      <li><code>LIBFOO_CONF_ENV</code>, to specify additional environment
> -      variables to pass to CMake. By default, empty.</li>
> -
> -      <li><code>LIBFOO_CONF_OPT</code>, to specify additional configure
> -      options to pass to CMake. 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
> -      <code>LIBFOO_MAKE=$(MAKE1)</code>.</li>
> -
> -      <li><code>LIBFOO_MAKE_ENV</code>, to specify additional environment
> -      variables to pass to make in the build step. These are passed before
> -      the <code>make</code> command. By default, empty.</li>
> -
> -      <li><code>LIBFOO_MAKE_OPT</code>, to specify additional variables to
> -      pass to make in the build step. These are passed after the
> -      <code>make</code> command. By default, empty.</li>
> -
> -      <li><code>LIBFOO_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 CMake 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 CMake packages, but it is still possible
> -      to override it if needed.</li>
> -
> -      <li><code>LIBFOO_CLEAN_OPT</code> contains the make options used to
> -      clean the package. By default, the value is <code>clean</code>.</li>
> -    </ul>
> -
> -    <p>With the CMake infrastructure, all the steps required to build
> -    and install the packages are already defined, and they generally work
> -    well for most CMake-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
> -      infrastructure for details.</li>
> -
> -      <li>By overriding one of the steps. For example, even if the CMake
> -      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 CMake 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, autotools
> -    or cmake infrastructure. This section is only kept to document the existing
> -    manual makefiles and to help understand how they work.</b></p>
> -
> -<pre>
> -01: #############################################################
> -02: #
> -03: # libfoo
> -04: #
> -05: #############################################################
> -<span id="ex2line6">06: LIBFOO_VERSION:=1.0</span>
> -07: LIBFOO_SOURCE:=libfoo-$(LIBFOO_VERSION).tar.gz
> -08: LIBFOO_SITE:=http://www.foosoftware.org/downloads
> -09: LIBFOO_DIR:=$(BUILD_DIR)/foo-$(FOO_VERSION)
> -10: LIBFOO_BINARY:=foo
> -11: LIBFOO_TARGET_BINARY:=usr/bin/foo
> -12:
> -<span id="ex2line13">13: $(DL_DIR)/$(LIBFOO_SOURCE):</span>
> -14:    $(call DOWNLOAD,$(LIBFOO_SITE),$(LIBFOO_SOURCE))
> -15:
> -<span id="ex2line16">16: $(LIBFOO_DIR)/.source: $(DL_DIR)/$(LIBFOO_SOURCE)</span>
> -17:    $(ZCAT) $(DL_DIR)/$(LIBFOO_SOURCE) | tar -C $(BUILD_DIR) $(TAR_OPTIONS) -
> -18:    touch $@
> -19:
> -<span id="ex2line20">20: $(LIBFOO_DIR)/.configured: $(LIBFOO_DIR)/.source</span>
> -21:    (cd $(LIBFOO_DIR); rm -rf config.cache; \
> -22:            $(TARGET_CONFIGURE_OPTS) \
> -23:            $(TARGET_CONFIGURE_ARGS) \
> -24:            ./configure \
> -25:            --target=$(GNU_TARGET_NAME) \
> -26:            --host=$(GNU_TARGET_NAME) \
> -27:            --build=$(GNU_HOST_NAME) \
> -28:            --prefix=/usr \
> -29:            --sysconfdir=/etc \
> -30:    )
> -31:    touch $@
> -32:
> -<span id="ex2line33">33: $(LIBFOO_DIR)/$(LIBFOO_BINARY): $(LIBFOO_DIR)/.configured</span>
> -34:    $(MAKE) CC=$(TARGET_CC) -C $(LIBFOO_DIR)
> -35:
> -<span id="ex2line36">36: $(TARGET_DIR)/$(LIBFOO_TARGET_BINARY): $(LIBFOO_DIR)/$(LIBFOO_BINARY)</span>
> -37:    $(MAKE) DESTDIR=$(TARGET_DIR) -C $(LIBFOO_DIR) install-strip
> -38:    rm -Rf $(TARGET_DIR)/usr/man
> -39:
> -<span id="ex2line40">40: libfoo: uclibc ncurses $(TARGET_DIR)/$(LIBFOO_TARGET_BINARY)</span>
> -41:
> -<span id="ex2line42">42: libfoo-source: $(DL_DIR)/$(LIBFOO_SOURCE)</span>
> -43:
> -<span id="ex2line44">44: libfoo-clean:</span>
> -45:    $(MAKE) prefix=$(TARGET_DIR)/usr -C $(LIBFOO_DIR) uninstall
> -46:    -$(MAKE) -C $(LIBFOO_DIR) clean
> -47:
> -<span id="ex2line48">48: libfoo-dirclean:</span>
> -49:    rm -rf $(LIBFOO_DIR)
> -50:
> -<span id="ex2line51">51: #############################################################</span>
> -52: #
> -53: # Toplevel Makefile options
> -54: #
> -55: #############################################################
> -56: ifeq ($(BR2_PACKAGE_LIBFOO),y)
> -57: TARGETS+=libfoo
> -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
> -    <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
> -      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
> -      <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
> -      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
> -      <code>BUILD_DIR</code> which is created upon decompression of the tarball.
> -      </li>
> -
> -      <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
> -      the target filesystem.</li> </ul>
> -
> -    <p>Lines <a href="#ex2line13">13-14</a> define a target that downloads
> -    the tarball from the remote site to the download directory
> -    (<code>DL_DIR</code>).</p>
> -
> -    <p>Lines <a href="#ex2line16">16-18</a> define a target and associated
> -    rules that uncompress the downloaded tarball. As you can see, this
> -    target depends on the tarball file so that the previous target (lines
> -    <a href="#ex2line13">13-14</a>) is called before executing the rules of
> -    the current target. Uncompressing is followed by <i>touching</i> a
> -    hidden file to mark the software as having been uncompressed. This trick
> -    is used everywhere in a Buildroot Makefile to split steps (download,
> -    uncompress, configure, compile, install) while still having correct
> -    dependencies.</p>
> -
> -    <p>Lines <a href="#ex2line20">20-31</a> define a target and associated
> -    rules that configure the software. It depends on the previous target
> -    (the hidden <code>.source</code> file) so that we are sure the software
> -    has been uncompressed. In order to configure the package, it basically
> -    runs the well-known <code>./configure</code> script. As we may be doing
> -    cross-compilation, <code>target</code>, <code>host</code> and
> -    <code>build</code> arguments are given. The prefix is also set to
> -    <code>/usr</code>, not because the software will be installed in
> -    <code>/usr</code> on your host system, but because the software will 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).
> -    It basically runs <code>make</code> inside the source directory.</p>
> -
> -    <p>Lines <a href="#ex2line36">36-38</a> define a target and associated
> -    rules that install the software inside the target filesystem. They
> -    depend on the binary file in the source directory to make sure the
> -    software has been compiled. They use the <code>install-strip</code>
> -    target of the software <code>Makefile</code> by passing a
> -    <code>DESTDIR</code> argument so that the <code>Makefile</code> doesn't
> -    try to install the software in the host <code>/usr</code> but rather in
> -    the target <code>/usr</code>. After the installation, the
> -    <code>/usr/man </code> directory inside the target filesystem is removed
> -    to save space. </p>
> -
> -    <p>Line <a href="#ex2line40">40</a> defines the main target of the
> -    software — the one that will 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
> -    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
> -    from $(STAGING_DIR) and from $(TARGET_DIR).</p>
> -
> -    <p>Lines <a href="#ex2line48">48-49</a> define a simple target to
> -    completely remove the directory in which the software was uncompressed,
> -    configured and compiled. The <code>-dirclean</code> target MUST
> -    completely rm $(BUILD_DIR)/ package-version.</p>
> -
> -    <p>Lines <a href="#ex2line51">51-58</a> add the target <code>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,
> -    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
> -    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
> -    support is enabled.</p>
> -
> -    <p>Therefore, Buildroot defines two configuration options:</p>
> -
> -    <ul>
> -      <li><code>BR2_NEEDS_GETTEXT</code>, which is true as soon as the
> -      toolchain doesn't provide its own gettext implementation</li>
> -
> -      <li><code>BR2_NEEDS_GETTEXT_IF_LOCALE</code>, which is true if the
> -      toolchain doesn't provide its own gettext implementation and if locale
> -      support is enabled</li> </ul>
> -
> -    <p>Therefore, packages that 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>,
> -      if libintl is also needed</li>
> -
> -      <li>Use <code>$(if $(BR2_NEEDS_GETTEXT),gettext)</code> in the package
> -      <code>DEPENDENCIES</code> variable</li>
> -    </ol>
> -
> -    <p>Packages that need gettext only when locale support is enabled should:
> -    </p>
> -
> -    <ol>
> -      <li>Use
> -      <code>select BR2_PACKAGE_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
> -      the package <code>DEPENDENCIES</code> variable</li>
> -    </ol>
> -
> -    <h3>Conclusion</h3>
> -
> -    <p>As you can see, adding a software package to Buildroot is simply a
> -    matter of writing a Makefile using an  existing example and modifying it
> -    according to the compilation process required by the package.</p>
> -
> -    <p>If you package software that might be useful for other people, don't
> -    forget to send a patch to Buildroot developers!</p>
> -
> -    <h2 id="faq">Frequently asked questions</h2>
> -
> -    <ul>
> -      <li><a href="#faq-boot-hangs">The boot hangs
> -      after <code>Starting network...</code></a></li>
> -      <li><a href="#module-init-tools-doesnt-build">module-init-tools
> -      fails to build with <code>cannot find -lc</code></a></li>
> -    </ul>
> -
> -    <h3 id="faq-boot-hangs">The boot hangs after <code>Starting
> -    network...</code></h3>
> -
> -    <p>If the boot process seems to hang after the following messages
> -    (messages not necessarly exactly similar, depending on the list of
> -    packages selected):</p>
> -
> -    <pre>Freeing init memory: 3972K
> -Initializing random number generator... done.
> -Starting network...
> -Starting dropbear sshd: generating rsa key... generating dsa key... OK</pre>
> -
> -    <p>then it means that your system is running, but didn't start a
> -    shell on the serial console. In order to have the system start a
> -    shell on your serial console, you have to go in the Buildroot
> -    configuration, <code>Target options</code>, enable <code>Generic
> -    serial port config</code>, and select the serial port and speed
> -    you would like to use for the shell. This will automatically tune
> -    the <code>/etc/inittab</code> file of the generated system so that
> -    a shell starts on the correct serial port.</p>
> -
> -    <h3 id="module-init-tools-doesnt-build">module-init-tools
> -      fails to build with <code>cannot find -lc</code></h3>
> -
> -    <p>If the build of <i>module-init-tools</i> for the host fails
> -    with:</p>
> -
> -    <pre>/usr/bin/ld: cannot find -lc </pre>
> -
> -    <p>then probably you are running a Fedora (or similar)
> -    distribution, and you should install the <code>glibc-static</code>
> -    package. This is because the <i>module-init-tools</i> build
> -    process wants to link statically against the C library.</p>
> -
> -    <h2 id="links">Resources</h2>
> -
> -    <p>To learn more about Buildroot you can visit these websites:</p>
> -
> -    <ul>
> -      <li><a href="http://www.uclibc.org/">http://www.uclibc.org/</a></li>
> -      <li><a href="http://www.busybox.net/">http://www.busybox.net/</a></li>
> -    </ul>
> -  </div>
> -</body>
> -</html>

Acked-by: Thomas De Schampheleire <thomas.de.schampheleire at gmail.com>


More information about the buildroot mailing list