openwrt/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>OpenWrt 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>OpenWrt Buildroot</h1>
  16     </div>
  17
  18     <p>Usage and documentation by Felix Fietkau and Waldemar Brodkorb, based on uClibc Buildroot
  19     documentation by Thomas Petazzoni. Contributions from Karsten Kruse,
  20     Ned Ludd, Martin Herren.</p>
  21
  22     <p><small>Last modification : $Id$</small></p>
  23
  24     <ul>
  25       <li><a href="#about">About OpenWrt Buildroot</a></li>
  26       <li><a href="#download">Obtaining OpenWrt Buildroot</a></li>
  27       <li><a href="#using">Using OpenWrt Buildroot</a></li>
  28       <li><a href="#custom_targetfs">Customizing the target filesystem</a></li>
  29       <li><a href="#custom_busybox">Customizing the Busybox
  30       configuration</a></li>
  31       <li><a href="#custom_uclibc">Customizing the uClibc
  32       configuration</a></li>
  33       <li><a href="#buildroot_innards">How OpenWrt Buildroot works</a></li>
  34       <li><a href="#using_toolchain">Using the uClibc toolchain</a></li>
  35       <li><a href="#toolchain_standalone">Using the uClibc toolchain
  36       outside of Buildroot</a></li>
  37       <li><a href="#downloaded_packages">Location of downloaded packages</a></li>
  38       <li><a href="#add_software">Extending OpenWrt with more Software</a></li>
  39       <li><a href="#links">Ressources</a></li>
  40     </ul>
  41
  42     <h2><a name="about" id="about"></a>About OpenWrt Buildroot</h2>
  43
  44     <p>OpenWrt 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     Wireless Router. 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>A compilation toolchain is the set of tools that allows to
  51     compile code for your system. It consists of a compiler (in our
  52     case, <code>gcc</code>), binary utils like assembler and linker
  53     (in our case, <code>binutils</code>) and a C standard library (for
  54     example <a href="http://www.gnu.org/software/libc/libc.html">GNU
  55     Libc</a>, <a href="http://www.uclibc.org">uClibc</a> or <a
  56     href="http://www.fefe.de/dietlibc/">dietlibc</a>). The system
  57     installed on your development station certainly already has a
  58     compilation toolchain that you can use to compile application that
  59     runs on your system. If you're using a PC, your compilation
  60     toolchain runs on an x86 processor and generates code for a x86
  61     processor. Under most Linux systems, the compilation toolchain
  62     uses the GNU libc as C standard library.  This compilation
  63     toolchain is called the "host compilation toolchain", and more
  64     generally, the machine on which it is running, and on which you're
  65     working is called the "host system". The compilation toolchain is
  66     provided by your distribution, and OpenWrt Buildroot has nothing to do
  67     with it.</p>
  68
  69     <p>As said above, the compilation toolchain that comes with your system
  70     runs and generates code for the processor of your host system. As your
  71     embedded system has a different processor, you need a cross-compilation
  72     toolchain: it's a compilation toolchain that runs on your host system but
  73     that generates code for your target system (and target processor). For
  74     example, if your host system uses x86 and your target system uses MIPS, the
  75     regular compilation toolchain of your host runs on x86 and generates code
  76     for x86, while the cross-compilation toolchain runs on x86 and generates
  77     code for MIPS.</p>
  78
  79     <p>You might wonder why such a tool is needed when you can compile
  80     <code>gcc</code>, <code>binutils</code>, uClibc and all the tools by hand.
  81     Of course, doing so is possible. But dealing with all configure options,
  82     with all problems of every <code>gcc</code> or <code>binutils</code>
  83     version is very time-consuming and uninteresting. OpenWrt Buildroot automates this
  84     process through the use of Makefiles, and has a collection of patches for
  85     each <code>gcc</code> and <code>binutils</code> version to make them work
  86     on the MIPS architecture of most Wireless Routers.</p>
  87
  88     <h2><a name="download" id="download"></a>Obtaining OpenWrt Buildroot</h2>
  89
  90     <p>OpenWrt Buildroot is available via CVS - Concurrent Version System.
  91     For any kind of development you should get the latest version from cvs via:</p>
  92 <pre>
  93  $ cvs -d:pserver:anonymous@openwrt.org:/openwrt co openwrt
  94 </pre>
  95
  96     <h2><a name="using" id="using"></a>Using OpenWrt Buildroot</h2>
  97
  98     <p>OpenWrt Buildroot has a nice configuration tool similar to the one you can find
  99     in the Linux Kernel (<a href="http://www.kernel.org/">http://www.kernel.org/</a>)
 100     or in Busybox (<a href="http://www.busybox.org/">http://www.busybox.org/</a>).
 101     Note that you can run everything as a normal user. There is no need to be root to
 102     configure and use the Buildroot. The first step is to run the configuration
 103     assistant:</p>
 104
 105 <pre>
 106  $ make menuconfig
 107 </pre>
 108
 109     <p>For each entry of the configuration tool, you can find associated help
 110     that describes the purpose of the entry.</p>
 111
 112     <p>Once everything is configured, the configuration tool has generated a
 113     <code>.config</code> file that contains the description of your
 114     configuration. It will be used by the Makefiles to do what's needed.</p>
 115
 116     <p>Let's go:</p>
 117
 118 <pre>
 119  $ make
 120 </pre>
 121
 122     <p>This command will download, configure and compile all the selected
 123     tools, and finally generate target firmware images and additional packages
 124     (depending on your selections in <code>make menuconfig</code>.
 125     All the target files can be found in the <code>bin/</code> subdirectory.
 126     You can compile firmware images containing two different filesystem types:
 127     <ul>
 128         <li>jffs2</li>
 129         <li>squashfs</li>
 130     </ul>
 131     <p><code>jffs2</code> contains a writable root filesystem, which will expand to
 132     the size of your flash image. Note: if you use the generic firmware image, you
 133     need to pick the right image for your flash size, because of different
 134     eraseblock sizes.</p>
 135
 136     <p><code>squashfs</code> contains a read-only root filesystem using a modified
 137     <code>squashfs</code> filesystem with LZMA compression. When booting it, you can
 138     create a writable second filesystem, which will contain your modifications to
 139     the root filesystem, including the packages you install.
 140
 141     <h2><a name="custom_targetfs" id="custom_targetfs"></a>Customizing the
 142     target filesystem</h2>
 143
 144     <p>There are two ways to customize the resulting target filesystem:</p>
 145
 146     <ul>
 147       <li>Customize the target filesystem directly, and rebuild the image. The
 148       target filesystem is available under <code>build_ARCH/root/</code> where
 149       <code>ARCH</code> is the chosen target architecture, usually mipsel.
 150       You can simply make your changes here, and run make target_install afterwards,
 151       which will rebuild the target filesystem image. This method allows to do
 152       everything on the target filesystem, but if you decide to rebuild your toolchain,
 153       tools or packages, these changes will be lost.</li>
 154
 155       <li>Customize the target filesystem skeleton, available under
 156       <code>target/default/target_skeleton/</code>. You can customize
 157       configuration files or other stuff here. However, the full file hierarchy
 158       is not yet present, because it's created during the compilation process.
 159       So you can't do everything on this target filesystem skeleton, but
 160       changes to it remains even when you completely rebuild the cross-compilation
 161       toolchain and the tools.<br />
 162     </ul>
 163
 164     <h2><a name="custom_busybox" id="custom_busybox"></a>Customizing the
 165     Busybox configuration</h2>
 166
 167     <p>Busybox is very configurable, and you may want to customize it.
 168     Its configuration is completely integrated into the main menuconfig system.
 169     You can find it under "OpenWrt Package Selection" =&gt; "Busybox Configuration"</p>
 170
 171     <h2><a name="custom_uclibc" id="custom_uclibc"></a>Customizing the uClibc
 172     configuration</h2>
 173
 174     <p>Just like <a href="#custom_busybox">BusyBox</a>, <a
 175     href="http://www.uclibc.org">uClibc</a> offers a lot of
 176     configuration options. They allow to select various
 177     functionalities, depending on your needs and limitations.</p>
 178
 179     <p>The easiest way to modify the configuration of uClibc is to
 180     follow these steps :</p>
 181
 182     <ol>
 183
 184       <li>Make a first compilation of buildroot without trying to
 185       customize uClibc.</li>
 186
 187       <li>Go into the directory
 188       <code>toolchain_build_ARCH/uClibc/</code> and run <code>make
 189       menuconfig</code>. The nice configuration assistant, similar to
 190       the one used in the Linux Kernel appears. Make
 191       your configuration as appropriate.</li>
 192
 193       <li>Copy the <code>.config</code> file to
 194       <code>toolchain/uClibc/uClibc.config</code> or
 195       <code>toolchain/uClibc/uClibc.config-locale</code>. The former
 196       is used if you haven't selected locale support in the Buildroot
 197       configuration, and the latter is used if you have selected
 198       locale support.</li>
 199
 200       <li>Run the compilation again.</li>
 201
 202     </ol>
 203
 204     <p>Otherwise, you can simply change
 205     <code>toolchain/uClibc/uClibc.config</code> or
 206     <code>toolchain/uClibc/uClibc.config-locale</code> without running
 207     the configuration assistant.</p>
 208
 209     <h2><a name="buildroot_innards" id="buildroot_innards"></a>How OpenWrt Buildroot
 210     works</h2>
 211
 212     <p>As said above, OpenWrt is basically a set of Makefiles that download,
 213     configure and compiles software with the correct options. It also includes
 214     some patches for various software, mainly the ones involved in the
 215     cross-compilation tool chain (<code>gcc</code>, <code>binutils</code> and
 216     uClibc).</p>
 217
 218     <p>There is basically one Makefile per software, and they are named <code>Makefile</code>.
 219     Makefiles are split into three sections:</p>
 220
 221     <ul>
 222       <li><b>package</b> (in the <code>package/</code> directory) contains the
 223       Makefiles and associated files for all user-space tools that Buildroot
 224       can compile and add to the target root filesystem. There is one
 225       sub-directory per tool.</li>
 226
 227       <li><b>toolchain</b> (in the <code>toolchain/</code> directory) contains
 228       the Makefiles and associated files for all software related to the
 229       cross-compilation toolchain : <code>binutils</code>, <code>ccache</code>,
 230       <code>gcc</code>, <code>gdb</code>, <code>kernel-headers</code> and
 231       <code>uClibc</code>.</li>
 232
 233       <li><b>target</b> (in the <code>target</code> directory) contains the
 234       Makefiles and associated files for software related to the generation of
 235       the target root filesystem image and the linux kernel for the different
 236       system on a chip boards, used in the Wireless Routers.
 237       Two types of filesystems are supported
 238       : jffs2 and squashfs.
 239     </ul>
 240
 241     <p>Each directory contains at least 2 files :</p>
 242
 243     <ul>
 244       <li><code>Makefile</code> is the Makefile that downloads, configures,
 245       compiles and installs the software <code>something</code>.</li>
 246
 247       <li><code>Config.in</code> is a part of the configuration tool
 248       description file. It describes the option related to the current
 249       software.</li>
 250     </ul>
 251
 252     <p>The main Makefile do the job through the following steps (once the
 253     configuration is done):</p>
 254
 255     <ol>
 256       <li>Create the download directory (<code>dl/</code> by default). This is
 257       where the tarballs will be downloaded. It is interesting to know that the
 258       tarballs are in this directory because it may be useful to save them
 259       somewhere to avoid further downloads.</li>
 260
 261       <li>Create the build directory (<code>build_ARCH/</code> by default,
 262       where <code>ARCH</code> is your architecture). This is where all
 263       user-space tools while be compiled.</li>
 264
 265       <li>Create the toolchain build directory
 266       (<code>toolchain_build_ARCH/</code> by default, where <code>ARCH</code>
 267       is your architecture). This is where the cross compilation toolchain will
 268       be compiled.</li>
 269
 270       <li>Setup the staging directory (<code>staging_dir_ARCH/</code> by
 271       default). This is where the cross-compilation toolchain will be
 272       installed. If you want to use the same cross-compilation toolchain for
 273       other purposes, such as compiling third-party applications, you can add
 274       <code>staging_dir_ARCH/bin</code> to your PATH, and then use
 275       <code>arch-linux-gcc</code> to compile your application. In order to
 276       setup this staging directory, it first removes it, and then it creates
 277       various subdirectories and symlinks inside it.</li>
 278
 279       <li>Create the target directory (<code>build_ARCH/root/</code> by
 280       default) and the target filesystem skeleton. This directory will contain
 281       the final root filesystem. To set it up, it first deletes it, then it
 282       copies the skeleton available in  <code>target/default/target_skeleton</code>
 283       and then removes useless <code>CVS/</code> directories.</li>
 284
 285       <li>Call the <code>prepare</code>, <code>compile</code> and <code>install</code>
 286       targets for the subdirectories <code>toolchain</code>, <code>package</code>
 287       and <code>target</code></li>
 288     </ol>
 289
 290     <h2><a name="using_toolchain" id="using_toolchain"></a>Using the
 291     uClibc toolchain</h2>
 292
 293     <p>You may want to compile your own programs or other software
 294     that are not packaged in OpenWrt. In order to do this, you can
 295     use the toolchain that was generated by the Buildroot.</p>
 296
 297     <p>The toolchain generated by the Buildroot by default is located in
 298     <code>staging_dir_ARCH</code>. The simplest way to use it
 299     is to add <code>staging_dir_ARCH/bin/</code> to your PATH
 300     environment variable, and then to use
 301     <code>arch-linux-gcc</code>, <code>arch-linux-objdump</code>,
 302     <code>arch-linux-ld</code>, etc.</p>
 303
 304     <p>For example, you may add the following to your
 305     <code>.bashrc</code> (considering you're building for the MIPS
 306     architecture and that Buildroot is located in
 307     <code>~/openwrt/</code>) :</p>
 308
 309 <pre>
 310 export PATH=$PATH:~/openwrt/staging_dir_mipsel/bin/
 311 </pre>
 312
 313     <p>Then you can simply do :</p>
 314
 315 <pre>
 316 mipsel-linux-uclibc-gcc -o foo foo.c
 317 </pre>
 318
 319     <p><b>Important</b> : do not try to move the toolchain to an other
 320     directory, it won't work. There are some hard-coded paths in the
 321     <i>gcc</i> configuration. If the default toolchain directory
 322     doesn't suit your needs, please refer to the <a
 323     href="#toolchain_standalone">Using the uClibc toolchain outside of
 324     buildroot</a> section.</p>
 325
 326     <h2><a name="toolchain_standalone" id="toolchain_standalone"></a>Using the
 327     uClibc toolchain outside of buildroot</h2>
 328
 329     <p>By default, the cross-compilation toolchain is generated inside
 330     <code>staging_dir_ARCH/</code>. But sometimes, it may be useful to
 331     install it somewhere else, so that it can be used to compile other programs
 332     or by other users. Moving the <code>staging_dir_ARCH/</code>
 333     directory elsewhere is <b>not possible</b>, because they are some hardcoded
 334     paths in the toolchain configuration.</p>
 335
 336     <p>If you want to use the generated toolchain for other purposes,
 337     you can configure Buildroot to generate it elsewhere using the
 338     option of the configuration tool : <code>Build options -&gt;
 339     Toolchain and header file location</code>, which defaults to
 340     <code>staging_dir_ARCH/</code>.</p>
 341
 342     <h2><a name="downloaded_packages"
 343     id="downloaded_packages"></a>Location of downloaded packages</h2>
 344
 345     <p>It might be useful to know that the various tarballs that are
 346     downloaded by the <i>Makefiles</i> are all stored in the
 347     <code>DL_DIR</code> which by default is the <code>dl</code>
 348     directory. It's useful for example if you want to keep a complete
 349     version of Buildroot which is known to be working with the
 350     associated tarballs. This will allow you to regenerate the
 351     toolchain and the target filesystem with exactly the same
 352     versions.</p>
 353
 354     <h2><a name="add_software" id="add_software"></a>Extending OpenWrt with
 355     more software</h2>
 356
 357     <p>This section will only consider the case in which you want to
 358     add user-space software.</p>
 359
 360     <h3>Package directory</h3>
 361
 362     <p>First of all, create a directory under the <code>package</code>
 363     directory for your software, for example <code>foo</code>.</p>
 364
 365     <h3><code>Config.in</code> file</h3>
 366
 367     <p>Then, create a file named <code>Config.in</code>. This file
 368     will contain the portion of options description related to our
 369     <code>foo</code> software that will be used and displayed in the
 370     configuration tool. It should basically contain :</p>
 371
 372 <pre>
 373 config BR2_PACKAGE_FOO
 374         tristate "foo - some nice tool"
 375         default m if CONFIG_DEVEL
 376         help
 377              This is a comment that explains what foo is.
 378 </pre>
 379
 380     <p>If you depend on other software or library inside the Buildroot, it
 381     is important that you automatically select these packages in your
 382     <code>Config.in</code>. Example if foo depends on bar library:
 383     </p>
 384 <pre>
 385 config BR2_PACKAGE_FOO
 386         tristate "foo - some nice tool"
 387         default m if CONFIG_DEVEL
 388         select BR2_PACKAGE_LIBBAR
 389         help
 390         This is a comment that explains what foo is.
 391 </pre>
 392
 393     <p>Of course, you can add other options to configure particular
 394     things in your software.</p>
 395
 396     <h3><code>Config.in</code> in the package directory</h3>
 397
 398     <p>To add your package to the configuration tool, you need
 399     to add the following line to <code>package/Config.in</code>,
 400     please add it to a section, which fits the purpose of foo:
 401
 402 <pre>
 403 comment "Networking"
 404 source "package/foo/Config.in"
 405 </pre>
 406
 407     <h3><code>Makefile</code> in the package directory</h3>
 408
 409     <p>To add your package to the build process, you need to edit
 410     the Makefile in the <code>package/</code> directory. Locate the
 411     lines that look like the following:</p>
 412
 413 <pre>
 414 package-$(BR2_PACKAGE_FOO) += foo
 415 </pre>
 416
 417    <p>As you can see, this short line simply adds the target
 418    <code>foo</code> to the list of targets handled by OpenWrt Buildroot.</p>
 419
 420    <p>In addition to the default dependencies, you make your package
 421    depend on another package (e.g. a library) by adding a line:
 422
 423 <pre>
 424 foo-compile: bar-compile
 425 </pre>
 426
 427    <h3>The ipkg control file</h3>
 428    <p>Additionally, you need to create a control file which contains
 429    information about your package, readable by the <i>ipkg</i> package
 430    utility. It should be created as file:
 431    <code>package/foo/ipkg/foo.control</code></p>
 432
 433    <p>The file looks like this</p>
 434
 435 <pre>
 436      1  Package: foo
 437      2  Priority: optional
 438      3  Section: net
 439      4  Maintainer: Foo Software &lt;foo@foosoftware.com&gt;
 440      5  Source: http://foosoftware.com
 441      6  Depends: libbar
 442      7  Description: Package Description
 443 </pre>
 444
 445    <p>You can skip the usual <code>Version:</code> and <code>Architecture</code>
 446    fields, as they will be generated by the <code>make-ipkg-dir.sh</code> script
 447    called from your Makefile. The Depends field is important, so that ipkg will
 448    automatically fetch all dependend software on your target system.</p>
 449
 450    <h3>The real <i>Makefile</i></h3>
 451
 452    <p>Finally, here's the hardest part. Create a file named
 453    <code>Makefile</code>. It will contain the <i>Makefile</i> rules that
 454    are in charge of downloading, configuring, compiling and installing
 455    the software. Below is an example that we will comment
 456    afterwards.</p>
 457
 458 <pre>
 459      1  # $Id$
 460      2  include $(TOPDIR)/rules.mk
 461      3  PKG_NAME:=foo
 462      4  PKG_VERSION:=1.0
 463      5  PKG_RELEASE:=1
 464      6  PKG_MD5SUM:=4584f226523776a3cdd2fb6f8212ba8d
 465      8  PKG_SOURCE:=$(PKG_NAME)-$(PKG_VERSION).tar.gz
 466      9  PKG_SOURCE_URL:=http://www.foosoftware.org/downloads
 467     10  PKG_DIR:=$(BUILD_DIR)/$(PKG_NAME)-$(PKG_VERSION)
 468     11  PKG_IPK:=$(PACKAGE_DIR)/$(PKG_NAME)_$(PKG_VERSION)-$(PKG_RELEASE)_$(ARCH).ipk
 469     12  PKG_IPK_DIR:=$(PKG_DIR)/ipkg
 470     13
 471     14  $(DL_DIR)/$(PKG_SOURCE):
 472     15          $(SCRIPT_DIR)/download.pl $(DL_DIR) $(PKG_SOURCE) $(PKG_MD5SUM) $(PKG_SOURCE_URL)
 473     16
 474     17  $(PKG_DIR)/.source: $(DL_DIR)/$(PKG_SOURCE)
 475     18          zcat $(DL_DIR)/$(PKG_SOURCE) | tar -C $(BUILD_DIR) $(TAR_OPTIONS) -
 476     19          touch $(PKG_DIR)/.source
 477     20
 478     21  $(PKG_DIR)/.configured: $(PKG_DIR)/.source
 479     22          (cd $(PKG_DIR); \
 480     23                  $(TARGET_CONFIGURE_OPTS) \
 481     24                  CFLAGS="$(TARGET_CFLAGS)" \
 482     25                  ./configure \
 483     26                  --target=$(GNU_TARGET_NAME) \
 484     27                  --host=$(GNU_TARGET_NAME) \
 485     28                  --build=$(GNU_HOST_NAME) \
 486     29                  --prefix=/usr \
 487     30                  --sysconfdir=/etc \
 488     31          );
 489     32          touch $(PKG_DIR)/.configured;
 490     33
 491     34  $(PKG_DIR)/$(PKG_NAME): $(PKG_DIR)/.configured
 492     35          $(MAKE) CC=$(TARGET_CC) -C $(PKG_DIR)
 493     36
 494     37  $(PKG_IPK): $(PKG_DIR)/$(PKG_NAME)
 495     38          $(SCRIPT_DIR)/make-ipkg-dir.sh $(PKG_IPK_DIR) $(PKG_NAME).control $(PKG_VERSION)-$(PKG_RELEASE) $(ARCH)
 496     39          $(MAKE) prefix=$(PKG_IPK_DIR)/usr -C $(PKG_DIR) install
 497     40          rm -Rf $(PKG_IPK_DIR)/usr/man
 498     41          $(IPKG_BUILD) $(PKG_IPK_DIR) $(PACKAGE_DIR)
 499     42
 500     43  $(IPKG_STATE_DIR)/info/$(PKG_NAME).list: $(PKG_IPK)
 501     44          $(IPKG) install $(PKG_IPK)
 502     45
 503     46  prepare: $(PKG_DIR)/.source
 504     47  compile: $(PKG_IPK)
 505     48  install: $(IPKG_STATE_DIR)/info/$(PKG_NAME).list
 506     49  clean:
 507     50          rm -rf $(PKG_DIR)
 508     51          rm -f $(PKG_IPK)
 509 </pre>
 510
 511     <p>First of all, this <i>Makefile</i> example works for a single
 512     binary software. For other software such as libraries or more
 513     complex stuff with multiple binaries, it should be adapted. Look at
 514     the other <code>Makefile</code> files in the <code>package</code>
 515     directory.</p>
 516
 517     <p>At lines 3-12, a couple of useful variables are defined :</p>
 518
 519     <ul>
 520      <li><code>PKG_NAME</code> : The package name, e.g. <i>foo</i>.</li>
 521
 522      <li><code>PKG_VERSION</code> : The version of the package that
 523      should be downloaded.</li>
 524
 525      <li><code>PKG_RELEASE</code> : The release number that will be
 526      appended to the version number of your <i>ipkg</i> package.
 527
 528      <li><code>PKG_MD5SUM</code> : The md5sum of the software archive.
 529
 530      <li><code>PKG_SOURCE</code> : The name of the tarball of
 531      your package on the download website of FTP site. As you can see
 532      <code>PKG_NAME</code> and <code>PKG_VERSION</code> are used.</li>
 533
 534      <li><code>PKG_SOURCE_URL</code> : Space separated list of the HTTP
 535      or FTP sites from which the archive is downloaded. It must include the complete
 536      path to the directory where <code>FOO_SOURCE</code> can be
 537      found.</li>
 538
 539      <li><code>PKG_DIR</code> : The directory into which the software
 540      will be configured and compiled. Basically, it's a subdirectory
 541      of <code>BUILD_DIR</code> which is created upon decompression of
 542      the tarball.</li>
 543
 544      <li><code>PKG_IPK</code> : The resulting <i>ipkg</i> package
 545
 546     </ul>
 547
 548     <p>Lines 14-15 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 17-19 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     14-15) 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 21-32 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 34-35 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 37-41 defines a target and associated rules that create
 582     the <i>ipkg</i> package which can optionally be embedded into
 583     the resulting firmware image. It depends on the binary file in
 584     the source directory, to make sure the software has been compiled.
 585     It uses the make-ipkg-dir.sh script, which will create the ipkg
 586     build directory for your package, copy your control file into
 587     that directory and add version and architecture information.
 588     Then it calls the <code>install</code> target of the
 589     software <code>Makefile</code> by passing a <code>prefix</code>
 590     argument, so that the <code>Makefile</code> doesn't try to install
 591     the software inside host <code>/usr</code> but inside target
 592     <code>/usr</code>. After the installation, the
 593     <code>/usr/man</code> directory inside the target filesystem is
 594     removed to save space.
 595     Finally <code>IPKG_BUILD</code> is called to create the package.</p>
 596
 597     <p>Line 43 and 44 define the installation target of your package,
 598     which will embed the software into the target filesystem.</p>
 599
 600     <p>Lines 46-51 define the main targets that the Makefile in the
 601     <code>package</code> dir calls.
 602     <ul>
 603       <li><code>prepare</code> : Download and unpack the source</li>
 604       <li><code>compile</code> : Compile the source and create the package</li>
 605       <li><code>install</code> : Embed the package into the target filesystem</li>
 606       <li><code>clean</code> : Remove all the files created by the build process</li>
 607     </ul></p>
 608
 609     <h3>Conclusion</h3>
 610
 611     <p>As you can see, adding a software to buildroot is simply a
 612     matter of writing a <i>Makefile</i> using an already existing
 613     example and to modify it according to the compilation process of
 614     the software.</p>
 615
 616     <p>If you package software that might be useful for other persons,
 617     don't forget to send a patch to OpenWrt developers !</p>
 618
 619      <h2><a name="links" id="links"></a>Resources</h2>
 620
 621     <p>To learn more about OpenWrt Buildroot you can visit this
 622     website: <a href="http://openwrt.org/">http://openwrt.org/</a></p>
 623
 624   </div>
 625 </body>
 626 </html>