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