Initial revision
[openwrt/svn-archive/archive.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>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>Buildroot</h1>
16 </div>
17
18 <p>Usage and documentation by Thomas Petazzoni. Contributions from
19 Karsten Kruse, Ned Ludd, Martin Herren.</p>
20
21 <p><small>Last modification : $Id$</small></p>
22
23 <ul>
24 <li><a href="#about">About Buildroot</a></li>
25 <li><a href="#download">Obtaining Buildroot</a></li>
26 <li><a href="#using">Using Buildroot</a></li>
27 <li><a href="#custom_targetfs">Customizing the target filesystem</a></li>
28 <li><a href="#custom_busybox">Customizing the Busybox
29 configuration</a></li>
30 <li><a href="#custom_uclibc">Customizing the uClibc
31 configuration</a></li>
32 <li><a href="#buildroot_innards">How Buildroot works</a></li>
33 <li><a href="#using_toolchain">Using the uClibc toolchain</a></li>
34 <li><a href="#toolchain_standalone">Using the uClibc toolchain
35 outside of Buildroot</a></li>
36 <li><a href="#downloaded_packages">Location of downloaded packages</a></li>
37 <li><a href="#add_software">Extending Buildroot with more
38 Software</a></li>
39 <li><a href="#links">Ressources</a></li>
40 </ul>
41
42 <h2><a name="about" id="about"></a>About Buildroot</h2>
43
44 <p>Buildroot is a set of Makefiles and patches that allows to easily
45 generate both a cross-compilation toolchain and a root filesystem for your
46 target. The cross-compilation toolchain uses uClibc (<a href=
47 "http://www.uclibc.org/">http://www.uclibc.org/</a>), a tiny C standard
48 library.</p>
49
50 <p>Buildroot is useful mainly for people working with embedded systems.
51 Embedded systems often use processors that are not the regular x86
52 processors everyone is used to have on his PC. It can be PowerPC
53 processors, MIPS processors, ARM processors, etc.</p>
54
55 <p>A compilation toolchain is the set of tools that allows to
56 compile code for your system. It consists of a compiler (in our
57 case, <code>gcc</code>), binary utils like assembler and linker
58 (in our case, <code>binutils</code>) and a C standard library (for
59 example <a href="http://www.gnu.org/software/libc/libc.html">GNU
60 Libc</a>, <a href="http://www.uclibc.org">uClibc</a> or <a
61 href="http://www.fefe.de/dietlibc/">dietlibc</a>). The system
62 installed on your development station certainly already has a
63 compilation toolchain that you can use to compile application that
64 runs on your system. If you're using a PC, your compilation
65 toolchain runs on an x86 processor and generates code for a x86
66 processor. Under most Linux systems, the compilation toolchain
67 uses the GNU libc as C standard library. This compilation
68 toolchain is called the "host compilation toolchain", and more
69 generally, the machine on which it is running, and on which you're
70 working is called the "host system". The compilation toolchain is
71 provided by your distribution, and Buildroot has nothing to do
72 with it.</p>
73
74 <p>As said above, the compilation toolchain that comes with your system
75 runs and generates code for the processor of your host system. As your
76 embedded system has a different processor, you need a cross-compilation
77 toolchain: it's a compilation toolchain that runs on your host system but
78 that generates code for your target system (and target processor). For
79 example, if your host system uses x86 and your target system uses ARM, the
80 regular compilation toolchain of your host runs on x86 and generates code
81 for x86, while the cross-compilation toolchain runs on x86 and generates
82 code for ARM.</p>
83
84 <p>Even if your embedded system uses a x86 processor, you might interested
85 in Buildroot, for two reasons:</p>
86
87 <ul>
88 <li>The compilation toolchain of your host certainly uses the GNU Libc
89 which is a complete but huge C standard library. Instead of using GNU
90 Libc on your target system, you can use uClibc which is a tiny C standard
91 library. If you want to use this C library, then you need a compilation
92 toolchain to generate binaries linked with it. Buildroot can do it for
93 you.</li>
94
95 <li>Buildroot automates the building of a root filesystem with all needed
96 tools like busybox. It makes it much easier than doing it by hand.</li>
97 </ul>
98
99 <p>You might wonder why such a tool is needed when you can compile
100 <code>gcc</code>, <code>binutils</code>, uClibc and all the tools by hand.
101 Of course, doing so is possible. But dealing with all configure options,
102 with all problems of every <code>gcc</code> or <code>binutils</code>
103 version it very time-consuming and uninteresting. Buildroot automates this
104 process through the use of Makefiles, and has a collection of patches for
105 each <code>gcc</code> and <code>binutils</code> version to make them work
106 on most architectures.</p>
107
108 <h2><a name="download" id="download"></a>Obtaining Buildroot</h2>
109
110 <p>Buildroot is available as daily CVS snapshots or directly using
111 CVS.</p>
112
113 <p>The latest snapshot is always available at <a
114 href="http://uclibc.org/downloads/snapshots/buildroot-snapshot.tar.bz2">http://uclibc.org/downloads/snapshots/buildroot-snapshot.tar.bz2</a>,
115 and previous snapshots are also available at <a
116 href="http://uclibc.org/downloads/snapshots/">http://uclibc.org/downloads/snapshots/</a>.</p>
117
118 <p>To download Buildroot using CVS, you can simply follow
119 the rules described on the "Accessing CVS"-page (<a href=
120 "http://www.uclibc.org/cvs_anon.html">http://www.uclibc.org/cvs_anon.html</a>)
121 of the uClibc website (<a href=
122 "http://www.uclibc.org">http://www.uclibc.org</a>), and download the
123 <code>buildroot</code> CVS module. For the impatient, here's a quick
124 recipe:</p>
125
126 <pre>
127 $ cvs -d:pserver:anonymous@uclibc.org:/var/cvs login
128 $ cvs -z3 -d:pserver:anonymous@uclibc.org:/var/cvs co buildroot
129 </pre>
130
131 <h2><a name="using" id="using"></a>Using Buildroot</h2>
132
133 <p>Buildroot has a nice configuration tool similar to the one you can find
134 in the Linux Kernel (<a href=
135 "http://www.kernel.org/">http://www.kernel.org/</a>) or in Busybox
136 (<a href="http://www.busybox.org/">http://www.busybox.org/</a>). Note that
137 you can run everything as a normal user. There is no need to be root to
138 configure and use Buildroot. The first step is to run the configuration
139 assistant:</p>
140
141 <pre>
142 $ make menuconfig
143 </pre>
144
145 <p>For each entry of the configuration tool, you can find associated help
146 that describes the purpose of the entry.</p>
147
148 <p>Once everything is configured, the configuration tool has generated a
149 <code>.config</code> file that contains the description of your
150 configuration. It will be used by the Makefiles to do what's needed.</p>
151
152 <p>Let's go:</p>
153
154 <pre>
155 $ make
156 </pre>
157
158 <p>This command will download, configure and compile all the selected
159 tools, and finally generate a target filesystem. The target filesystem will
160 be named <code>root_fs_ARCH.EXT</code> where <code>ARCH</code> is your
161 architecture and <code>EXT</code> depends on the type of target filesystem
162 selected in the <code>Target options</code> section of the configuration
163 tool.</p>
164
165 <h2><a name="custom_targetfs" id="custom_targetfs"></a>Customizing the
166 target filesystem</h2>
167
168 <p>There are two ways to customize the resulting target filesystem:</p>
169
170 <ul>
171 <li>Customize the target filesystem directly, and rebuild the image. The
172 target filesystem is available under <code>build_ARCH/root/</code> where
173 <code>ARCH</code> is the chosen target architecture. You can simply make
174 your changes here, and run make afterwards, which will rebuild the target
175 filesystem image. This method allows to do everything on the target
176 filesystem, but if you decide to completely rebuild your toolchain and
177 tools, these changes will be lost.</li>
178
179 <li>Customize the target filesystem skeleton, available under
180 <code>target/default/target_skeleton/</code>. You can customize
181 configuration files or other stuff here. However, the full file hierarchy
182 is not yet present, because it's created during the compilation process.
183 So you can't do everything on this target filesystem skeleton, but
184 changes to it remains even you completely rebuild the cross-compilation
185 toolchain and the tools.<br />
186 You can also customize the <code>target/default/device_table.txt</code>
187 file which is used by the tools that generate the target filesystem image
188 to properly set permissions and create device nodes. The
189 <code>target/default/skel.tar.gz</code> file contains the main
190 directories of a root filesystem and there is no obvious reason for which
191 it should be changed. These main directories are in an tarball inside of
192 inside the skeleton because it contains symlinks that would be broken
193 otherwise.</li>
194 </ul>
195
196 <h2><a name="custom_busybox" id="custom_busybox"></a>Customizing the
197 Busybox configuration</h2>
198
199 <p>Busybox is very configurable, and you may want to customize it. You can
200 follow these simple steps to do it. It's not an optimal way, but it's
201 simple and it works.</p>
202
203 <ol>
204 <li>Make a first compilation of buildroot with busybox without trying to
205 customize it.</li>
206
207 <li>Go into <code>build_ARCH/busybox/</code> and run <code>make
208 menuconfig</code>. The nice configuration tool appears and you can
209 customize everything.</li>
210
211 <li>Copy the <code>.config</code> file to
212 <code>package/busybox/busybox.config</code> so that your customized
213 configuration will remains even if you remove the cross-compilation
214 toolchain.</li>
215
216 <li>Run the compilation of buildroot again.</li>
217 </ol>
218
219 <p>Otherwise, you can simply change the
220 <code>package/busybox/busybox.config</code> file if you know the options
221 you want to change without using the configuration tool.</p>
222
223 <h2><a name="custom_uclibc" id="custom_uclibc"></a>Customizing the uClibc
224 configuration</h2>
225
226 <p>Just like <a href="#custom_busybox">BusyBox</a>, <a
227 href="http://www.uclibc.org">uClibc</a> offers a lot of
228 configuration options. They allow to select various
229 functionalities, depending on your needs and limitations.</p>
230
231 <p>The easiest way to modify the configuration of uClibc is to
232 follow these steps :</p>
233
234 <ol>
235
236 <li>Make a first compilation of buildroot without trying to
237 customize uClibc.</li>
238
239 <li>Go into the directory
240 <code>toolchain_build_ARCH/uClibc/</code> and run <code>make
241 menuconfig</code>. The nice configuration assistant, similar to
242 the one used in the Linux Kernel or in Buildroot appears. Make
243 your configuration as appropriate.</li>
244
245 <li>Copy the <code>.config</code> file to
246 <code>toolchain/uClibc/uClibc.config</code> or
247 <code>toolchain/uClibc/uClibc.config-locale</code>. The former
248 is used if you haven't selected locale support in Buildroot
249 configuration, and the latter is used if you have selected
250 locale support.</li>
251
252 <li>Run the compilation of Buildroot again</li>
253
254 </ol>
255
256 <p>Otherwise, you can simply change
257 <code>toolchain/uClibc/uClibc.config</code> or
258 <code>toolchain/uClibc/uClibc.config-locale</code> without running
259 the configuration assistant.</p>
260
261 <h2><a name="buildroot_innards" id="buildroot_innards"></a>How Buildroot
262 works</h2>
263
264 <p>As said above, Buildroot is basically a set of Makefiles that download,
265 configure and compiles software with the correct options. It also includes
266 some patches for various software, mainly the ones involved in the
267 cross-compilation tool chain (<code>gcc</code>, <code>binutils</code> and
268 uClibc).</p>
269
270 <p>There is basically one Makefile per software, and they are named with
271 the <code>.mk</code> extension. Makefiles are split into three
272 sections:</p>
273
274 <ul>
275 <li><b>package</b> (in the <code>package/</code> directory) contains the
276 Makefiles and associated files for all user-space tools that Buildroot
277 can compile and add to the target root filesystem. There is one
278 sub-directory per tool.</li>
279
280 <li><b>toolchain</b> (in the <code>toolchain/</code> directory) contains
281 the Makefiles and associated files for all software related to the
282 cross-compilation toolchain : <code>binutils</code>, <code>ccache</code>,
283 <code>gcc</code>, <code>gdb</code>, <code>kernel-headers</code> and
284 <code>uClibc</code>.</li>
285
286 <li><b>target</b> (in the <code>target</code> directory) contains the
287 Makefiles and associated files for software related to the generation of
288 the target root filesystem image. Four types of filesystems are supported
289 : ext2, jffs2, cramfs and squashfs. For each of them, there's a
290 sub-directory with the required files. There is also a
291 <code>default/</code> directory that contains the target filesystem
292 skeleton.</li>
293 </ul>
294
295 <p>Each directory contains at least 3 files :</p>
296
297 <ul>
298 <li><code>something.mk</code> is the Makefile that downloads, configures,
299 compiles and installs the software <code>something</code>.</li>
300
301 <li><code>Config.in</code> is a part of the configuration tool
302 description file. It describes the option related to the current
303 software.</li>
304
305 <li><code>Makefile.in</code> is a part of Makefile that sets various
306 variables according to the configuration given through the configuration
307 tool. For most tools it simply involves adding the name of the tool to
308 the <code>TARGETS</code> variable.</li>
309 </ul>
310
311 <p>The main Makefile do the job through the following steps (once the
312 configuration is done):</p>
313
314 <ol>
315 <li>Create the download directory (<code>dl/</code> by default). This is
316 where the tarballs will be downloaded. It is interesting to know that the
317 tarballs are in this directory because it may be useful to save them
318 somewhere to avoid further downloads.</li>
319
320 <li>Create the build directory (<code>build_ARCH/</code> by default,
321 where <code>ARCH</code> is your architecture). This is where all
322 user-space tools while be compiled.</li>
323
324 <li>Create the toolchain build directory
325 (<code>toolchain_build_ARCH/</code> by default, where <code>ARCH</code>
326 is your architecture). This is where the cross compilation toolchain will
327 be compiled.</li>
328
329 <li>Setup the staging directory (<code>build_ARCH/staging_dir/</code> by
330 default). This is where the cross-compilation toolchain will be
331 installed. If you want to use the same cross-compilation toolchain for
332 other purposes, such as compiling third-party applications, you can add
333 <code>build_ARCH/staging_dir/bin</code> to your PATH, and then use
334 <code>arch-linux-gcc</code> to compile your application. In order to
335 setup this staging directory, it first removes it, and then it creates
336 various subdirectories and symlinks inside it.</li>
337
338 <li>Create the target directory (<code>build_ARCH/root/</code> by
339 default) and the target filesystem skeleton. This directory will contain
340 the final root filesystem. To setup it up, it first deletes it, then it
341 uncompress the <code>target/default/skel.tar.gz</code> file to create the
342 main subdirectories and symlinks, copies the skeleton available in
343 <code>target/default/target_skeleton</code> and then removes useless
344 <code>CVS/</code> directories.</li>
345
346 <li>Make the <code>TARGETS</code> dependency. This is where all the job
347 is done : all <code>Makefile.in</code> files "subscribe" targets into
348 this global variable, so that the needed tools gets compiled.</li>
349 </ol>
350
351 <h2><a name="using_toolchain" id="using_toolchain"></a>Using the
352 uClibc toolchain</h2>
353
354 <p>You may want to compile your own programs or other software
355 that are not packaged in Buildroot. In order to do this, you can
356 use the toolchain that was generated by Buildroot.</p>
357
358 <p>The toolchain generated by Buildroot by default is located in
359 <code>build_ARCH/staging_dir/</code>. The simplest way to use it
360 is to add <code>build_ARCH/staging_dir/bin/</code> to your PATH
361 environnement variable, and then to use
362 <code>arch-linux-gcc</code>, <code>arch-linux-objdump</code>,
363 <code>arch-linux-ld</code>, etc.</p>
364
365 <p>For example, you may add the following to your
366 <code>.bashrc</code> (considering you're building for the MIPS
367 architecture and that Buildroot is located in
368 <code>~/buildroot/</code>) :</p>
369
370 <pre>
371 export PATH=$PATH:~/buildroot/build_mips/bin/
372 </pre>
373
374 <p>Then you can simply do :</p>
375
376 <pre>
377 mips-linux-gcc -o foo foo.c
378 </pre>
379
380 <p><b>Important</b> : do not try to move the toolchain to an other
381 directory, it won't work. There are some hard-coded paths in the
382 <i>gcc</i> configuration. If the default toolchain directory
383 doesn't suit your needs, please refer to the <a
384 href="#toolchain_standalone">Using the uClibc toolchain outside of
385 buildroot</a> section.</p>
386
387 <h2><a name="toolchain_standalone" id="toolchain_standalone"></a>Using the
388 uClibc toolchain outside of buildroot</h2>
389
390 <p>By default, the cross-compilation toolchain is generated inside
391 <code>build_ARCH/staging_dir/</code>. But sometimes, it may be useful to
392 install it somewhere else, so that it can be used to compile other programs
393 or by other users. Moving the <code>build_ARCH/staging_dir/</code>
394 directory elsewhere is <b>not possible</b>, because they are some hardcoded
395 paths in the toolchain configuration.</p>
396
397 <p>If you want to use the generated toolchain for other purposes,
398 you can configure Buildroot to generate it elsewhere using the
399 option of the configuration tool : <code>Build options ->
400 Toolchain and header file location</code>, which defaults to
401 <code>$(BUILD_DIR)/staging_dir/</code>.</p>
402
403 <h2><a name="downloaded_packages"
404 id="downloaded_packages"></a>Location of downloaded packages</h2>
405
406 <p>It might be useful to know that the various tarballs that are
407 downloaded by the <i>Makefiles</i> are all stored in the
408 <code>DL_DIR</code> which by default is the <code>dl</code>
409 directory. It's useful for example if you want to keep a complete
410 version of Buildroot which is know to be working with the
411 associated tarballs. This will allow you to regenerate the
412 toolchain and the target filesystem with exactly the same
413 versions.</p>
414
415 <h2><a name="add_software" id="add_software"></a>Extending Buildroot with
416 more software</h2>
417
418 <p>This section will only consider the case in which you want to
419 add user-space software.</p>
420
421 <h3>Package directory</h3>
422
423 <p>First of all, create a directory under the <code>package</code>
424 directory for your software, for example <code>foo</code>.</p>
425
426 <h3><code>Config.in</code> file</h3>
427
428 <p>Then, create a file named <code>Config.in</code>. This file
429 will contain the portion of options description related to our
430 <code>foo</code> software that will be used and displayed in the
431 configuration tool. It should basically contain :</p>
432
433 <pre>
434 config BR2_PACKAGE_FOO
435 bool "foo"
436 default n
437 help
438 This is a comment that explains what foo is.
439 </pre>
440
441 <p>Of course, you can add other options to configure particular
442 things in your software.</p>
443
444 <h3><code>Makefile.in</code> file</h3>
445
446 <p>Then, write a <code>Makefile.in</code> file. Basically, this is
447 a very short <i>Makefile</i> that adds the name of the software to
448 the list of <code>TARGETS</code> that Buildroot will generate. In
449 fact, the name of the software is the the identifier of the target
450 inside the real <i>Makefile</i> that will do everything (download,
451 compile, install), and that we study below. Back to
452 <code>Makefile.in</code>, here is an example :</p>
453
454 <pre>
455 ifeq ($(strip $(BR2_PACKAGE_FOO)),y)
456 TARGETS+=foo
457 endif
458 </pre>
459
460 <p>As you can see, this short <i>Makefile</i> simply adds the
461 target <code>foo</code> to the list of targets handled by Buildroot
462 if software <i>foo</i> was selected using the configuration tool.</p>
463
464 <h3>The real <i>Makefile</i></h3>
465
466 <p>Finally, here's the hardest part. Create a file named
467 <code>foo.mk</code>. It will contain the <i>Makefile</i> rules that
468 are in charge of downloading, configuring, compiling and installing
469 the software. Below is an example that we will comment
470 afterwards.</p>
471
472 <pre>
473 1 #############################################################
474 2 #
475 3 # foo
476 4 #
477 5 #############################################################
478 6 FOO_VERSION:=1.0
479 7 FOO_SOURCE:=less-$(FOO_VERSION).tar.gz
480 8 FOO_SITE:=http://www.foosoftware.org/downloads
481 9 FOO_DIR:=$(BUILD_DIR)/less-$(FOO_VERSION)
482 10 FOO_BINARY:=foo
483 11 FOO_TARGET_BINARY:=usr/bin/foo
484 12
485 13 $(DL_DIR)/$(FOO_SOURCE):
486 14 $(WGET) -P $(DL_DIR) $(FOO_SITE)/$(FOO_SOURCE)
487 15
488 16 $(FOO_DIR)/.source: $(DL_DIR)/$(FOO_SOURCE)
489 17 zcat $(DL_DIR)/$(FOO_SOURCE) | tar -C $(BUILD_DIR) $(TAR_OPTIONS) -
490 18 touch $(FOO_DIR)/.source
491 19
492 20 $(FOO_DIR)/.configured: $(FOO_DIR)/.source
493 21 (cd $(FOO_DIR); \
494 22 $(TARGET_CONFIGURE_OPTS) \
495 23 CFLAGS="$(TARGET_CFLAGS)" \
496 24 ./configure \
497 25 --target=$(GNU_TARGET_NAME) \
498 26 --host=$(GNU_TARGET_NAME) \
499 27 --build=$(GNU_HOST_NAME) \
500 28 --prefix=/usr \
501 29 --sysconfdir=/etc \
502 30 );
503 31 touch $(FOO_DIR)/.configured;
504 32
505 33 $(FOO_DIR)/$(FOO_BINARY): $(FOO_DIR)/.configured
506 34 $(MAKE) CC=$(TARGET_CC) -C $(FOO_DIR)
507 35
508 36 $(TARGET_DIR)/$(FOO_TARGET_BINARY): $(FOO_DIR)/$(FOO_BINARY)
509 37 $(MAKE) prefix=$(TARGET_DIR)/usr -C $(FOO_DIR) install
510 38 rm -Rf $(TARGET_DIR)/usr/man
511 39
512 40 foo: uclibc ncurses $(TARGET_DIR)/$(FOO_TARGET_BINARY)
513 41
514 42 foo-source: $(DL_DIR)/$(FOO_SOURCE)
515 43
516 44 foo-clean:
517 45 $(MAKE) prefix=$(TARGET_DIR)/usr -C $(FOO_DIR) uninstall
518 46 -$(MAKE) -C $(FOO_DIR) clean
519 47
520 48 foo-dirclean:
521 49 rm -rf $(FOO_DIR)
522 50
523 </pre>
524
525 <p>First of all, this <i>Makefile</i> example works for a single
526 binary software. For other software such as libraries or more
527 complex stuff with multiple binaries, it should be adapted. Look at
528 the other <code>*.mk</code> files in the <code>package</code>
529 directory.</p>
530
531 <p>At lines 6-11, a couple of useful variables are defined :</p>
532
533 <ul>
534
535 <li><code>FOO_VERSION</code> : The version of <i>foo</i> that
536 should be downloaded.</li>
537
538 <li><code>FOO_SOURCE</code> : The name of the tarball of
539 <i>foo</i> on the download website of FTP site. As you can see
540 <code>FOO_VERSION</code> is used.</li>
541
542 <li><code>FOO_SITE</code> : The HTTP or FTP site from which
543 <i>foo</i> archive is downloaded. It must include the complete
544 path to the directory where <code>FOO_SOURCE</code> can be
545 found.</li>
546
547 <li><code>FOO_DIR</code> : The directory into which the software
548 will be configured and compiled. Basically, it's a subdirectory
549 of <code>BUILD_DIR</code> which is created upon decompression of
550 the tarball.</li>
551
552 <li><code>FOO_BINARY</code> : Software binary name. As said
553 previously, this is an example for a single binary software.</li>
554
555 <li><code>FOO_TARGET_BINARY</code> : The full path of the binary
556 inside the target filesystem.</li>
557
558 </ul>
559
560 <p>Lines 13-14 defines a target that downloads the tarball from
561 the remote site to the download directory
562 (<code>DL_DIR</code>).</p>
563
564 <p>Lines 16-18 defines a target and associated rules that
565 uncompress the downloaded tarball. As you can see, this target
566 depends on the tarball file, so that the previous target (line
567 13-14) is called before executing the rules of the current
568 target. Uncompressing is followed by <i>touching</i> a hidden file
569 to mark the software has having been uncompressed. This trick is
570 used everywhere in Buildroot <i>Makefile</i> to split steps
571 (download, uncompress, configure, compile, install) while still
572 having correct dependencies.</p>
573
574 <p>Lines 20-31 defines a target and associated rules that
575 configures the software. It depends on the previous target (the
576 hidden <code>.source</code> file) so that we are sure the software has
577 been uncompressed. In order to configure it, it basically runs the
578 well-known <code>./configure</code>script. As we may be doing
579 cross-compilation, <code>target</code>, <code>host</code> and
580 <code>build</code> arguments are given. The prefix is also set to
581 <code>/usr</code>, not because the software will be installed in
582 <code>/usr</code> on your host system, but in the target
583 filesystem. Finally it creates a <code>.configured</code> file to
584 mark the software as configured.</p>
585
586 <p>Lines 33-34 defines a target and a rule that compiles the
587 software. This target will create the binary file in the
588 compilation directory, and depends on the software being already
589 configured (hence the reference to the <code>.configured</code>
590 file). It basically runs <code>make</code> inside the source
591 directory.</p>
592
593 <p>Lines 36-38 defines a target and associated rules that install
594 the software inside the target filesystem. It depends on the
595 binary file in the source directory, to make sure the software has
596 been compiled. It uses the <code>install</code> target of the
597 software <code>Makefile</code> by passing a <code>prefix</code>
598 argument, so that the <code>Makefile</code> doesn't try to install
599 the software inside host <code>/usr</code> but inside target
600 <code>/usr</code>. After the installation, the
601 <code>/usr/man</code> directory inside the target filesystem is
602 removed to save space.</p>
603
604 <p>Line 40 defines the main target of the software, the one
605 referenced in the <code>Makefile.in</code> file. This targets
606 should first of all depends on the dependecies of the software (in
607 our example, <i>uclibc</i> and <i>ncurses</i>), and then to the
608 final binary. This last dependency will call all previous
609 dependencies in the right order. </p>
610
611 <p>Line 42 defines a simple target that only downloads the code
612 source. This is not used during normal operation of Buildroot, but
613 might be useful.</p>
614
615 <p>Lignes 44-46 define a simple target to clean the software build
616 by calling the <i>Makefiles</i> with the appropriate option.</p>
617
618 <p>Lines 48-49 define a simple target to completely remove the
619 directory in which the software was uncompressed, configured and
620 compiled.</p>
621
622 <h3>Conclusion</h3>
623
624 <p>As you can see, adding a software to buildroot is simply a
625 matter of writing a <i>Makefile</i> using an already existing
626 example and to modify it according to the compilation process of
627 the software.</p>
628
629 <p>If you package software that might be useful for other persons,
630 don't forget to send a patch to Buildroot developers !</p>
631
632 <h2><a name="links" id="links"></a>Ressources</h2>
633
634 <p>To learn more about Buildroot you can visit these
635 websites:</p>
636
637 <ul>
638 <li><a href="http://www.uclibc.org/">http://www.uclibc.org/</a></li>
639 <li><a href="http://www.busybox.net/">http://www.busybox.net/</a></li>
640 </ul>
641
642 </div>
643 </body>
644 </html>