fix package name in template call, remove unneeded patch,
[openwrt.git] / 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" />
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:
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 <p>If you want other targets to be executed at <code>compile</code>,
591 <code>install</code> or <code>clean</code> time (e.g. for installing
592 a library into the staging dir), just create the targets (usually
593 <code>install-dev</code> and <code>uninstall-dev</code>) and enable
594 them like this:
595 <pre>
596 compile-targets: install-dev
597 clean-targets: uninstall-dev
598 </pre>
599
600 <h3>Conclusion</h3>
601
602 <p>As you can see, adding a software to buildroot is simply a
603 matter of writing a <i>Makefile</i> using an already existing
604 example and to modify it according to the compilation process of
605 the software.</p>
606
607 <p>If you package software that might be useful for other persons,
608 don't forget to send a patch to OpenWrt developers!
609 Use the mail address: openwrt-devel@openwrt.org
610 </p>
611
612 <h2><a name="links" id="links"></a>Resources</h2>
613
614 <p>To learn more about OpenWrt, you can visit this website:
615 <a href="http://openwrt.org/">http://openwrt.org/</a></p>
616
617 </div>
618
619 <div class="main">
620 <div class="titre">
621 <h1>OpenWrt Kernel Module Creation Howto</h1>
622 </div>
623
624 <h2><a name="about_module" id="about_module"></a>About OpenWrt Kernel Module Compilation</h2>
625
626 <p>You are planning to compile a kernel module? This howto will
627 explain what you have to do, to have your kernel module installable as
628 an ipkg.</p>
629
630 <h2><a name="kernel" id="kernel"></a>Enable the kernel options</h2>
631
632 <p>Enable the kernel options you want by modifying
633 build_mipsel/linux/.config. We are assuming, that you already had your
634 kernel compiled once here. You can do the modification by hand or by
635
636 <pre>
637 $ cd build_mipsel/linux
638 $ make menuconfig
639 </pre>
640
641 And copy it, so your changes are not getting lost, when doing a 'make
642 dirclean'. Here we assume that you are compiling for Broadcom chipset
643 based devices:
644
645 <pre> $ cp .config ../../../target/linux/linux-2.4/config/brcm </pre>
646
647 </p>
648 <h2><a name="buildroot_option" id="buildroot_option"></a>Create a buildroot option</h2>
649
650 <p>Create a buildroot option by modifying/inserting into
651 target/linux/Config.in, e.g.
652
653 <pre>
654 config BR2_PACKAGE_KMOD_USB_KEYBOARD
655 tristate "Support for USB keyboards"
656 default m
657 depends BR2_PACKAGE_KMOD_USB_CONTROLLER
658 </pre>
659 </p>
660
661 <h2><a name="binary" id="binary"></a>Define the binary files for the kernel module</h2>
662
663 <p>Define the binary files for the kernel module by modifying/inserting into
664 target/linux/linux-2.4/Makefile, e.g.
665
666 <pre>
667 $(eval $(call KMOD_template,USB_KEYBOARD,usb-kbd,\
668 $(MODULES_DIR)/kernel/drivers/input/input.o \
669 $(MODULES_DIR)/kernel/drivers/input/keybdev.o \
670 $(MODULES_DIR)/kernel/drivers/usb/usbkbd.o \
671 ,CONFIG_USB_KEYB,kmod-usb-core,60,input keybdev usbkbd))
672 </pre>
673
674 Where CONFIG_USB_KEYB is the kernel option, USB_KEYBOARD is the last
675 part of BR2_PACKAGE_KMOD_USB_KEYBOARD and usb-kbd is part of the
676 filename of the created ipkg.</p>
677
678 <h2><a name="control" id="control"></a>Specify the ipkg control file</h2>
679
680 <p>Create e.g. target/linux/control/kmod-usb-kbd.control with content similar to this:
681
682 <pre>
683 Package: kmod-usb-kbd
684 Priority: optional
685 Section: sys
686 Maintainer: Markus Becker &lt;mab@comnets.uni-bremen.de&gt;
687 Source: buildroot internal
688 Description: Kernel Support for USB Keyboards
689 </pre>
690 </p>
691
692 <h2><a name="compile" id="compile"></a>Compile the kernel module</h2>
693
694 <p>Enable the kernel module with
695 <pre>
696 $ make menuconfig
697 </pre>
698 in TOPDIR and selecting it.<br>
699
700 Compile with
701 <pre>
702 $ make dirclean && make
703 </pre>
704 </p>
705 </div>
706
707 </body>
708 </html>
This page took 0.066481 seconds and 5 git commands to generate.