docs/buildroot-documentation.html

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   3     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   4
   5 <html xmlns="http://www.w3.org/1999/xhtml">
   6 <head>
   7   <title>Buildroot - Usage and documentation</title>
   8   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
   9   <link rel="stylesheet" type="text/css" href="stylesheet.css" />
  10 </head>
  11
  12 <body>
  13   <div class="main">
  14     <div class="titre">
  15       <h1>Buildroot</h1>
  16     </div>
  17
  18     <p>Usage and documentation by Thomas Petazzoni. Contributions from
  19     Karsten Kruse, Ned Ludd, Martin Herren.</p>
  20
  21     <p><small>Last modification : $Id$</small></p>
  22
  23     <ul>
  24       <li><a href="#about">About Buildroot</a></li>
  25       <li><a href="#download">Obtaining Buildroot</a></li>
  26       <li><a href="#using">Using Buildroot</a></li>
  27       <li><a href="#custom_targetfs">Customizing the target filesystem</a></li>
  28       <li><a href="#custom_busybox">Customizing the Busybox
  29       configuration</a></li>
  30       <li><a href="#custom_uclibc">Customizing the uClibc
  31       configuration</a></li>
  32       <li><a href="#buildroot_innards">How Buildroot works</a></li>
  33       <li><a href="#using_toolchain">Using the uClibc toolchain</a></li>
  34       <li><a href="#toolchain_standalone">Using the uClibc toolchain
  35       outside of Buildroot</a></li>
  36       <li><a href="#downloaded_packages">Location of downloaded packages</a></li>
  37       <li><a href="#add_software">Extending Buildroot with more
  38       Software</a></li>
  39       <li><a href="#links">Ressources</a></li>
  40     </ul>
  41
  42     <h2><a name="about" id="about"></a>About Buildroot</h2>
  43
  44     <p>Buildroot is a set of Makefiles and patches that allows to easily
  45     generate both a cross-compilation toolchain and a root filesystem for your
  46     target. The cross-compilation toolchain uses uClibc (<a href=
  47     "http://www.uclibc.org/">http://www.uclibc.org/</a>), a tiny C standard
  48     library.</p>
  49
  50     <p>Buildroot is useful mainly for people working with embedded systems.
  51     Embedded systems often use processors that are not the regular x86
  52     processors everyone is used to have on his PC. It can be PowerPC
  53     processors, MIPS processors, ARM processors, etc.</p>
  54
  55     <p>A compilation toolchain is the set of tools that allows to
  56     compile code for your system. It consists of a compiler (in our
  57     case, <code>gcc</code>), binary utils like assembler and linker
  58     (in our case, <code>binutils</code>) and a C standard library (for
  59     example <a href="http://www.gnu.org/software/libc/libc.html">GNU
  60     Libc</a>, <a href="http://www.uclibc.org">uClibc</a> or <a
  61     href="http://www.fefe.de/dietlibc/">dietlibc</a>). The system
  62     installed on your development station certainly already has a
  63     compilation toolchain that you can use to compile application that
  64     runs on your system. If you're using a PC, your compilation
  65     toolchain runs on an x86 processor and generates code for a x86
  66     processor. Under most Linux systems, the compilation toolchain
  67     uses the GNU libc as C standard library.  This compilation
  68     toolchain is called the "host compilation toolchain", and more
  69     generally, the machine on which it is running, and on which you're
  70     working is called the "host system". The compilation toolchain is
  71     provided by your distribution, and Buildroot has nothing to do
  72     with it.</p>
  73
  74     <p>As said above, the compilation toolchain that comes with your system
  75     runs and generates code for the processor of your host system. As your
  76     embedded system has a different processor, you need a cross-compilation
  77     toolchain: it's a compilation toolchain that runs on your host system but
  78     that generates code for your target system (and target processor). For
  79     example, if your host system uses x86 and your target system uses ARM, the
  80     regular compilation toolchain of your host runs on x86 and generates code
  81     for x86, while the cross-compilation toolchain runs on x86 and generates
  82     code for ARM.</p>
  83
  84     <p>Even if your embedded system uses a x86 processor, you might interested
  85     in Buildroot, for two reasons:</p>
  86
  87     <ul>
  88       <li>The compilation toolchain of your host certainly uses the GNU Libc
  89       which is a complete but huge C standard library. Instead of using GNU
  90       Libc on your target system, you can use uClibc which is a tiny C standard
  91       library. If you want to use this C library, then you need a compilation
  92       toolchain to generate binaries linked with it. Buildroot can do it for
  93       you.</li>
  94
  95       <li>Buildroot automates the building of a root filesystem with all needed
  96       tools like busybox. It makes it much easier than doing it by hand.</li>
  97     </ul>
  98
  99     <p>You might wonder why such a tool is needed when you can compile
 100     <code>gcc</code>, <code>binutils</code>, uClibc and all the tools by hand.
 101     Of course, doing so is possible. But dealing with all configure options,
 102     with all problems of every <code>gcc</code> or <code>binutils</code>
 103     version it very time-consuming and uninteresting. Buildroot automates this
 104     process through the use of Makefiles, and has a collection of patches for
 105     each <code>gcc</code> and <code>binutils</code> version to make them work
 106     on most architectures.</p>
 107
 108     <h2><a name="download" id="download"></a>Obtaining Buildroot</h2>
 109
 110     <p>Buildroot is available as daily CVS snapshots or directly using
 111     CVS.</p>
 112
 113     <p>The latest snapshot is always available at <a
 114     href="http://uclibc.org/downloads/snapshots/buildroot-snapshot.tar.bz2">http://uclibc.org/downloads/snapshots/buildroot-snapshot.tar.bz2</a>,
 115     and previous snapshots are also available at <a
 116     href="http://uclibc.org/downloads/snapshots/">http://uclibc.org/downloads/snapshots/</a>.</p>
 117
 118     <p>To download Buildroot using CVS, you can simply follow
 119     the rules described on the "Accessing CVS"-page (<a href=
 120     "http://www.uclibc.org/cvs_anon.html">http://www.uclibc.org/cvs_anon.html</a>)
 121     of the uClibc website (<a href=
 122     "http://www.uclibc.org">http://www.uclibc.org</a>), and download the
 123     <code>buildroot</code> CVS module. For the impatient, here's a quick
 124     recipe:</p>
 125
 126  <pre>
 127  $ cvs -d:pserver:anonymous@uclibc.org:/var/cvs login
 128  $ cvs -z3 -d:pserver:anonymous@uclibc.org:/var/cvs co buildroot
 129 </pre>
 130
 131     <h2><a name="using" id="using"></a>Using Buildroot</h2>
 132
 133     <p>Buildroot has a nice configuration tool similar to the one you can find
 134     in the Linux Kernel (<a href=
 135     "http://www.kernel.org/">http://www.kernel.org/</a>) or in Busybox
 136     (<a href="http://www.busybox.org/">http://www.busybox.org/</a>). Note that
 137     you can run everything as a normal user. There is no need to be root to
 138     configure and use Buildroot. The first step is to run the configuration
 139     assistant:</p>
 140
 141 <pre>
 142  $ make menuconfig
 143 </pre>
 144
 145     <p>For each entry of the configuration tool, you can find associated help
 146     that describes the purpose of the entry.</p>
 147
 148     <p>Once everything is configured, the configuration tool has generated a
 149     <code>.config</code> file that contains the description of your
 150     configuration. It will be used by the Makefiles to do what's needed.</p>
 151
 152     <p>Let's go:</p>
 153
 154 <pre>
 155  $ make
 156 </pre>
 157
 158     <p>This command will download, configure and compile all the selected
 159     tools, and finally generate a target filesystem. The target filesystem will
 160     be named <code>root_fs_ARCH.EXT</code> where <code>ARCH</code> is your
 161     architecture and <code>EXT</code> depends on the type of target filesystem
 162     selected in the <code>Target options</code> section of the configuration
 163     tool.</p>
 164
 165     <h2><a name="custom_targetfs" id="custom_targetfs"></a>Customizing the
 166     target filesystem</h2>
 167
 168     <p>There are two ways to customize the resulting target filesystem:</p>
 169
 170     <ul>
 171       <li>Customize the target filesystem directly, and rebuild the image. The
 172       target filesystem is available under <code>build_ARCH/root/</code> where
 173       <code>ARCH</code> is the chosen target architecture. You can simply make
 174       your changes here, and run make afterwards, which will rebuild the target
 175       filesystem image. This method allows to do everything on the target
 176       filesystem, but if you decide to completely rebuild your toolchain and
 177       tools, these changes will be lost.</li>
 178
 179       <li>Customize the target filesystem skeleton, available under
 180       <code>target/default/target_skeleton/</code>. You can customize
 181       configuration files or other stuff here. However, the full file hierarchy
 182       is not yet present, because it's created during the compilation process.
 183       So you can't do everything on this target filesystem skeleton, but
 184       changes to it remains even you completely rebuild the cross-compilation
 185       toolchain and the tools.<br />
 186       You can also customize the <code>target/default/device_table.txt</code>
 187       file which is used by the tools that generate the target filesystem image
 188       to properly set permissions and create device nodes. The
 189       <code>target/default/skel.tar.gz</code> file contains the main
 190       directories of a root filesystem and there is no obvious reason for which
 191       it should be changed. These main directories are in an tarball inside of
 192       inside the skeleton because it contains symlinks that would be broken
 193       otherwise.</li>
 194     </ul>
 195
 196     <h2><a name="custom_busybox" id="custom_busybox"></a>Customizing the
 197     Busybox configuration</h2>
 198
 199     <p>Busybox is very configurable, and you may want to customize it. You can
 200     follow these simple steps to do it. It's not an optimal way, but it's
 201     simple and it works.</p>
 202
 203     <ol>
 204       <li>Make a first compilation of buildroot with busybox without trying to
 205       customize it.</li>
 206
 207       <li>Go into <code>build_ARCH/busybox/</code> and run <code>make
 208       menuconfig</code>. The nice configuration tool appears and you can
 209       customize everything.</li>
 210
 211       <li>Copy the <code>.config</code> file to
 212       <code>package/busybox/busybox.config</code> so that your customized
 213       configuration will remains even if you remove the cross-compilation
 214       toolchain.</li>
 215
 216       <li>Run the compilation of buildroot again.</li>
 217     </ol>
 218
 219     <p>Otherwise, you can simply change the
 220     <code>package/busybox/busybox.config</code> file if you know the options
 221     you want to change without using the configuration tool.</p>
 222
 223     <h2><a name="custom_uclibc" id="custom_uclibc"></a>Customizing the uClibc
 224     configuration</h2>
 225
 226     <p>Just like <a href="#custom_busybox">BusyBox</a>, <a
 227     href="http://www.uclibc.org">uClibc</a> offers a lot of
 228     configuration options. They allow to select various
 229     functionalities, depending on your needs and limitations.</p>
 230
 231     <p>The easiest way to modify the configuration of uClibc is to
 232     follow these steps :</p>
 233
 234     <ol>
 235
 236       <li>Make a first compilation of buildroot without trying to
 237       customize uClibc.</li>
 238
 239       <li>Go into the directory
 240       <code>toolchain_build_ARCH/uClibc/</code> and run <code>make
 241       menuconfig</code>. The nice configuration assistant, similar to
 242       the one used in the Linux Kernel or in Buildroot appears. Make
 243       your configuration as appropriate.</li>
 244
 245       <li>Copy the <code>.config</code> file to
 246       <code>toolchain/uClibc/uClibc.config</code> or
 247       <code>toolchain/uClibc/uClibc.config-locale</code>. The former
 248       is used if you haven't selected locale support in Buildroot
 249       configuration, and the latter is used if you have selected
 250       locale support.</li>
 251
 252       <li>Run the compilation of Buildroot again</li>
 253
 254     </ol>
 255
 256     <p>Otherwise, you can simply change
 257     <code>toolchain/uClibc/uClibc.config</code> or
 258     <code>toolchain/uClibc/uClibc.config-locale</code> without running
 259     the configuration assistant.</p>
 260
 261     <h2><a name="buildroot_innards" id="buildroot_innards"></a>How Buildroot
 262     works</h2>
 263
 264     <p>As said above, Buildroot is basically a set of Makefiles that download,
 265     configure and compiles software with the correct options. It also includes
 266     some patches for various software, mainly the ones involved in the
 267     cross-compilation tool chain (<code>gcc</code>, <code>binutils</code> and
 268     uClibc).</p>
 269
 270     <p>There is basically one Makefile per software, and they are named with
 271     the <code>.mk</code> extension. Makefiles are split into three
 272     sections:</p>
 273
 274     <ul>
 275       <li><b>package</b> (in the <code>package/</code> directory) contains the
 276       Makefiles and associated files for all user-space tools that Buildroot
 277       can compile and add to the target root filesystem. There is one
 278       sub-directory per tool.</li>
 279
 280       <li><b>toolchain</b> (in the <code>toolchain/</code> directory) contains
 281       the Makefiles and associated files for all software related to the
 282       cross-compilation toolchain : <code>binutils</code>, <code>ccache</code>,
 283       <code>gcc</code>, <code>gdb</code>, <code>kernel-headers</code> and
 284       <code>uClibc</code>.</li>
 285
 286       <li><b>target</b> (in the <code>target</code> directory) contains the
 287       Makefiles and associated files for software related to the generation of
 288       the target root filesystem image. Four types of filesystems are supported
 289       : ext2, jffs2, cramfs and squashfs. For each of them, there's a
 290       sub-directory with the required files. There is also a
 291       <code>default/</code> directory that contains the target filesystem
 292       skeleton.</li>
 293     </ul>
 294
 295     <p>Each directory contains at least 3 files :</p>
 296
 297     <ul>
 298       <li><code>something.mk</code> is the Makefile that downloads, configures,
 299       compiles and installs the software <code>something</code>.</li>
 300
 301       <li><code>Config.in</code> is a part of the configuration tool
 302       description file. It describes the option related to the current
 303       software.</li>
 304
 305       <li><code>Makefile.in</code> is a part of Makefile that sets various
 306       variables according to the configuration given through the configuration
 307       tool. For most tools it simply involves adding the name of the tool to
 308       the <code>TARGETS</code> variable.</li>
 309     </ul>
 310
 311     <p>The main Makefile do the job through the following steps (once the
 312     configuration is done):</p>
 313
 314     <ol>
 315       <li>Create the download directory (<code>dl/</code> by default). This is
 316       where the tarballs will be downloaded. It is interesting to know that the
 317       tarballs are in this directory because it may be useful to save them
 318       somewhere to avoid further downloads.</li>
 319
 320       <li>Create the build directory (<code>build_ARCH/</code> by default,
 321       where <code>ARCH</code> is your architecture). This is where all
 322       user-space tools while be compiled.</li>
 323
 324       <li>Create the toolchain build directory
 325       (<code>toolchain_build_ARCH/</code> by default, where <code>ARCH</code>
 326       is your architecture). This is where the cross compilation toolchain will
 327       be compiled.</li>
 328
 329       <li>Setup the staging directory (<code>build_ARCH/staging_dir/</code> by
 330       default). This is where the cross-compilation toolchain will be
 331       installed. If you want to use the same cross-compilation toolchain for
 332       other purposes, such as compiling third-party applications, you can add
 333       <code>build_ARCH/staging_dir/bin</code> to your PATH, and then use
 334       <code>arch-linux-gcc</code> to compile your application. In order to
 335       setup this staging directory, it first removes it, and then it creates
 336       various subdirectories and symlinks inside it.</li>
 337
 338       <li>Create the target directory (<code>build_ARCH/root/</code> by
 339       default) and the target filesystem skeleton. This directory will contain
 340       the final root filesystem. To setup it up, it first deletes it, then it
 341       uncompress the <code>target/default/skel.tar.gz</code> file to create the
 342       main subdirectories and symlinks, copies the skeleton available in
 343       <code>target/default/target_skeleton</code> and then removes useless
 344       <code>CVS/</code> directories.</li>
 345
 346       <li>Make the <code>TARGETS</code> dependency. This is where all the job
 347       is done : all <code>Makefile.in</code> files "subscribe" targets into
 348       this global variable, so that the needed tools gets compiled.</li>
 349     </ol>
 350
 351     <h2><a name="using_toolchain" id="using_toolchain"></a>Using the
 352     uClibc toolchain</h2>
 353
 354     <p>You may want to compile your own programs or other software
 355     that are not packaged in Buildroot. In order to do this, you can
 356     use the toolchain that was generated by Buildroot.</p>
 357
 358     <p>The toolchain generated by Buildroot by default is located in
 359     <code>build_ARCH/staging_dir/</code>. The simplest way to use it
 360     is to add <code>build_ARCH/staging_dir/bin/</code> to your PATH
 361     environnement variable, and then to use
 362     <code>arch-linux-gcc</code>, <code>arch-linux-objdump</code>,
 363     <code>arch-linux-ld</code>, etc.</p>
 364
 365     <p>For example, you may add the following to your
 366     <code>.bashrc</code> (considering you're building for the MIPS
 367     architecture and that Buildroot is located in
 368     <code>~/buildroot/</code>) :</p>
 369
 370 <pre>
 371 export PATH=$PATH:~/buildroot/build_mips/bin/
 372 </pre>
 373
 374     <p>Then you can simply do :</p>
 375
 376 <pre>
 377 mips-linux-gcc -o foo foo.c
 378 </pre>
 379
 380     <p><b>Important</b> : do not try to move the toolchain to an other
 381     directory, it won't work. There are some hard-coded paths in the
 382     <i>gcc</i> configuration. If the default toolchain directory
 383     doesn't suit your needs, please refer to the <a
 384     href="#toolchain_standalone">Using the uClibc toolchain outside of
 385     buildroot</a> section.</p>
 386
 387     <h2><a name="toolchain_standalone" id="toolchain_standalone"></a>Using the
 388     uClibc toolchain outside of buildroot</h2>
 389
 390     <p>By default, the cross-compilation toolchain is generated inside
 391     <code>build_ARCH/staging_dir/</code>. But sometimes, it may be useful to
 392     install it somewhere else, so that it can be used to compile other programs
 393     or by other users. Moving the <code>build_ARCH/staging_dir/</code>
 394     directory elsewhere is <b>not possible</b>, because they are some hardcoded
 395     paths in the toolchain configuration.</p>
 396
 397     <p>If you want to use the generated toolchain for other purposes,
 398     you can configure Buildroot to generate it elsewhere using the
 399     option of the configuration tool : <code>Build options ->
 400     Toolchain and header file location</code>, which defaults to
 401     <code>$(BUILD_DIR)/staging_dir/</code>.</p>
 402
 403     <h2><a name="downloaded_packages"
 404     id="downloaded_packages"></a>Location of downloaded packages</h2>
 405
 406     <p>It might be useful to know that the various tarballs that are
 407     downloaded by the <i>Makefiles</i> are all stored in the
 408     <code>DL_DIR</code> which by default is the <code>dl</code>
 409     directory. It's useful for example if you want to keep a complete
 410     version of Buildroot which is know to be working with the
 411     associated tarballs. This will allow you to regenerate the
 412     toolchain and the target filesystem with exactly the same
 413     versions.</p>
 414
 415     <h2><a name="add_software" id="add_software"></a>Extending Buildroot with
 416     more software</h2>
 417
 418     <p>This section will only consider the case in which you want to
 419     add user-space software.</p>
 420
 421     <h3>Package directory</h3>
 422
 423     <p>First of all, create a directory under the <code>package</code>
 424     directory for your software, for example <code>foo</code>.</p>
 425
 426     <h3><code>Config.in</code> file</h3>
 427
 428     <p>Then, create a file named <code>Config.in</code>. This file
 429     will contain the portion of options description related to our
 430     <code>foo</code> software that will be used and displayed in the
 431     configuration tool. It should basically contain :</p>
 432
 433 <pre>
 434 config BR2_PACKAGE_FOO
 435         bool "foo"
 436         default n
 437         help
 438              This is a comment that explains what foo is.
 439 </pre>
 440
 441     <p>Of course, you can add other options to configure particular
 442     things in your software.</p>
 443
 444     <h3><code>Makefile.in</code> file</h3>
 445
 446     <p>Then, write a <code>Makefile.in</code> file. Basically, this is
 447     a very short <i>Makefile</i> that adds the name of the software to
 448     the list of <code>TARGETS</code> that Buildroot will generate. In
 449     fact, the name of the software is the the identifier of the target
 450     inside the real <i>Makefile</i> that will do everything (download,
 451     compile, install), and that we study below. Back to
 452     <code>Makefile.in</code>, here is an example :</p>
 453
 454 <pre>
 455 ifeq ($(strip $(BR2_PACKAGE_FOO)),y)
 456 TARGETS+=foo
 457 endif
 458 </pre>
 459
 460    <p>As you can see, this short <i>Makefile</i> simply adds the
 461    target <code>foo</code> to the list of targets handled by Buildroot
 462    if software <i>foo</i> was selected using the configuration tool.</p>
 463
 464    <h3>The real <i>Makefile</i></h3>
 465
 466    <p>Finally, here's the hardest part. Create a file named
 467    <code>foo.mk</code>. It will contain the <i>Makefile</i> rules that
 468    are in charge of downloading, configuring, compiling and installing
 469    the software. Below is an example that we will comment
 470    afterwards.</p>
 471
 472 <pre>
 473      1  #############################################################
 474      2  #
 475      3  # foo
 476      4  #
 477      5  #############################################################
 478      6  FOO_VERSION:=1.0
 479      7  FOO_SOURCE:=less-$(FOO_VERSION).tar.gz
 480      8  FOO_SITE:=http://www.foosoftware.org/downloads
 481      9  FOO_DIR:=$(BUILD_DIR)/less-$(FOO_VERSION)
 482     10  FOO_BINARY:=foo
 483     11  FOO_TARGET_BINARY:=usr/bin/foo
 484     12
 485     13  $(DL_DIR)/$(FOO_SOURCE):
 486     14          $(WGET) -P $(DL_DIR) $(FOO_SITE)/$(FOO_SOURCE)
 487     15
 488     16  $(FOO_DIR)/.source: $(DL_DIR)/$(FOO_SOURCE)
 489     17          zcat $(DL_DIR)/$(FOO_SOURCE) | tar -C $(BUILD_DIR) $(TAR_OPTIONS) -
 490     18          touch $(FOO_DIR)/.source
 491     19
 492     20  $(FOO_DIR)/.configured: $(FOO_DIR)/.source
 493     21          (cd $(FOO_DIR); \
 494     22                  $(TARGET_CONFIGURE_OPTS) \
 495     23                  CFLAGS="$(TARGET_CFLAGS)" \
 496     24                  ./configure \
 497     25                  --target=$(GNU_TARGET_NAME) \
 498     26                  --host=$(GNU_TARGET_NAME) \
 499     27                  --build=$(GNU_HOST_NAME) \
 500     28                  --prefix=/usr \
 501     29                  --sysconfdir=/etc \
 502     30          );
 503     31          touch $(FOO_DIR)/.configured;
 504     32
 505     33  $(FOO_DIR)/$(FOO_BINARY): $(FOO_DIR)/.configured
 506     34          $(MAKE) CC=$(TARGET_CC) -C $(FOO_DIR)
 507     35
 508     36  $(TARGET_DIR)/$(FOO_TARGET_BINARY): $(FOO_DIR)/$(FOO_BINARY)
 509     37          $(MAKE) prefix=$(TARGET_DIR)/usr -C $(FOO_DIR) install
 510     38          rm -Rf $(TARGET_DIR)/usr/man
 511     39
 512     40  foo: uclibc ncurses $(TARGET_DIR)/$(FOO_TARGET_BINARY)
 513     41
 514     42  foo-source: $(DL_DIR)/$(FOO_SOURCE)
 515     43
 516     44  foo-clean:
 517     45          $(MAKE) prefix=$(TARGET_DIR)/usr -C $(FOO_DIR) uninstall
 518     46          -$(MAKE) -C $(FOO_DIR) clean
 519     47
 520     48  foo-dirclean:
 521     49          rm -rf $(FOO_DIR)
 522     50
 523 </pre>
 524
 525     <p>First of all, this <i>Makefile</i> example works for a single
 526     binary software. For other software such as libraries or more
 527     complex stuff with multiple binaries, it should be adapted. Look at
 528     the other <code>*.mk</code> files in the <code>package</code>
 529     directory.</p>
 530
 531     <p>At lines 6-11, a couple of useful variables are defined :</p>
 532
 533     <ul>
 534
 535      <li><code>FOO_VERSION</code> : The version of <i>foo</i> that
 536      should be downloaded.</li>
 537
 538      <li><code>FOO_SOURCE</code> : The name of the tarball of
 539      <i>foo</i> on the download website of FTP site. As you can see
 540      <code>FOO_VERSION</code> is used.</li>
 541
 542      <li><code>FOO_SITE</code> : The HTTP or FTP site from which
 543      <i>foo</i> archive is downloaded. It must include the complete
 544      path to the directory where <code>FOO_SOURCE</code> can be
 545      found.</li>
 546
 547      <li><code>FOO_DIR</code> : The directory into which the software
 548      will be configured and compiled. Basically, it's a subdirectory
 549      of <code>BUILD_DIR</code> which is created upon decompression of
 550      the tarball.</li>
 551
 552      <li><code>FOO_BINARY</code> : Software binary name. As said
 553      previously, this is an example for a single binary software.</li>
 554
 555      <li><code>FOO_TARGET_BINARY</code> : The full path of the binary
 556      inside the target filesystem.</li>
 557
 558     </ul>
 559
 560     <p>Lines 13-14 defines a target that downloads the tarball from
 561     the remote site to the download directory
 562     (<code>DL_DIR</code>).</p>
 563
 564     <p>Lines 16-18 defines a target and associated rules that
 565     uncompress the downloaded tarball. As you can see, this target
 566     depends on the tarball file, so that the previous target (line
 567     13-14) is called before executing the rules of the current
 568     target. Uncompressing is followed by <i>touching</i> a hidden file
 569     to mark the software has having been uncompressed. This trick is
 570     used everywhere in Buildroot <i>Makefile</i> to split steps
 571     (download, uncompress, configure, compile, install) while still
 572     having correct dependencies.</p>
 573
 574     <p>Lines 20-31 defines a target and associated rules that
 575     configures the software. It depends on the previous target (the
 576     hidden <code>.source</code> file) so that we are sure the software has
 577     been uncompressed. In order to configure it, it basically runs the
 578     well-known <code>./configure</code>script. As we may be doing
 579     cross-compilation, <code>target</code>, <code>host</code> and
 580     <code>build</code> arguments are given. The prefix is also set to
 581     <code>/usr</code>, not because the software will be installed in
 582     <code>/usr</code> on your host system, but in the target
 583     filesystem. Finally it creates a <code>.configured</code> file to
 584     mark the software as configured.</p>
 585
 586     <p>Lines 33-34 defines a target and a rule that compiles the
 587     software. This target will create the binary file in the
 588     compilation directory, and depends on the software being already
 589     configured (hence the reference to the <code>.configured</code>
 590     file). It basically runs <code>make</code> inside the source
 591     directory.</p>
 592
 593     <p>Lines 36-38 defines a target and associated rules that install
 594     the software inside the target filesystem. It depends on the
 595     binary file in the source directory, to make sure the software has
 596     been compiled. It uses the <code>install</code> target of the
 597     software <code>Makefile</code> by passing a <code>prefix</code>
 598     argument, so that the <code>Makefile</code> doesn't try to install
 599     the software inside host <code>/usr</code> but inside target
 600     <code>/usr</code>. After the installation, the
 601     <code>/usr/man</code> directory inside the target filesystem is
 602     removed to save space.</p>
 603
 604     <p>Line 40 defines the main target of the software, the one
 605     referenced in the <code>Makefile.in</code> file. This targets
 606     should first of all depends on the dependecies of the software (in
 607     our example, <i>uclibc</i> and <i>ncurses</i>), and then to the
 608     final binary. This last dependency will call all previous
 609     dependencies in the right order. </p>
 610
 611     <p>Line 42 defines a simple target that only downloads the code
 612     source. This is not used during normal operation of Buildroot, but
 613     might be useful.</p>
 614
 615     <p>Lignes 44-46 define a simple target to clean the software build
 616     by calling the <i>Makefiles</i> with the appropriate option.</p>
 617
 618     <p>Lines 48-49 define a simple target to completely remove the
 619     directory in which the software was uncompressed, configured and
 620     compiled.</p>
 621
 622     <h3>Conclusion</h3>
 623
 624     <p>As you can see, adding a software to buildroot is simply a
 625     matter of writing a <i>Makefile</i> using an already existing
 626     example and to modify it according to the compilation process of
 627     the software.</p>
 628
 629     <p>If you package software that might be useful for other persons,
 630     don't forget to send a patch to Buildroot developers !</p>
 631
 632      <h2><a name="links" id="links"></a>Ressources</h2>
 633
 634     <p>To learn more about Buildroot you can visit these
 635     websites:</p>
 636
 637     <ul>
 638       <li><a href="http://www.uclibc.org/">http://www.uclibc.org/</a></li>
 639       <li><a href="http://www.busybox.net/">http://www.busybox.net/</a></li>
 640     </ul>
 641
 642   </div>
 643 </body>
 644 </html>