<li><a href="#using_toolchain">Using the uClibc toolchain
outside Buildroot</a></li>
<li><a href="#external_toolchain">Use an external toolchain</a></li>
- <li><a href="#downloaded_packages">Location of downloaded packages</a>
- </li>
- <li><a href="#add_software">Extending Buildroot with more
- Software</a></li>
+ <li><a href="#downloaded_packages">Location of downloaded packages</a></li>
+ <li><a href="#add_packages">Adding new packages to Buildroot</a></li>
<li><a href="#board_support">Creating your own board support</a></li>
<li><a href="#links">Resources</a></li>
</ul>
directory is <i>not</i> intended to be the root filesystem for
the target: it contains a lot of development files, unstripped
binaries and libraries that make it far too big for an embedded
- system.</li>
+ system. These development files are used to compile libraries
+ and applications for the target that depend on other
+ libraries.</li>
<li><code>target/</code> which contains <i>almost</i> the root
filesystem for the target: everything needed is present except
uniformely named and handled by the different packages, so some
understanding of the particular package is needed.</p>
- <p>For packages relying on the <i>autotools</i> Buildroot
- infrastructure (see <a href="#add_software">this section</a> for
- details), the following stamp files are relevent:</p>
+ <p>For packages relying on Buildroot packages infrastructures (see
+ <a href="#add_packages">this section</a> for details), the
+ following stamp files are relevent:</p>
<ul>
<p>For other packages, an analysis of the specific
<i>package.mk</i> file is needed. For example, the zlib Makefile
- looks like:</p>
+ used to look like this (before it was converted to the generic
+ package infrastructure):</p>
<pre>
$(ZLIB_DIR)/.configured: $(ZLIB_DIR)/.patched
you want to trigger only the recompilation, you need to remove
<code>output/build/zlib-version/libz.a</code>.</p>
+ <p>Note that most packages, if not all, will progressively be
+ ported over the generic or the autotools infrastructure, making it
+ much easier to rebuild individual packages.</p>
+
<h2><a name="buildroot_innards" id="buildroot_innards"></a>How Buildroot
works</h2>
<code>uClibc</code>). </p>
<p>There is basically one Makefile per software package, and they are named with
- the <code>.mk</code> extension. Makefiles are split into four
+ the <code>.mk</code> extension. Makefiles are split into three main
sections:</p>
<ul>
and <i>eglibc</i> for a wide range of architectures and has good
community support.</p>
- <h2><a name="add_software" id="add_software"></a>Extending Buildroot with
- more software</h2>
+ <h2><a name="add_packages" id="add_packages"></a>Adding new
+ packages to Buildroot</h2>
- <p>This section will only consider the case in which you want to
- add user-space software. </p>
+ <p>This section covers how new packages (userspace libraries or
+ applications) can be integrated into Buildroot. It also allows to
+ understand how existing packages are integrated, which is needed
+ to fix issues or tune their configuration.</p>
- <h3>Package directory</h3>
+ <ul>
+ <li><a href="#package-directory">Package directory</a></li>
+ <li><a href="#config-in-file"><code>Config.in</code> file</a></li>
+ <li><a href="#mk-file">The <code>.mk</code> file</a>
+ <ul>
+ <li><a href="#generic-tutorial">Makefile for generic
+ packages : tutorial</a></li>
+ <li><a href="#generic-reference">Makefile for
+ generic packages : reference</a></li>
+ <li><a href="#autotools-tutorial">Makefile for autotools-based
+ packages : tutorial</a></li>
+ <li><a href="#autotools-reference">Makefile for autotools-based
+ packages : reference</a></li>
+ <li><a href="#manual-tutorial">Manual Makefile : tutorial</a></li>
+ </ul>
+ </li>
+ </ul>
+
+ <h3><a name="package-directory"></a>Package directory</h3>
<p>First of all, create a directory under the <code>package</code>
directory for your software, for example <code>foo</code>. </p>
- <h3><code>Config.in</code> file</h3>
+ <p>Some packages have been grouped by topic in a sub-directory:
+ <code>multimedia</code>, <code>java</code>,
+ <code>databases</code>, <code>editors</code>, <code>x11r7</code>,
+ <code>games</code>. If your package fits in one of these
+ categories, then create your package directory in these.</p>
+
+ <h3><a name="config-in-file"></a><code>Config.in</code> file</h3>
<p>Then, create a file named <code>Config.in</code>. This file
will contain the option descriptions related to our
- <code>foo</code> software that will be used and displayed in the
- configuration tool. It should basically contain:</p>
+ <code>libfoo</code> software that will be used and displayed in the
+ configuration tool. It should basically contain :</p>
<pre>
-config BR2_PACKAGE_FOO
- bool "foo"
+config BR2_PACKAGE_LIBFOO
+ bool "libfoo"
help
- This is a comment that explains what foo is.
+ This is a comment that explains what libfoo is.
- http://foosoftware.org/foo/
+ http://foosoftware.org/libfoo/
</pre>
<p>Of course, you can add other options to configure particular
- things in your software. </p>
- <p>Finally you have to add your new <code>foo/Config.in</code> to
- <code>package/Config.in</code>. The files included there are
- <em>sorted alphabetically</em> per category and are <em>NOT</em>
- supposed to contain anything but the <em>bare</em> name of the package.</p>
+ 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/procps/Config.in"
+source "package/libfoo/Config.in"
</pre>
- <p><strong>Note:</strong><br>
- Generally all packages should live <em>directly</em> in the
- <code>package</code> directory to make it easier to find them.
- </p>
- <h3>The real Makefile</h3>
+
+ <h3><a name="mk-file"></a>The <code>.mk</code> file</h3>
<p>Finally, here's the hardest part. Create a file named
- <code>foo.mk</code>. It will contain the Makefile rules that
- are in charge of downloading, configuring, compiling and installing
- the software.</p>
+ <code>foo.mk</code>. It describes how the package should be
+ downloaded, configured, built, installed, etc.</p>
- <p>Two types of Makefiles can be written :</p>
+ <p>Depending on the package type, the <code>.mk</code> file must be
+ written in a different way, using different infrastructures:</p>
<ul>
- <li>Makefiles for autotools-based (autoconf, automake, etc.)
- software are very easy to write thanks to the infrastructure
- available in <code>package/Makefile.autotools.in</code>.</li>
- <li>Makefiles for other types of packages are a little bit more
- complex to write.</li>
+
+ <li>Makefiles for generic packages (not using autotools), based
+ on an infrastructure similar to the one used for autotools-based
+ packages, but which requires a little more work from the
+ developer : specify what should be done at for the configuration,
+ compilation, installation and cleanup of the package. This
+ infrastructure must be used for all packages that do not use the
+ autotools as their build system. In the future, other specialized
+ infrastructures might be written for other build systems.<br/>We
+ cover them through a <a
+ href="#generic-tutorial">tutorial</a> and a <a
+ href="#generic-reference">reference</a>.</li>
+
+ <li>Makefiles for autotools-based (autoconf, automake, etc.)
+ softwares. We provide a dedicated infrastructure for such
+ packages, since autotools is a very common build system. This
+ infrastructure <i>must</i> be used for new packages that rely on
+ the autotools as their build system.<br/>We cover them through a
+ <a href="#autotools-tutorial">tutorial</a> and a <a
+ href="#autotools-reference">reference</a>.</li>
+
+ <li>Manual Makefiles. These are currently obsolete and no new
+ manual Makefiles should be added. However, since there are still
+ many of them in the tree and because the , we keep them documented in a <a
+ href="#manual-tutorial">tutorial</a>.</li>
+
</ul>
- <p>First, let's see how to write a Makefile for an
- autotools-based package, with an example :</p>
+ <h4><a name="generic-tutorial"></a>Makefile for generic packages :
+ tutorial</h4>
+
+ <pre><tt><span style="color: #000000">01:</span> <span style="font-style: italic"><span style="color: #9A1900">#############################################################</span></span>
+<span style="color: #000000">02:</span> <span style="font-style: italic"><span style="color: #9A1900">#</span></span>
+<span style="color: #000000">03:</span> <span style="font-style: italic"><span style="color: #9A1900"># libfoo</span></span>
+<span style="color: #000000">04:</span> <span style="font-style: italic"><span style="color: #9A1900">#</span></span>
+<span style="color: #000000">05:</span> <span style="font-style: italic"><span style="color: #9A1900">#############################################################</span></span>
+<span style="color: #000000">06:</span> <span style="color: #990000">LIBFOO_VERSION:=</span>1.0
+<span style="color: #000000">07:</span> <span style="color: #990000">LIBFOO_SOURCE:=</span>libfoo-<span style="color: #009900">$(LIBFOO_VERSION)</span>.tar.gz
+<span style="color: #000000">08:</span> <span style="color: #990000">LIBFOO_SITE:=</span>http<span style="color: #990000">:</span>//www.foosoftware.org/download
+<span style="color: #000000">09:</span> <span style="color: #009900">LIBFOO_INSTALL_STAGING=</span>YES
+<span style="color: #000000">10:</span> <span style="color: #009900">LIBFOO_DEPENDENCIES =</span> host-libaaa libbbb
+<span style="color: #000000">11:</span>
+<span style="color: #000000">12:</span> define LIBFOO_BUILD_CMDS
+<span style="color: #000000">13:</span> <span style="color: #009900">$(MAKE)</span> <span style="color: #009900">CC</span><span style="color: #990000">=</span><span style="color: #009900">$(TARGET_CC)</span> <span style="color: #009900">LD</span><span style="color: #990000">=</span><span style="color: #009900">$(TARGET_LD)</span> -C <span style="color: #009900">$(@D)</span> all
+<span style="color: #000000">14:</span> endef
+<span style="color: #000000">15:</span>
+<span style="color: #000000">16:</span> define LIBFOO_INSTALL_STAGING_CMDS
+<span style="color: #000000">17:</span> <span style="color: #009900">$(INSTALL)</span> -D <span style="color: #009900">$(@D)</span>/libfoo.a <span style="color: #009900">$(STAGING_DIR)</span>/usr/lib/libfoo.a
+<span style="color: #000000">18:</span> <span style="color: #009900">$(INSTALL)</span> -D <span style="color: #009900">$(@D)</span>/foo.h <span style="color: #009900">$(STAGING_DIR)</span>/usr/include/foo.h
+<span style="color: #000000">19:</span> cp -dpf <span style="color: #009900">$(@D)</span>/libfoo.so<span style="color: #990000">*</span> <span style="color: #009900">$(STAGING_DIR)</span>/usr/lib
+<span style="color: #000000">20:</span> endef
+<span style="color: #000000">21:</span>
+<span style="color: #000000">22:</span> define LIBFOO_INSTALL_TARGET_CMDS
+<span style="color: #000000">23:</span> cp -dpf <span style="color: #009900">$(@D)</span>/libfoo.so<span style="color: #990000">*</span> <span style="color: #009900">$(TARGET_DIR)</span>/usr/lib
+<span style="color: #000000">24:</span> -<span style="color: #009900">$(STRIPCMP)</span> <span style="color: #009900">$(STRIP_STRIP_UNNEEDED)</span> <span style="color: #009900">$(TARGET_DIR)</span>/isr/lib/libfoo.so<span style="color: #990000">*</span>
+<span style="color: #000000">25:</span> endef
+<span style="color: #000000">26:</span>
+<span style="color: #000000">27:</span> <span style="color: #009900">$(</span><span style="font-weight: bold"><span style="color: #0000FF">eval</span></span> <span style="color: #009900">$(</span>call GENTARGETS<span style="color: #990000">,</span>package<span style="color: #990000">,</span>libfoo<span style="color: #990000">))</span></tt></pre>
+
+ <p>The Makefile begins on line 6 to 8 by metadata informations: the
+ version of the package (<code>LIBFOO_VERSION</code>), the name of
+ the tarball containing the package (<code>LIBFOO_SOURCE</code>) and
+ the Internet location at which the tarball can be downloaded
+ (<code>LIBFOO_SITE</code>). All variables must start with the same
+ prefix, <code>LIBFOO_</code> in this case. This prefix is always
+ the uppercased version of the package name (see below to understand
+ where the package name is defined).</p>
+
+ <p>On line 9, we specify that this package wants to install
+ something to the staging space. This is often needed for libraries
+ since they must install header files and other development files in
+ the staging space. This will ensure that the commands listed in the
+ <code>LIBFOO_INSTALL_STAGING_CMDS</code> variable will be
+ executed.</p>
+
+ <p>On line 10, we specify the list of dependencies this package
+ relies on. These dependencies are listed in terms of lower-case
+ package names, which can be packages for the target (without the
+ <code>host-</code> prefix) or packages for the host (with the
+ <code>host-</code>) prefix). Buildroot will ensure that all these
+ packages are built and installed <i>before</i> the current package
+ starts its configuration.</p>
+
+ <p>The rest of the Makefile defines what should be done at the
+ different steps of the package configuration, compilation and
+ installation. <code>LIBFOO_BUILD_CMDS</code> tells what steps
+ should be performed to build the
+ package. <code>LIBFOO_INSTALL_STAGING_CMDS</code> tells what steps
+ should be performed to install the package in the staging
+ space. <code>LIBFOO_INSTALL_TARGET_CMDS</code> tells what steps
+ should be performed to install the package in the target space.</p>
+
+ <p>All these steps rely on the <code>$(@D)</code> variable, which
+ contains the directory where the source code of the package has
+ been extracted.</p>
+
+ <p>Finally, on line 27, we call the <code>GENTARGETS</code> which
+ generates, according to the variables defined previously, all the
+ Makefile code necessary to make your package working.</p>
+
+ <h4><a name="generic-reference"></a>Makefile for generic packages :
+ reference</h4>
+
+ <p>The <code>GENTARGETS</code> macro takes three arguments:</p>
+
+ <ul>
+
+ <li>The first argument is the package directory prefix. If your
+ package is in <code>package/libfoo</code>, then the directory
+ prefix is <code>package</code>. If your package is in
+ <code>package/editors/foo</code>, then the directory prefix must
+ be <code>package/editors</code>.</li>
+
+ <li>The second argument is the lower-cased package name. It must
+ match the prefix of the variables in the <code>.mk</code> file
+ and must match the configuration option name in the
+ <code>Config.in</code> file. For example, if the package name is
+ <code>libfoo</code>, so the variables in the <code>.mk</code>
+ must start with <code>LIBFOO_</code> and the configuration option
+ in the <code>Config.in</code> file must be
+ <code>BR2_PACKAGE_LIBFOO</code>.</li>
+
+ <li>The third argument is optional. It can be used to tell if the
+ package if a target package (cross-compiled for the target) or a
+ host package (natively compiled for the host). If unspecified, it
+ is assumed that it is a target package. See below for
+ details.</li>
+
+ </ul>
+
+ <p>For a given package, in a single <code>.mk</code> file, it is
+ possible to call GENTARGETS twice, once to create the rules to
+ generate a target package and once to create the rules to generate
+ a host package:</p>
+
+<pre>
+$(eval $(call GENTARGETS,package,libfoo))
+$(eval $(call GENTARGETS,package,libfoo,host))
+</pre>
+
+ <p>This might be useful if the compilation of the target package
+ requires some tools to be installed on the host. If the package
+ name is <code>libfoo</code>, then the name of the package for the
+ target is also <code>libfoo</code>, while the name of the package
+ for the host is <code>host-libfoo</code>. These names should be
+ used in the DEPENDENCIES variables of other packages if they depend
+ on <code>libfoo</code> or <code>host-libfoo</code>.</p>
+
+ <p>The call to the <code>GENTARGETS</code> macro <b>must</b> be at
+ the end of the <code>.mk</code> file, after all variable
+ definitions.</p>
+
+ <p>For the target package, the <code>GENTARGETS</code> uses the
+ variables defined by the .mk file and prefixed by the uppercased
+ package name: <code>LIBFOO_*</code>. For target package, it uses
+ the <code>HOST_LIBFOO_*</code>. For <i>some</i> variables, if the
+ <code>HOST_LIBFOO_</code> prefixed variable doesn't exist, the
+ package infrastructure uses the corresponding variable prefixed by
+ <code>LIBFOO_</code>. This is done for variables that are likely to
+ have the same value for both the target and host packages. See
+ below for details.</p>
+
+ <p>The list of variables that can be set in a <code>.mk</code> file
+ to give metadata informations is (assuming the package name is
+ <code>libfoo</code>) :</p>
+
+ <ul>
+
+ <li><code>LIBFOO_VERSION</code>, mandatory, must contain the
+ version of the package. Note that if
+ <code>HOST_LIBFOO_VERSION</code> doesn't exist, it is assumed to
+ be the same as <code>LIBFOO_VERSION</code>.<br/>Example:
+ <code>LIBFOO_VERSION=0.1.2</code></li>
+
+ <li><code>LIBFOO_SOURCE</code> may contain the name of the
+ tarball of the package. If <code>HOST_LIBFOO_SOURCE</code> is not
+ specified, it defaults to <code>LIBFOO_VERSION</code>. If none
+ are specified, then the value is assumed to be
+ <code>packagename-$(LIBFOO_VERSION).tar.gz</code>.<br/>Example:
+ <code>LIBFOO_SOURCE =
+ foobar-$(LIBFOO_VERSION).tar.bz2</code></li>
+
+ <li><code>LIBFOO_PATCH</code> may contain the name of a patch,
+ that will be downloaded from the same location as the tarball
+ indicated in <code>LIBFOO_SOURCE</code>. If
+ <code>HOST_LIBFOO_PATCH</code> is not specified, it defaults to
+ <code>LIBFOO_PATCH</code>. Also note that another mechanism is
+ available to patch a package: all files of the form
+ <code>packagename-packageversion-description.patch</code> present
+ in the package directory inside Buildroot will be applied to the
+ package after extraction.</li>
+
+ <li><code>LIBFOO_SITE</code> may contain the Internet location of
+ the tarball of the package. If <code>HOST_LIBFOO_SITE</code> is
+ not specified, it defaults to <code>LIBFOO_SITE</code>. If none
+ are specified, then the location is assumed to be
+ <code>http://$$(BR2_SOURCEFORGE_MIRROR).dl.sourceforge.net/sourceforge/packagename</code>.<br/>Example:
+ <code>LIBFOO_SITE=http://www.foosoftware.org/libfoo</code>.</li>
+
+ <li><code>LIBFOO_DEPENDENCIES</code> lists the dependencies (in
+ terms of package name) that are required for the current target
+ package to compile. These dependencies are guaranteed to be
+ compiled and installed before the configuration of the current
+ package starts. In a similar way,
+ <code>HOST_LIBFOO_DEPENDENCIES</code> lists the dependency for
+ the current host package.</li>
+
+ <li><code>LIBFOO_INSTALL_STAGING</code> can be set to
+ <code>YES</code> or <code>NO</code> (default). If set to
+ <code>YES</code>, then the commands in the
+ <code>LIBFOO_INSTALL_STAGING_CMDS</code> variables are executed
+ to install the package into the staging directory.</p>
+
+ <li><code>LIBFOO_INSTALL_TARGET</code> can be set to
+ <code>YES</code> (default) or <code>NO</code>. If set to
+ <code>YES</code>, then the commands in the
+ <code>LIBFOO_INSTALL_TARGET_CMDS</code> variables are executed
+ to install the package into the target directory.</p>
+
+ </ul>
+
+ <p>The recommended way to define these variables is to use the
+ following syntax:</p>
<pre>
- <a name="ex1line1" id="ex1line1">1</a> #############################################################
- <a name="ex1line2" id="ex1line2">2</a> #
- <a name="ex1line3" id="ex1line3">3</a> # foo
- <a name="ex1line4" id="ex1line4">4</a> #
- <a name="ex1line5" id="ex1line5">5</a> #############################################################
- <a name="ex1line6" id="ex1line6">6</a> FOO_VERSION:=1.0
- <a name="ex1line7" id="ex1line7">7</a> FOO_SOURCE:=foo-$(FOO_VERSION).tar.gz
- <a name="ex1line8" id="ex1line8">8</a> FOO_SITE:=http://www.foosoftware.org/downloads
- <a name="ex1line9" id="ex1line9">9</a> FOO_INSTALL_STAGING = YES
- <a name="ex1line10" id="ex1line10">10</a> FOO_INSTALL_TARGET = YES
- <a name="ex1line11" id="ex1line11">11</a> FOO_CONF_OPT = --enable-shared
- <a name="ex1line12" id="ex1line12">12</a> FOO_DEPENDENCIES = libglib2 host-pkgconfig
- <a name="ex1line13" id="ex1line13">13</a> $(eval $(call AUTOTARGETS,package,foo))
+LIBFOO_VERSION=2.32
</pre>
- <p>On <a href="#ex1line6">line 6</a>, we declare the version of
- the package. On lines <a href="#ex1line7">7</a> and <a
- href="#ex1line8">8</a>, we declare the name of the tarball and the
- location of the tarball on the web. Buildroot will automatically
- download the tarball from this location.</p>
-
- <p>On <a href="#ex1line9">line 9</a>, we tell Buildroot to install
- the application to the staging directory. The staging directory,
- located in <code>output/staging/</code> is the directory
- where all the packages are installed, including their
- documentation, etc. By default, packages are installed in this
+ <p>Now, the variables that define what should be performed at the
+ different steps of the build process.</p>
+
+ <ul>
+
+ <li><code>LIBFOO_CONFIGURE_CMDS</code>, used to list the
+ actions to be performed to configure the package before its
+ compilation</li>
+
+ <li><code>LIBFOO_BUILD_CMDS</code>, used to list the actions to
+ be performed to compile the package</li>
+
+ <li><code>HOST_LIBFOO_INSTALL_CMDS</code>, used to list the
+ actions to be performed to install the package, when the
+ package is a host package. The package must install its files
+ to the directory given by <code>$(HOST_DIR)</code>. All files,
+ including development files such as headers should be
+ installed, since other packages might be compiled on top of
+ this package.</li>
+
+ <li><code>LIBFOO_INSTALL_TARGET_CMDS</code>, used to list the
+ actions to be performed to install the package to the target
+ directory, when the package is a target package. The package
+ must install its files to the directory given by
+ <code>$(TARGET_DIR)</code>. Only the files required for
+ <i>execution</i> of the package should be installed. Header
+ files and documentation should not be installed.</li>
+
+ <li><code>LIBFOO_INSTALL_STAGING_CMDS</code>, used to list the
+ actions to be performed to install the package to the staging
+ directory, when the package is a target package. The package
+ must install its files to the directory given by
+ <code>$(STAGING_DIR)</code>. All development files should be
+ installed, since they might be needed to compile other
+ packages.</li>
+
+ <li><code>LIBFOO_CLEAN_CMDS</code>, used to list the actions to
+ perform to clean up the build directory of the package.</li>
+
+ <li><code>LIBFOO_UNINSTALL_TARGET_CMDS</code>, used to list the
+ actions to uninstall the package from the target directory
+ <code>$(TARGET_DIR)</code></li>
+
+ <li><code>LIBFOO_UNINSTALL_STAGING_CMDS</code></li>, used to
+ list the actions to uninstall the package from the staging
+ directory <code>$(STAGING_DIR)</code>.</li>
+
+ </ul>
+
+ <p>The preferred way to define these variables is:</p>
+
+<pre>
+define LIBFOO_CONFIGURE_CMDS
+ action 1
+ action 2
+ action 3
+endef</pre>
+
+ <p>In the action definitions, you can use the following
+ variables:</p>
+
+ <ul>
+
+ <li><code>$(@D)</code>, which contains the directory in which
+ the package source code has been uncompressed.</li>
+
+ <li><code>$(TARGET_CC)</code>, <code>$(TARGET_LD)</code>,
+ etc. to get the target cross-compilation utilities</li>
+
+ <li><code>$(TARGET_CROSS)</code> to get the cross-compilation
+ toolchain prefix</li>
+
+ <li>Of course the <code>$(HOST_DIR)</code>,
+ <code>$(STAGING_DIR)</code> and <code>$(TARGET_DIR)</code>
+ variables to install the packages properly.</li>
+
+ </ul>
+
+
+ <p>The last feature of the generic infrastructure is the ability
+ to add hook more actions after existing steps. These hooks aren't
+ really useful for generic packages, since the <code>.mk</code>
+ file already has full control over the actions performed in each
+ step of the package construction. The hooks are more useful for
+ packages using the autotools infrastructure described below. But
+ since they are provided by the generic infrastructure, they are
+ documented here.</p>
+
+ <p>The following hook points are available:</p>
+
+ <ul>
+ <li><code>LIBFOO_POST_PATCH_HOOKS</code></li>
+ <li><code>LIBFOO_POST_CONFIGURE_HOOKS</code></li>
+ <li><code>LIBFOO_POST_BUILD_HOOKS</code></li>
+ <li><code>LIBFOO_POST_INSTALL_HOOKS</code> (for host packages only)</li>
+ <li><code>LIBFOO_POST_INSTALL_STAGING_HOOKS</code> (for target packages only)</li>
+ <li><code>LIBFOO_POST_INSTALL_TARGET_HOOKS</code> (for target packages only)</li>
+ </ul>
+
+ <p>This variables are <i>lists</i> of variable names containing
+ actions to be performed at this hook point. This allows several
+ hooks to be registered at a given hook point. Here is an
+ example:</p>
+
+ <pre>
+define LIBFOO_POST_PATCH_FIXUP
+ action1
+ action2
+endef
+
+LIBFOO_POST_PATCH_HOOKS += LIBFOO_POST_PATCH_FIXUP
+</pre>
+
+ <h4><a name="autotools-tutorial"></a>Makefile for autotools-based
+ packages : tutorial</h4>
+
+ <p>First, let's see how to write a <code>.mk</code> file for an
+ autotools-based package, with an example :</p>
+
+<pre><tt><span style="color: #000000">01:</span> <span style="font-style: italic"><span style="color: #9A1900">#############################################################</span></span>
+<span style="color: #000000">02:</span> <span style="font-style: italic"><span style="color: #9A1900">#</span></span>
+<span style="color: #000000">03:</span> <span style="font-style: italic"><span style="color: #9A1900"># foo</span></span>
+<span style="color: #000000">04:</span> <span style="font-style: italic"><span style="color: #9A1900">#</span></span>
+<span style="color: #000000">05:</span> <span style="font-style: italic"><span style="color: #9A1900">#############################################################</span></span>
+<span style="color: #000000">06:</span>
+<span style="color: #000000">07:</span> <span style="color: #990000">FOO_VERSION:=</span>1.0
+<span style="color: #000000">08:</span> <span style="color: #990000">FOO_SOURCE:=</span>foo-<span style="color: #009900">$(FOO_VERSION)</span>.tar.gz
+<span style="color: #000000">09:</span> <span style="color: #990000">FOO_SITE:=</span>http<span style="color: #990000">:</span>//www.foosoftware.org/downloads
+<span style="color: #000000">10:</span> <span style="color: #009900">FOO_INSTALL_STAGING =</span> YES
+<span style="color: #000000">11:</span> <span style="color: #009900">FOO_INSTALL_TARGET =</span> YES
+<span style="color: #000000">12:</span> <span style="color: #009900">FOO_CONF_OPT =</span> --enable-shared
+<span style="color: #000000">13:</span> <span style="color: #009900">FOO_DEPENDENCIES =</span> libglib2 host-pkg-config
+<span style="color: #000000">14:</span>
+<span style="color: #000000">15:</span> <span style="color: #009900">$(</span><span style="font-weight: bold"><span style="color: #0000FF">eval</span></span> <span style="color: #009900">$(</span>call AUTOTARGETS<span style="color: #990000">,</span>package<span style="color: #990000">,</span>foo<span style="color: #990000">))</span></tt></pre>
+
+ <p>On line 7, we declare the version of the package. On line 8 and
+ 9, we declare the name of the tarball and the location of the
+ tarball on the Web. Buildroot will automatically download the
+ tarball from this location.</p>
+
+ <p>On line 10, we tell Buildroot to install the package to the
+ staging directory. The staging directory, located in
+ <code>output/staging/</code> is the directory where all the
+ packages are installed, including their development files, etc. By
+ default, packages are not installed to the staging directory,
+ since usually, only libraries need to be installed in the staging
+ directory: their development files are needed to compile other
+ libraries or applications depending on them. Also by default, when
+ staging installation is enabled, packages are installed in this
location using the <code>make install</code> command.</p>
- <p>On <a href="#ex1line10">line 10</a>, we tell Buildroot to also
- install the application to the target directory. This directory
- contains what will become the root filesystem running on the
- target. Usually, we try to install stripped binaries and
- to not install the documentation. By default, packages are
+ <p>On line 11, we tell Buildroot to also install the package to
+ the target directory. This directory contains what will become the
+ root filesystem running on the target. Usually, we try not to
+ install the documentation and to install stripped versions of the
+ binary. By default, target installation is enabled, so in fact,
+ this line is not strictly necessary. Also by default, packages are
installed in this location using the <code>make
install-strip</code> command.</p>
- <p>On <a href="#ex1line11">line 11</a>, we tell Buildroot to pass
- a custom configure option to the
- <code>./configure</code> script when configuring the
- the package.</p>
+ <p>On line 12, we tell Buildroot to pass a custom configure
+ option, that will be passed to the <code>./configure</code> script
+ before configuring and building the package.</p>
+
+ <p>On line 13, we declare our dependencies, so that they are built
+ before the build process of our package starts.</p>
+
+ <p>Finally, on line line 14, we invoke the
+ <code>AUTOTARGETS</code> macro that generates all the Makefile
+ rules that actually allows the package to be built.</p>
+
+ <h4><a name="autotools-reference"></a>Makefile for autotools
+ packages : reference</h4>
+
+ <p>The main macro of the autotools package infrastructure is
+ <code>AUTOTARGETS</code>. It has the same number of arguments and
+ the same semantic as the <code>GENTARGETS</code> macro, which is
+ the main macro of the generic package infrastructure. For
+ autotools packages, the ability to have target and host packages
+ is also available (and is actually widely used).</p>
+
+ <p>Just like the generic infrastructure, the autotools
+ infrastructure works by defining a number of variables before
+ calling the <code>AUTOTARGETS</code> macro.</p>
+
+ <p>First, all the package meta-information variables that exist in
+ the generic infrastructure also exist in the autotools
+ infrastructure: <code>LIBFOO_VERSION</code>,
+ <code>LIBFOO_SOURCE</code>, <code>LIBFOO_PATCH</code>,
+ <code>LIBFOO_SITE</code>, <code>LIBFOO_SUBDIR</code>,
+ <code>LIBFOO_DEPENDENCIES</code>,
+ <code>LIBFOO_INSTALL_STAGING</code>,
+ <code>LIBFOO_INSTALL_TARGET</code>.</p>
+
+ <p>A few additional variables, specific to the autotools
+ infrastructure, can also be defined. Many of them are only useful
+ in very specific cases, typical packages will therefore only use a
+ few of them.</p>
+
+ <ul>
+
+ <li><code>LIBFOO_SUBDIR</code> may contain the name of a
+ subdirectory inside the package that contains the configure
+ script. This is useful, if for example, the main configure
+ script is not at the root of the tree extracted by the
+ tarball. If <code>HOST_LIBFOO_SUBDIR</code> is not specified, it
+ defaults to <code>LIBFOO_SUBDIR</code>.</li>
+
+ <li><code>LIBFOO_CONF_ENV</code>, to specify additional
+ environment variables to pass to the configure script. By
+ default, empty.</li>
+
+ <li><code>LIBFOO_CONF_OPT</code>, to specify additional
+ configure options to pass to the configure script. By default,
+ empty.</li>
+
+ <li><code>LIBFOO_MAKE</code>, to specify an
+ alternate <code>make</code> command. This is typically useful
+ when parallel make it enabled in the configuration
+ (using <code>BR2_JLEVEL</code>) but that this feature should be
+ disabled for the given package, for one reason or another. By
+ default, set to <code>$(MAKE)</code>. If parallel building is
+ not supported by the package, then it should
+ do <code>LIBFOO_MAKE=$(MAKE1)</code>.</li>
+
+ <li><code>LIBFOO_MAKE_ENV</code>, to specify additional
+ environment variables to pass to make in the build step. These
+ are passed before the <code>make</code> command. By default,
+ empty.</li>
+
+ <li><code>LIBFOO_MAKE_OPT</code>, to specify additional
+ variables to pass to make in the build step. These are passed
+ after the <code>make</code> command. By default, empty.</li>
+
+ <li><code>LIBFOO_AUTORECONF</code>, tells whether the package
+ should be autoreconfigured or not (i.e, if the configure script
+ and Makefile.in files should be re-generated by re-running
+ autoconf, automake, libtool, etc.). Valid values
+ are <code>YES</code> and <code>NO</code>. By default, the value
+ is <code>NO</code></li>
+
+ <li><code>LIBFOO_AUTORECONF_OPT</code> to specify additional
+ options passed to the <i>autoreconf</i> program
+ if <code>LIBFOO_AUTORECONF=YES</code>. By default, empty.</li>
+
+ <li><code>LIBFOO_LIBTOOL_PATCH</code> tells whether the
+ Buildroot patch to fix libtool cross-compilation issues should
+ be applied or not. Valid values are <code>YES</code>
+ and <code>NO</code>. By default, the value
+ is <code>YES</code></li>
+
+ <li><code>LIBFOO_USE_CONFIG_CACHE</code> tells whether the
+ configure script should really on a cache file that caches test
+ results from previous configure script. Usually, this variable
+ should be left to its default value. Only for specific packages
+ having issues with the configure cache can set this variable to
+ the <code>NO</code> value (but this is more a work-around than a
+ really fix)</li>
+
+ <li><code>LIBFOO_INSTALL_STAGING_OPT</code> contains the make
+ options used to install the package to the staging directory. By
+ default, the value is <code>DESTDIR=$$(STAGING_DIR)
+ install</code>, which is correct for most autotools packages. It
+ is still possible to override it.</li>
+
+ <li><code>LIBFOO_INSTALL_TARGET_OPT</code> contains the make
+ options used to install the package to the target directory. By
+ default, the value is <code>DESTDIR=$$(TARGET_DIR)
+ install-strip</code> if <code>BR2_ENABLE_DEBUG</code> is not
+ set, and <code>DESTDIR=$$(TARGET_DIR) install-exec</code>
+ if <code>BR2_ENABLE_DEBUG</code> is set. These default values
+ are correct for most autotools packages, but it is still
+ possible to override them if needed.</li>
+
+ <li><code>LIBFOO_CLEAN_OPT</code> contains the make options used
+ to clean the package. By default, the value
+ is <code>clean</code>.</li>
+
+ <li><code>LIBFOO_UNINSTALL_STAGING_OPT</code>, contains the make
+ options used to uninstall the package from the staging
+ directory. By default, the value is
+ <code>DESTDIR=$$(STAGING_DIR) uninstall</code>.</li>
+
+ <li><code>LIBFOO_UNINSTALL_TARGET_OPT</code>, contains the make
+ options used to uninstall the package from the target
+ directory. By default, the value is
+ <code>DESTDIR=$$(TARGET_DIR) uninstall</code>.</li>
+
+ </ul>
- <p>On <a href="#ex1line12">line 12</a>, we declare our
- dependencies so that they are built before the build process of
- our package starts.</p>
+ <p>With the autotools infrastructure, all the steps required to
+ build and install the packages are already defined, and they
+ generally work well for most autotools-based packages. However,
+ when required, it is still possible to customize what is done in
+ particular step:</p>
- <p>Finally, on line <a href="#ex1line13">line 13</a>, we invoke
- the <code>package/Makefile.autotools.in</code> magic to get things
- working.</p>
+ <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>
- <p>For more details about the available variables and options, see
- the comment at the top of
- <code>package/Makefile.autotools.in</code> and the examples in all
- the available packages.</p>
+ <li>By overriding one of the steps. For example, even if the
+ autotools infrastructure is used, if the package
+ <code>.mk</code> defines its own
+ <code>LIBFOO_CONFIGURE_CMDS</code> variable, it will be used
+ instead of the default autotools one. However, using this method
+ should be restricted to very specific cases. Do not use it in
+ the general case.</li>
+
+ </ul>
- <p>The second solution, suitable for every type of package, looks
- like this :</p>
+ <h4><a name="manual-tutorial"></a>Manual Makefile : tutorial</h4>
+ <p><b>NOTE: new manual makefiles should not be created, and
+ existing manual makefiles should be converted either to the
+ generic infrastructure or the autotools infrastructure. This
+ section is only kept to document the existing manual makefiles and
+ help understanding how they work.</b></p>
<pre>
<a name="ex2line1" id="ex2line1">1</a> #############################################################
projects / buildroot.git / commitdiff