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