+++ /dev/null
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-
-<html xmlns="http://www.w3.org/1999/xhtml">
-<head>
- <title>Buildroot - Usage and documentation</title>
- <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
- <link rel="stylesheet" type="text/css" href="stylesheet.css" />
-</head>
-
-<body>
- <div class="main">
- <div class="titre">
- <h1>Buildroot</h1>
- </div>
-
- <p>Usage and documentation by Thomas Petazzoni. Contributions from
- Karsten Kruse, Ned Ludd, Martin Herren.</p>
-
- <p><small>Last modification : $Id: buildroot-documentation.html,v 1.2 2004/12/28 19:15:20 andersen Exp $</small></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 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="#buildroot_innards">How Buildroot works</a></li>
- <li><a href="#using_toolchain">Using the uClibc toolchain</a></li>
- <li><a href="#toolchain_standalone">Using the uClibc toolchain
- outside of Buildroot</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="#links">Ressources</a></li>
- </ul>
-
- <h2><a name="about" id="about"></a>About Buildroot</h2>
-
- <p>Buildroot is a set of Makefiles and patches that allows to easily
- generate both a cross-compilation toolchain and a root filesystem for your
- target. The cross-compilation toolchain uses uClibc (<a href=
- "http://www.uclibc.org/">http://www.uclibc.org/</a>), a tiny C standard
- library.</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 have on his PC. It can be PowerPC
- processors, MIPS processors, ARM processors, etc.</p>
-
- <p>A compilation toolchain is the set of tools that allows 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 application that
- runs on your system. If you're using a PC, your compilation
- toolchain runs on an x86 processor and generates code for a x86
- processor. Under most Linux systems, the compilation toolchain
- uses the GNU libc as C standard library. This compilation
- toolchain is called the "host compilation toolchain", and more
- generally, 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.</p>
-
- <p>As said above, the compilation toolchain that comes with your system
- runs and generates code for the processor of your host system. As your
- embedded system has a different processor, you need a cross-compilation
- toolchain: it's a compilation toolchain that runs on your host system but
- that 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 of 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 a x86 processor, you might interested
- in Buildroot, for two reasons:</p>
-
- <ul>
- <li>The compilation toolchain of 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 it for
- you.</li>
-
- <li>Buildroot automates the building of a root filesystem with all needed
- tools like busybox. It 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>, uClibc and all the tools by hand.
- Of course, doing so is possible. But dealing with all configure options,
- with all problems of every <code>gcc</code> or <code>binutils</code>
- version it 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>
-
- <h2><a name="download" id="download"></a>Obtaining Buildroot</h2>
-
- <p>Buildroot is available as daily CVS snapshots or directly using
- CVS.</p>
-
- <p>The latest snapshot is always available at <a
- href="http://uclibc.org/downloads/snapshots/buildroot-snapshot.tar.bz2">http://uclibc.org/downloads/snapshots/buildroot-snapshot.tar.bz2</a>,
- and previous snapshots are also available at <a
- href="http://uclibc.org/downloads/snapshots/">http://uclibc.org/downloads/snapshots/</a>.</p>
-
- <p>To download Buildroot using CVS, you can simply follow
- the rules described on the "Accessing CVS"-page (<a href=
- "http://www.uclibc.org/cvs_anon.html">http://www.uclibc.org/cvs_anon.html</a>)
- of the uClibc website (<a href=
- "http://www.uclibc.org">http://www.uclibc.org</a>), and download the
- <code>buildroot</code> CVS module. For the impatient, here's a quick
- recipe:</p>
-
- <pre>
- $ cvs -d:pserver:anonymous@uclibc.org:/var/cvs login
- $ cvs -z3 -d:pserver:anonymous@uclibc.org:/var/cvs co buildroot
-</pre>
-
- <h2><a name="using" id="using"></a>Using Buildroot</h2>
-
- <p>Buildroot has a nice configuration tool similar to the one you can find
- in the Linux Kernel (<a href=
- "http://www.kernel.org/">http://www.kernel.org/</a>) or in Busybox
- (<a href="http://www.busybox.org/">http://www.busybox.org/</a>). Note that
- you can run 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>For each entry of the configuration tool, you can find associated help
- that describes the purpose of the entry.</p>
-
- <p>Once everything is configured, the configuration tool has generated a
- <code>.config</code> file that contains the description of your
- configuration. It will be used by the Makefiles to do what's needed.</p>
-
- <p>Let's go:</p>
-
-<pre>
- $ make
-</pre>
-
- <p>This command will download, configure and compile all the selected
- tools, and finally generate a target filesystem. The target filesystem will
- be named <code>root_fs_ARCH.EXT</code> where <code>ARCH</code> is your
- architecture and <code>EXT</code> depends on the type of target filesystem
- selected in the <code>Target options</code> section of the configuration
- tool.</p>
-
- <h2><a name="custom_targetfs" id="custom_targetfs"></a>Customizing the
- target filesystem</h2>
-
- <p>There are two 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>build_ARCH/root/</code> where
- <code>ARCH</code> is the chosen target architecture. You can simply make
- your changes here, and run make afterwards, which will rebuild the target
- filesystem image. This method allows to do everything on the target
- filesystem, but if you decide to completely rebuild your toolchain and
- tools, these changes will be lost.</li>
-
- <li>Customize the target filesystem skeleton, available under
- <code>target/default/target_skeleton/</code>. You can customize
- configuration files or other stuff here. However, the full file hierarchy
- is not yet present, because it's created during the compilation process.
- So you can't do everything on this target filesystem skeleton, but
- changes to it remains even you completely rebuild the cross-compilation
- toolchain and the tools.<br />
- You can also customize the <code>target/default/device_table.txt</code>
- file which is used by the tools that generate the target filesystem image
- to properly set permissions and create device nodes. The
- <code>target/default/skel.tar.gz</code> file contains the main
- directories of a root filesystem and there is no obvious reason for which
- it should be changed. These main directories are in an tarball inside of
- inside the skeleton because it contains symlinks that would be broken
- otherwise.</li>
- </ul>
-
- <h2><a name="custom_busybox" id="custom_busybox"></a>Customizing the
- Busybox configuration</h2>
-
- <p>Busybox is very configurable, and you may want to customize it. You can
- follow these simple steps to do it. It's not an optimal way, but it's
- simple and it works.</p>
-
- <ol>
- <li>Make a first compilation of buildroot with busybox without trying to
- customize it.</li>
-
- <li>Go into <code>build_ARCH/busybox/</code> and run <code>make
- menuconfig</code>. The nice configuration tool appears and you can
- customize everything.</li>
-
- <li>Copy the <code>.config</code> file to
- <code>package/busybox/busybox.config</code> so that your customized
- configuration will remains even if you remove the cross-compilation
- toolchain.</li>
-
- <li>Run the compilation of buildroot again.</li>
- </ol>
-
- <p>Otherwise, you can simply change the
- <code>package/busybox/busybox.config</code> file if you know the options
- you want to change without using the configuration tool.</p>
-
- <h2><a name="custom_uclibc" id="custom_uclibc"></a>Customizing the uClibc
- configuration</h2>
-
- <p>Just like <a href="#custom_busybox">BusyBox</a>, <a
- href="http://www.uclibc.org">uClibc</a> offers a lot of
- configuration options. They allow 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>Make a first compilation of buildroot without trying to
- customize uClibc.</li>
-
- <li>Go into the directory
- <code>toolchain_build_ARCH/uClibc/</code> and run <code>make
- menuconfig</code>. The nice configuration assistant, similar to
- the one used in the Linux Kernel or in Buildroot appears. Make
- your configuration as appropriate.</li>
-
- <li>Copy the <code>.config</code> file to
- <code>toolchain/uClibc/uClibc.config</code> or
- <code>toolchain/uClibc/uClibc.config-locale</code>. The former
- is used if you haven't selected locale support in Buildroot
- configuration, and the latter is used if you have selected
- locale support.</li>
-
- <li>Run the compilation of Buildroot again</li>
-
- </ol>
-
- <p>Otherwise, you can simply change
- <code>toolchain/uClibc/uClibc.config</code> or
- <code>toolchain/uClibc/uClibc.config-locale</code> without running
- the configuration assistant.</p>
-
- <h2><a name="buildroot_innards" id="buildroot_innards"></a>How Buildroot
- works</h2>
-
- <p>As said above, Buildroot is basically a set of Makefiles that download,
- configure and compiles software with the correct options. It also includes
- some patches for various software, mainly the ones involved in the
- cross-compilation tool chain (<code>gcc</code>, <code>binutils</code> and
- uClibc).</p>
-
- <p>There is basically one Makefile per software, and they are named with
- the <code>.mk</code> extension. Makefiles are split into three
- sections:</p>
-
- <ul>
- <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>toolchain</b> (in the <code>toolchain/</code> directory) contains
- the Makefiles and associated files for all software related to the
- cross-compilation toolchain : <code>binutils</code>, <code>ccache</code>,
- <code>gcc</code>, <code>gdb</code>, <code>kernel-headers</code> and
- <code>uClibc</code>.</li>
-
- <li><b>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's 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 software <code>something</code>.</li>
-
- <li><code>Config.in</code> is a part of the configuration tool
- description file. It describes the option related to the current
- software.</li>
-
- </ul>
-
- <p>The main Makefile do the job through the following steps (once the
- configuration is done):</p>
-
- <ol>
- <li>Create the download directory (<code>dl/</code> by default). This is
- where the tarballs will be downloaded. It is interesting to know that the
- tarballs are in this directory because it may be useful to save them
- somewhere to avoid further downloads.</li>
-
- <li>Create the build directory (<code>build_ARCH/</code> by default,
- where <code>ARCH</code> is your architecture). This is where all
- user-space tools while be compiled.</li>
-
- <li>Create the toolchain build directory
- (<code>toolchain_build_ARCH/</code> by default, where <code>ARCH</code>
- is your architecture). This is where the cross compilation toolchain will
- be compiled.</li>
-
- <li>Setup the staging directory (<code>build_ARCH/staging_dir/</code> by
- default). This is where the cross-compilation toolchain will be
- installed. If you want to use the same cross-compilation toolchain for
- other purposes, such as compiling third-party applications, you can add
- <code>build_ARCH/staging_dir/bin</code> to your PATH, and then use
- <code>arch-linux-gcc</code> to compile your application. In order to
- setup this staging directory, it first removes it, and then it creates
- various subdirectories and symlinks inside it.</li>
-
- <li>Create the target directory (<code>build_ARCH/root/</code> by
- default) and the target filesystem skeleton. This directory will contain
- the final root filesystem. To setup it up, it first deletes it, then it
- uncompress the <code>target/default/skel.tar.gz</code> file to create the
- main subdirectories and symlinks, copies the skeleton available in
- <code>target/default/target_skeleton</code> and then removes useless
- <code>CVS/</code> directories.</li>
-
- <li>Add the <code>TARGETS</code> dependency. This should generally check
- if the configuration option for this package is enabled, and if so then
- "subscribe" this package to be compiled by adding it to the TARGETS
- global variable.</li>
- </ol>
-
- <h2><a name="using_toolchain" id="using_toolchain"></a>Using the
- uClibc toolchain</h2>
-
- <p>You may want to compile 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 by default is located in
- <code>build_ARCH/staging_dir/</code>. The simplest way to use it
- is to add <code>build_ARCH/staging_dir/bin/</code> to your PATH
- environnement variable, and then to use
- <code>arch-linux-gcc</code>, <code>arch-linux-objdump</code>,
- <code>arch-linux-ld</code>, etc.</p>
-
- <p>For example, you may add the following to your
- <code>.bashrc</code> (considering you're building for the MIPS
- architecture and that Buildroot is located in
- <code>~/buildroot/</code>) :</p>
-
-<pre>
-export PATH=$PATH:~/buildroot/build_mips/bin/
-</pre>
-
- <p>Then you can simply do :</p>
-
-<pre>
-mips-linux-gcc -o foo foo.c
-</pre>
-
- <p><b>Important</b> : do not try to move the toolchain to an other
- directory, it won't work. There are some hard-coded paths in the
- <i>gcc</i> configuration. If the default toolchain directory
- doesn't suit your needs, please refer to the <a
- href="#toolchain_standalone">Using the uClibc toolchain outside of
- buildroot</a> section.</p>
-
- <h2><a name="toolchain_standalone" id="toolchain_standalone"></a>Using the
- uClibc toolchain outside of buildroot</h2>
-
- <p>By default, the cross-compilation toolchain is generated inside
- <code>build_ARCH/staging_dir/</code>. But sometimes, it may be useful to
- install it somewhere else, so that it can be used to compile other programs
- or by other users. Moving the <code>build_ARCH/staging_dir/</code>
- directory elsewhere is <b>not possible</b>, because they are some hardcoded
- paths in the toolchain configuration.</p>
-
- <p>If you want to use the generated toolchain for other purposes,
- you can configure Buildroot to generate it elsewhere using the
- option of the configuration tool : <code>Build options ->
- Toolchain and header file location</code>, which defaults to
- <code>$(BUILD_DIR)/staging_dir/</code>.</p>
-
- <h2><a name="downloaded_packages"
- id="downloaded_packages"></a>Location of downloaded packages</h2>
-
- <p>It might be useful to know that the various tarballs that are
- downloaded by the <i>Makefiles</i> are all stored in the
- <code>DL_DIR</code> which by default is the <code>dl</code>
- directory. It's useful for example if you want to keep a complete
- version of Buildroot which is know to be working with the
- associated tarballs. This will allow you to regenerate the
- toolchain and the target filesystem with exactly the same
- versions.</p>
-
- <h2><a name="add_software" id="add_software"></a>Extending Buildroot with
- more software</h2>
-
- <p>This section will only consider the case in which you want to
- add user-space software.</p>
-
- <h3>Package directory</h3>
-
- <p>First of all, create a directory under the <code>package</code>
- directory for your software, for example <code>foo</code>.</p>
-
- <h3><code>Config.in</code> file</h3>
-
- <p>Then, create a file named <code>Config.in</code>. This file
- will contain the portion of options description related to our
- <code>foo</code> software that will be used and displayed in the
- configuration tool. It should basically contain :</p>
-
-<pre>
-config BR2_PACKAGE_FOO
- bool "foo"
- default n
- help
- This is a comment that explains what foo is.
-</pre>
-
- <p>Of course, you can add other options to configure particular
- things in your software.</p>
-
- <h3>The real <i>Makefile</i></h3>
-
- <p>Finally, here's the hardest part. Create a file named
- <code>foo.mk</code>. It will contain the <i>Makefile</i> rules that
- are in charge of downloading, configuring, compiling and installing
- the software. Below is an example that we will comment
- afterwards.</p>
-
-<pre>
- 1 #############################################################
- 2 #
- 3 # foo
- 4 #
- 5 #############################################################
- 6 FOO_VERSION:=1.0
- 7 FOO_SOURCE:=less-$(FOO_VERSION).tar.gz
- 8 FOO_SITE:=http://www.foosoftware.org/downloads
- 9 FOO_DIR:=$(BUILD_DIR)/less-$(FOO_VERSION)
- 10 FOO_BINARY:=foo
- 11 FOO_TARGET_BINARY:=usr/bin/foo
- 12
- 13 $(DL_DIR)/$(FOO_SOURCE):
- 14 $(WGET) -P $(DL_DIR) $(FOO_SITE)/$(FOO_SOURCE)
- 15
- 16 $(FOO_DIR)/.source: $(DL_DIR)/$(FOO_SOURCE)
- 17 zcat $(DL_DIR)/$(FOO_SOURCE) | tar -C $(BUILD_DIR) $(TAR_OPTIONS) -
- 18 touch $(FOO_DIR)/.source
- 19
- 20 $(FOO_DIR)/.configured: $(FOO_DIR)/.source
- 21 (cd $(FOO_DIR); \
- 22 $(TARGET_CONFIGURE_OPTS) \
- 23 CFLAGS="$(TARGET_CFLAGS)" \
- 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 $(FOO_DIR)/.configured;
- 32
- 33 $(FOO_DIR)/$(FOO_BINARY): $(FOO_DIR)/.configured
- 34 $(MAKE) CC=$(TARGET_CC) -C $(FOO_DIR)
- 35
- 36 $(TARGET_DIR)/$(FOO_TARGET_BINARY): $(FOO_DIR)/$(FOO_BINARY)
- 37 $(MAKE) prefix=$(TARGET_DIR)/usr -C $(FOO_DIR) install
- 38 rm -Rf $(TARGET_DIR)/usr/man
- 39
- 40 foo: uclibc ncurses $(TARGET_DIR)/$(FOO_TARGET_BINARY)
- 41
- 42 foo-source: $(DL_DIR)/$(FOO_SOURCE)
- 43
- 44 foo-clean:
- 45 $(MAKE) prefix=$(TARGET_DIR)/usr -C $(FOO_DIR) uninstall
- 46 -$(MAKE) -C $(FOO_DIR) clean
- 47
- 48 foo-dirclean:
- 49 rm -rf $(FOO_DIR)
- 50
- 51 #############################################################
- 52 #
- 53 # Toplevel Makefile options
- 54 #
- 55 #############################################################
- 56 ifeq ($(strip $(BR2_PACKAGE_FOO)),y)
- 57 TARGETS+=foo
- 58 endif
-
-</pre>
-
- <p>First of all, this <i>Makefile</i> example works for a single
- binary software. For other software such as libraries or more
- complex stuff with multiple binaries, it should be adapted. Look at
- the other <code>*.mk</code> files in the <code>package</code>
- directory.</p>
-
- <p>At lines 6-11, a couple of useful variables are defined :</p>
-
- <ul>
-
- <li><code>FOO_VERSION</code> : The version of <i>foo</i> that
- should be downloaded.</li>
-
- <li><code>FOO_SOURCE</code> : The name of the tarball of
- <i>foo</i> on the download website of FTP site. As you can see
- <code>FOO_VERSION</code> is used.</li>
-
- <li><code>FOO_SITE</code> : The HTTP or FTP site from which
- <i>foo</i> archive is downloaded. It must include the complete
- path to the directory where <code>FOO_SOURCE</code> can be
- found.</li>
-
- <li><code>FOO_DIR</code> : The directory into which the software
- will be configured and compiled. Basically, it's a subdirectory
- of <code>BUILD_DIR</code> which is created upon decompression of
- the tarball.</li>
-
- <li><code>FOO_BINARY</code> : Software binary name. As said
- previously, this is an example for a single binary software.</li>
-
- <li><code>FOO_TARGET_BINARY</code> : The full path of the binary
- inside the target filesystem.</li>
-
- </ul>
-
- <p>Lines 13-14 defines a target that downloads the tarball from
- the remote site to the download directory
- (<code>DL_DIR</code>).</p>
-
- <p>Lines 16-18 defines 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 (line
- 13-14) is called before executing the rules of the current
- target. Uncompressing is followed by <i>touching</i> a hidden file
- to mark the software has having been uncompressed. This trick is
- used everywhere in Buildroot <i>Makefile</i> to split steps
- (download, uncompress, configure, compile, install) while still
- having correct dependencies.</p>
-
- <p>Lines 20-31 defines a target and associated rules that
- configures 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 it, 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 in the target
- filesystem. Finally it creates a <code>.configured</code> file to
- mark the software as configured.</p>
-
- <p>Lines 33-34 defines a target and a rule that compiles 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 36-38 defines a target and associated rules that install
- the software inside the target filesystem. It depends on the
- binary file in the source directory, to make sure the software has
- been compiled. It uses the <code>install</code> target of the
- software <code>Makefile</code> by passing a <code>prefix</code>
- argument, so that the <code>Makefile</code> doesn't try to install
- the software inside host <code>/usr</code> but inside 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 40 defines the main target of the software, the one
- that will be eventually be used by the top level
- <code>Makefile</code> to download, compile, and then install
- this package. This target should first of all depends on all
- needed dependecies 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 42 defines a simple target that only downloads the code
- source. This is not used during normal operation of Buildroot, but
- might be useful.</p>
-
- <p>Lignes 44-46 define a simple target to clean the software build
- by calling the <i>Makefiles</i> with the appropriate option.</p>
-
- <p>Lines 48-49 define a simple target to completely remove the
- directory in which the software was uncompressed, configured and
- compiled.</p>
-
- <p>Lines 51-58 adds the target <code>foo</code> to the list
- of targets to be compiled by Buildroot by first checking if
- the configuration option for this package has been enabled
- using the configuration tool, and if so then "subscribes"
- this package to be compiled by adding it 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 40, which is used by Buildroot to download, compile, and
- then install this package.</p>
-
-
- <h3>Conclusion</h3>
-
- <p>As you can see, adding a software to buildroot is simply a
- matter of writing a <i>Makefile</i> using an already existing
- example and to modify it according to the compilation process of
- the software.</p>
-
- <p>If you package software that might be useful for other persons,
- don't forget to send a patch to Buildroot developers !</p>
-
- <h2><a name="links" id="links"></a>Ressources</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>
--- /dev/null
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+ <title>Buildroot - Usage and documentation</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
+ <link rel="stylesheet" type="text/css" href="stylesheet.css" />
+</head>
+
+<body>
+ <div class="main">
+ <div class="titre">
+ <h1>Buildroot</h1>
+ </div>
+
+ <p>Usage and documentation by Thomas Petazzoni. Contributions from
+ Karsten Kruse, Ned Ludd, Martin Herren.</p>
+
+ <p><small>Last modification : $Id: buildroot-documentation.html,v 1.2 2004/12/28 19:15:20 andersen Exp $</small></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 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="#buildroot_innards">How Buildroot works</a></li>
+ <li><a href="#using_toolchain">Using the uClibc toolchain</a></li>
+ <li><a href="#toolchain_standalone">Using the uClibc toolchain
+ outside of Buildroot</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="#links">Ressources</a></li>
+ </ul>
+
+ <h2><a name="about" id="about"></a>About Buildroot</h2>
+
+ <p>Buildroot is a set of Makefiles and patches that allows to easily
+ generate both a cross-compilation toolchain and a root filesystem for your
+ target. The cross-compilation toolchain uses uClibc (<a href=
+ "http://www.uclibc.org/">http://www.uclibc.org/</a>), a tiny C standard
+ library.</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 have on his PC. It can be PowerPC
+ processors, MIPS processors, ARM processors, etc.</p>
+
+ <p>A compilation toolchain is the set of tools that allows 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 application that
+ runs on your system. If you're using a PC, your compilation
+ toolchain runs on an x86 processor and generates code for a x86
+ processor. Under most Linux systems, the compilation toolchain
+ uses the GNU libc as C standard library. This compilation
+ toolchain is called the "host compilation toolchain", and more
+ generally, 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.</p>
+
+ <p>As said above, the compilation toolchain that comes with your system
+ runs and generates code for the processor of your host system. As your
+ embedded system has a different processor, you need a cross-compilation
+ toolchain: it's a compilation toolchain that runs on your host system but
+ that 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 of 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 a x86 processor, you might interested
+ in Buildroot, for two reasons:</p>
+
+ <ul>
+ <li>The compilation toolchain of 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 it for
+ you.</li>
+
+ <li>Buildroot automates the building of a root filesystem with all needed
+ tools like busybox. It 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>, uClibc and all the tools by hand.
+ Of course, doing so is possible. But dealing with all configure options,
+ with all problems of every <code>gcc</code> or <code>binutils</code>
+ version it 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>
+
+ <h2><a name="download" id="download"></a>Obtaining Buildroot</h2>
+
+ <p>Buildroot is available as daily CVS snapshots or directly using
+ CVS.</p>
+
+ <p>The latest snapshot is always available at <a
+ href="http://uclibc.org/downloads/snapshots/buildroot-snapshot.tar.bz2">http://uclibc.org/downloads/snapshots/buildroot-snapshot.tar.bz2</a>,
+ and previous snapshots are also available at <a
+ href="http://uclibc.org/downloads/snapshots/">http://uclibc.org/downloads/snapshots/</a>.</p>
+
+ <p>To download Buildroot using CVS, you can simply follow
+ the rules described on the "Accessing CVS"-page (<a href=
+ "http://www.uclibc.org/cvs_anon.html">http://www.uclibc.org/cvs_anon.html</a>)
+ of the uClibc website (<a href=
+ "http://www.uclibc.org">http://www.uclibc.org</a>), and download the
+ <code>buildroot</code> CVS module. For the impatient, here's a quick
+ recipe:</p>
+
+ <pre>
+ $ cvs -d:pserver:anonymous@uclibc.org:/var/cvs login
+ $ cvs -z3 -d:pserver:anonymous@uclibc.org:/var/cvs co buildroot
+</pre>
+
+ <h2><a name="using" id="using"></a>Using Buildroot</h2>
+
+ <p>Buildroot has a nice configuration tool similar to the one you can find
+ in the Linux Kernel (<a href=
+ "http://www.kernel.org/">http://www.kernel.org/</a>) or in Busybox
+ (<a href="http://www.busybox.org/">http://www.busybox.org/</a>). Note that
+ you can run 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>For each entry of the configuration tool, you can find associated help
+ that describes the purpose of the entry.</p>
+
+ <p>Once everything is configured, the configuration tool has generated a
+ <code>.config</code> file that contains the description of your
+ configuration. It will be used by the Makefiles to do what's needed.</p>
+
+ <p>Let's go:</p>
+
+<pre>
+ $ make
+</pre>
+
+ <p>This command will download, configure and compile all the selected
+ tools, and finally generate a target filesystem. The target filesystem will
+ be named <code>root_fs_ARCH.EXT</code> where <code>ARCH</code> is your
+ architecture and <code>EXT</code> depends on the type of target filesystem
+ selected in the <code>Target options</code> section of the configuration
+ tool.</p>
+
+ <h2><a name="custom_targetfs" id="custom_targetfs"></a>Customizing the
+ target filesystem</h2>
+
+ <p>There are two 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>build_ARCH/root/</code> where
+ <code>ARCH</code> is the chosen target architecture. You can simply make
+ your changes here, and run make afterwards, which will rebuild the target
+ filesystem image. This method allows to do everything on the target
+ filesystem, but if you decide to completely rebuild your toolchain and
+ tools, these changes will be lost.</li>
+
+ <li>Customize the target filesystem skeleton, available under
+ <code>target/default/target_skeleton/</code>. You can customize
+ configuration files or other stuff here. However, the full file hierarchy
+ is not yet present, because it's created during the compilation process.
+ So you can't do everything on this target filesystem skeleton, but
+ changes to it remains even you completely rebuild the cross-compilation
+ toolchain and the tools.<br />
+ You can also customize the <code>target/default/device_table.txt</code>
+ file which is used by the tools that generate the target filesystem image
+ to properly set permissions and create device nodes. The
+ <code>target/default/skel.tar.gz</code> file contains the main
+ directories of a root filesystem and there is no obvious reason for which
+ it should be changed. These main directories are in an tarball inside of
+ inside the skeleton because it contains symlinks that would be broken
+ otherwise.</li>
+ </ul>
+
+ <h2><a name="custom_busybox" id="custom_busybox"></a>Customizing the
+ Busybox configuration</h2>
+
+ <p>Busybox is very configurable, and you may want to customize it. You can
+ follow these simple steps to do it. It's not an optimal way, but it's
+ simple and it works.</p>
+
+ <ol>
+ <li>Make a first compilation of buildroot with busybox without trying to
+ customize it.</li>
+
+ <li>Go into <code>build_ARCH/busybox/</code> and run <code>make
+ menuconfig</code>. The nice configuration tool appears and you can
+ customize everything.</li>
+
+ <li>Copy the <code>.config</code> file to
+ <code>package/busybox/busybox.config</code> so that your customized
+ configuration will remains even if you remove the cross-compilation
+ toolchain.</li>
+
+ <li>Run the compilation of buildroot again.</li>
+ </ol>
+
+ <p>Otherwise, you can simply change the
+ <code>package/busybox/busybox.config</code> file if you know the options
+ you want to change without using the configuration tool.</p>
+
+ <h2><a name="custom_uclibc" id="custom_uclibc"></a>Customizing the uClibc
+ configuration</h2>
+
+ <p>Just like <a href="#custom_busybox">BusyBox</a>, <a
+ href="http://www.uclibc.org">uClibc</a> offers a lot of
+ configuration options. They allow 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>Make a first compilation of buildroot without trying to
+ customize uClibc.</li>
+
+ <li>Go into the directory
+ <code>toolchain_build_ARCH/uClibc/</code> and run <code>make
+ menuconfig</code>. The nice configuration assistant, similar to
+ the one used in the Linux Kernel or in Buildroot appears. Make
+ your configuration as appropriate.</li>
+
+ <li>Copy the <code>.config</code> file to
+ <code>toolchain/uClibc/uClibc.config</code> or
+ <code>toolchain/uClibc/uClibc.config-locale</code>. The former
+ is used if you haven't selected locale support in Buildroot
+ configuration, and the latter is used if you have selected
+ locale support.</li>
+
+ <li>Run the compilation of Buildroot again</li>
+
+ </ol>
+
+ <p>Otherwise, you can simply change
+ <code>toolchain/uClibc/uClibc.config</code> or
+ <code>toolchain/uClibc/uClibc.config-locale</code> without running
+ the configuration assistant.</p>
+
+ <h2><a name="buildroot_innards" id="buildroot_innards"></a>How Buildroot
+ works</h2>
+
+ <p>As said above, Buildroot is basically a set of Makefiles that download,
+ configure and compiles software with the correct options. It also includes
+ some patches for various software, mainly the ones involved in the
+ cross-compilation tool chain (<code>gcc</code>, <code>binutils</code> and
+ uClibc).</p>
+
+ <p>There is basically one Makefile per software, and they are named with
+ the <code>.mk</code> extension. Makefiles are split into three
+ sections:</p>
+
+ <ul>
+ <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>toolchain</b> (in the <code>toolchain/</code> directory) contains
+ the Makefiles and associated files for all software related to the
+ cross-compilation toolchain : <code>binutils</code>, <code>ccache</code>,
+ <code>gcc</code>, <code>gdb</code>, <code>kernel-headers</code> and
+ <code>uClibc</code>.</li>
+
+ <li><b>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's 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 software <code>something</code>.</li>
+
+ <li><code>Config.in</code> is a part of the configuration tool
+ description file. It describes the option related to the current
+ software.</li>
+
+ </ul>
+
+ <p>The main Makefile do the job through the following steps (once the
+ configuration is done):</p>
+
+ <ol>
+ <li>Create the download directory (<code>dl/</code> by default). This is
+ where the tarballs will be downloaded. It is interesting to know that the
+ tarballs are in this directory because it may be useful to save them
+ somewhere to avoid further downloads.</li>
+
+ <li>Create the build directory (<code>build_ARCH/</code> by default,
+ where <code>ARCH</code> is your architecture). This is where all
+ user-space tools while be compiled.</li>
+
+ <li>Create the toolchain build directory
+ (<code>toolchain_build_ARCH/</code> by default, where <code>ARCH</code>
+ is your architecture). This is where the cross compilation toolchain will
+ be compiled.</li>
+
+ <li>Setup the staging directory (<code>build_ARCH/staging_dir/</code> by
+ default). This is where the cross-compilation toolchain will be
+ installed. If you want to use the same cross-compilation toolchain for
+ other purposes, such as compiling third-party applications, you can add
+ <code>build_ARCH/staging_dir/bin</code> to your PATH, and then use
+ <code>arch-linux-gcc</code> to compile your application. In order to
+ setup this staging directory, it first removes it, and then it creates
+ various subdirectories and symlinks inside it.</li>
+
+ <li>Create the target directory (<code>build_ARCH/root/</code> by
+ default) and the target filesystem skeleton. This directory will contain
+ the final root filesystem. To setup it up, it first deletes it, then it
+ uncompress the <code>target/default/skel.tar.gz</code> file to create the
+ main subdirectories and symlinks, copies the skeleton available in
+ <code>target/default/target_skeleton</code> and then removes useless
+ <code>CVS/</code> directories.</li>
+
+ <li>Add the <code>TARGETS</code> dependency. This should generally check
+ if the configuration option for this package is enabled, and if so then
+ "subscribe" this package to be compiled by adding it to the TARGETS
+ global variable.</li>
+ </ol>
+
+ <h2><a name="using_toolchain" id="using_toolchain"></a>Using the
+ uClibc toolchain</h2>
+
+ <p>You may want to compile 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 by default is located in
+ <code>build_ARCH/staging_dir/</code>. The simplest way to use it
+ is to add <code>build_ARCH/staging_dir/bin/</code> to your PATH
+ environnement variable, and then to use
+ <code>arch-linux-gcc</code>, <code>arch-linux-objdump</code>,
+ <code>arch-linux-ld</code>, etc.</p>
+
+ <p>For example, you may add the following to your
+ <code>.bashrc</code> (considering you're building for the MIPS
+ architecture and that Buildroot is located in
+ <code>~/buildroot/</code>) :</p>
+
+<pre>
+export PATH=$PATH:~/buildroot/build_mips/bin/
+</pre>
+
+ <p>Then you can simply do :</p>
+
+<pre>
+mips-linux-gcc -o foo foo.c
+</pre>
+
+ <p><b>Important</b> : do not try to move the toolchain to an other
+ directory, it won't work. There are some hard-coded paths in the
+ <i>gcc</i> configuration. If the default toolchain directory
+ doesn't suit your needs, please refer to the <a
+ href="#toolchain_standalone">Using the uClibc toolchain outside of
+ buildroot</a> section.</p>
+
+ <h2><a name="toolchain_standalone" id="toolchain_standalone"></a>Using the
+ uClibc toolchain outside of buildroot</h2>
+
+ <p>By default, the cross-compilation toolchain is generated inside
+ <code>build_ARCH/staging_dir/</code>. But sometimes, it may be useful to
+ install it somewhere else, so that it can be used to compile other programs
+ or by other users. Moving the <code>build_ARCH/staging_dir/</code>
+ directory elsewhere is <b>not possible</b>, because they are some hardcoded
+ paths in the toolchain configuration.</p>
+
+ <p>If you want to use the generated toolchain for other purposes,
+ you can configure Buildroot to generate it elsewhere using the
+ option of the configuration tool : <code>Build options ->
+ Toolchain and header file location</code>, which defaults to
+ <code>$(BUILD_DIR)/staging_dir/</code>.</p>
+
+ <h2><a name="downloaded_packages"
+ id="downloaded_packages"></a>Location of downloaded packages</h2>
+
+ <p>It might be useful to know that the various tarballs that are
+ downloaded by the <i>Makefiles</i> are all stored in the
+ <code>DL_DIR</code> which by default is the <code>dl</code>
+ directory. It's useful for example if you want to keep a complete
+ version of Buildroot which is know to be working with the
+ associated tarballs. This will allow you to regenerate the
+ toolchain and the target filesystem with exactly the same
+ versions.</p>
+
+ <h2><a name="add_software" id="add_software"></a>Extending Buildroot with
+ more software</h2>
+
+ <p>This section will only consider the case in which you want to
+ add user-space software.</p>
+
+ <h3>Package directory</h3>
+
+ <p>First of all, create a directory under the <code>package</code>
+ directory for your software, for example <code>foo</code>.</p>
+
+ <h3><code>Config.in</code> file</h3>
+
+ <p>Then, create a file named <code>Config.in</code>. This file
+ will contain the portion of options description related to our
+ <code>foo</code> software that will be used and displayed in the
+ configuration tool. It should basically contain :</p>
+
+<pre>
+config BR2_PACKAGE_FOO
+ bool "foo"
+ default n
+ help
+ This is a comment that explains what foo is.
+</pre>
+
+ <p>Of course, you can add other options to configure particular
+ things in your software.</p>
+
+ <h3>The real <i>Makefile</i></h3>
+
+ <p>Finally, here's the hardest part. Create a file named
+ <code>foo.mk</code>. It will contain the <i>Makefile</i> rules that
+ are in charge of downloading, configuring, compiling and installing
+ the software. Below is an example that we will comment
+ afterwards.</p>
+
+<pre>
+ 1 #############################################################
+ 2 #
+ 3 # foo
+ 4 #
+ 5 #############################################################
+ 6 FOO_VERSION:=1.0
+ 7 FOO_SOURCE:=less-$(FOO_VERSION).tar.gz
+ 8 FOO_SITE:=http://www.foosoftware.org/downloads
+ 9 FOO_DIR:=$(BUILD_DIR)/less-$(FOO_VERSION)
+ 10 FOO_BINARY:=foo
+ 11 FOO_TARGET_BINARY:=usr/bin/foo
+ 12
+ 13 $(DL_DIR)/$(FOO_SOURCE):
+ 14 $(WGET) -P $(DL_DIR) $(FOO_SITE)/$(FOO_SOURCE)
+ 15
+ 16 $(FOO_DIR)/.source: $(DL_DIR)/$(FOO_SOURCE)
+ 17 zcat $(DL_DIR)/$(FOO_SOURCE) | tar -C $(BUILD_DIR) $(TAR_OPTIONS) -
+ 18 touch $(FOO_DIR)/.source
+ 19
+ 20 $(FOO_DIR)/.configured: $(FOO_DIR)/.source
+ 21 (cd $(FOO_DIR); \
+ 22 $(TARGET_CONFIGURE_OPTS) \
+ 23 CFLAGS="$(TARGET_CFLAGS)" \
+ 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 $(FOO_DIR)/.configured;
+ 32
+ 33 $(FOO_DIR)/$(FOO_BINARY): $(FOO_DIR)/.configured
+ 34 $(MAKE) CC=$(TARGET_CC) -C $(FOO_DIR)
+ 35
+ 36 $(TARGET_DIR)/$(FOO_TARGET_BINARY): $(FOO_DIR)/$(FOO_BINARY)
+ 37 $(MAKE) prefix=$(TARGET_DIR)/usr -C $(FOO_DIR) install
+ 38 rm -Rf $(TARGET_DIR)/usr/man
+ 39
+ 40 foo: uclibc ncurses $(TARGET_DIR)/$(FOO_TARGET_BINARY)
+ 41
+ 42 foo-source: $(DL_DIR)/$(FOO_SOURCE)
+ 43
+ 44 foo-clean:
+ 45 $(MAKE) prefix=$(TARGET_DIR)/usr -C $(FOO_DIR) uninstall
+ 46 -$(MAKE) -C $(FOO_DIR) clean
+ 47
+ 48 foo-dirclean:
+ 49 rm -rf $(FOO_DIR)
+ 50
+ 51 #############################################################
+ 52 #
+ 53 # Toplevel Makefile options
+ 54 #
+ 55 #############################################################
+ 56 ifeq ($(strip $(BR2_PACKAGE_FOO)),y)
+ 57 TARGETS+=foo
+ 58 endif
+
+</pre>
+
+ <p>First of all, this <i>Makefile</i> example works for a single
+ binary software. For other software such as libraries or more
+ complex stuff with multiple binaries, it should be adapted. Look at
+ the other <code>*.mk</code> files in the <code>package</code>
+ directory.</p>
+
+ <p>At lines 6-11, a couple of useful variables are defined :</p>
+
+ <ul>
+
+ <li><code>FOO_VERSION</code> : The version of <i>foo</i> that
+ should be downloaded.</li>
+
+ <li><code>FOO_SOURCE</code> : The name of the tarball of
+ <i>foo</i> on the download website of FTP site. As you can see
+ <code>FOO_VERSION</code> is used.</li>
+
+ <li><code>FOO_SITE</code> : The HTTP or FTP site from which
+ <i>foo</i> archive is downloaded. It must include the complete
+ path to the directory where <code>FOO_SOURCE</code> can be
+ found.</li>
+
+ <li><code>FOO_DIR</code> : The directory into which the software
+ will be configured and compiled. Basically, it's a subdirectory
+ of <code>BUILD_DIR</code> which is created upon decompression of
+ the tarball.</li>
+
+ <li><code>FOO_BINARY</code> : Software binary name. As said
+ previously, this is an example for a single binary software.</li>
+
+ <li><code>FOO_TARGET_BINARY</code> : The full path of the binary
+ inside the target filesystem.</li>
+
+ </ul>
+
+ <p>Lines 13-14 defines a target that downloads the tarball from
+ the remote site to the download directory
+ (<code>DL_DIR</code>).</p>
+
+ <p>Lines 16-18 defines 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 (line
+ 13-14) is called before executing the rules of the current
+ target. Uncompressing is followed by <i>touching</i> a hidden file
+ to mark the software has having been uncompressed. This trick is
+ used everywhere in Buildroot <i>Makefile</i> to split steps
+ (download, uncompress, configure, compile, install) while still
+ having correct dependencies.</p>
+
+ <p>Lines 20-31 defines a target and associated rules that
+ configures 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 it, 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 in the target
+ filesystem. Finally it creates a <code>.configured</code> file to
+ mark the software as configured.</p>
+
+ <p>Lines 33-34 defines a target and a rule that compiles 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 36-38 defines a target and associated rules that install
+ the software inside the target filesystem. It depends on the
+ binary file in the source directory, to make sure the software has
+ been compiled. It uses the <code>install</code> target of the
+ software <code>Makefile</code> by passing a <code>prefix</code>
+ argument, so that the <code>Makefile</code> doesn't try to install
+ the software inside host <code>/usr</code> but inside 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 40 defines the main target of the software, the one
+ that will be eventually be used by the top level
+ <code>Makefile</code> to download, compile, and then install
+ this package. This target should first of all depends on all
+ needed dependecies 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 42 defines a simple target that only downloads the code
+ source. This is not used during normal operation of Buildroot, but
+ might be useful.</p>
+
+ <p>Lignes 44-46 define a simple target to clean the software build
+ by calling the <i>Makefiles</i> with the appropriate option.</p>
+
+ <p>Lines 48-49 define a simple target to completely remove the
+ directory in which the software was uncompressed, configured and
+ compiled.</p>
+
+ <p>Lines 51-58 adds the target <code>foo</code> to the list
+ of targets to be compiled by Buildroot by first checking if
+ the configuration option for this package has been enabled
+ using the configuration tool, and if so then "subscribes"
+ this package to be compiled by adding it 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 40, which is used by Buildroot to download, compile, and
+ then install this package.</p>
+
+
+ <h3>Conclusion</h3>
+
+ <p>As you can see, adding a software to buildroot is simply a
+ matter of writing a <i>Makefile</i> using an already existing
+ example and to modify it according to the compilation process of
+ the software.</p>
+
+ <p>If you package software that might be useful for other persons,
+ don't forget to send a patch to Buildroot developers !</p>
+
+ <h2><a name="links" id="links"></a>Ressources</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>
projects / buildroot.git / commitdiff