openwrt/docs/buildroot-documentation.html

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