source: branches/whiterussian/openwrt/docs/buildroot-documentation.html @ 2205

Last change on this file since 2205 was 2205, checked in by kaloz, 11 years ago

fix path for target skeleton in the buildroot documentation

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 28.6 KB
Line 
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    <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>CVS/</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>
325export PATH=$PATH:~/openwrt/staging_dir_mipsel/bin/
326</pre>
327
328    <p>Then you can simply do :</p>
329
330<pre>
331mipsel-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>
388config 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>
400config 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>
418comment "Networking"
419source "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>
429package-$(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>
439foo-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
629explain what you have to do, to have your kernel module installable as
630an 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
635build_mipsel/linux/.config. We are assuming, that you already had your
636kernel 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
643And copy it, so your changes are not getting lost, when doing a 'make
644dirclean'. Here we assume that you are compiling for Broadcom chipset
645based 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
653target/linux/Config.in, e.g.
654
655<pre>
656config 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
666target/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
676Where CONFIG_USB_KEYB is the kernel option, USB_KEYBOARD is the last
677part of BR2_PACKAGE_KMOD_USB_KEYBOARD and usb-kbd is part of the
678filename 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>
685Package: kmod-usb-kbd
686Priority: optional
687Section: sys
688Maintainer: Markus Becker &lt;mab@comnets.uni-bremen.de&gt;
689Source: buildroot internal
690Description: 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>
Note: See TracBrowser for help on using the repository browser.