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