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