diff options
Diffstat (limited to 'buildroot-documentation.html')
| -rw-r--r-- | buildroot-documentation.html | 607 |
1 files changed, 0 insertions, 607 deletions
diff --git a/buildroot-documentation.html b/buildroot-documentation.html deleted file mode 100644 index a9f9f8b3c..000000000 --- a/buildroot-documentation.html +++ /dev/null @@ -1,607 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - -<html xmlns="http://www.w3.org/1999/xhtml"> -<head> - <title>Buildroot - Usage and documentation</title> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> - <link rel="stylesheet" type="text/css" href="stylesheet.css" /> -</head> - -<body> - <div class="main"> - <div class="titre"> - <h1>Buildroot</h1> - </div> - - <p>Usage and documentation by Thomas Petazzoni. Contributions from - Karsten Kruse, Ned Ludd, Martin Herren.</p> - - <p><small>Last modification : $Date: 2004/12/22 22:19:46 $</small></p> - - <ul> - <li><a href="#about">About Buildroot</a></li> - <li><a href="#download">Obtaining Buildroot</a></li> - <li><a href="#using">Using Buildroot</a></li> - <li><a href="#custom_targetfs">Customizing the target filesystem</a></li> - <li><a href="#custom_busybox">Customizing the Busybox - configuration</a></li> - <li><a href="#custom_uclibc">Customizing the uClibc - configuration</a></li> - <li><a href="#buildroot_innards">How Buildroot works</a></li> - <li><a href="#toolchain_standalone">Using the uClibc toolchain without - Buildroot</a></li> - <li><a href="#downloaded_packages">Location of downloaded packages</a></li> - <li><a href="#add_software">Extending Buildroot with more - Software</a></li> - <li><a href="#links">Ressources</a></li> - </ul> - - <h2><a name="about" id="about"></a>About Buildroot</h2> - - <p>Buildroot is a set of Makefiles and patches that allows to easily - generate both a cross-compilation toolchain and a root filesystem for your - target. The cross-compilation toolchain uses uClibc (<a href= - "http://www.uclibc.org/">http://www.uclibc.org/</a>), a tiny C standard - library.</p> - - <p>Buildroot is useful mainly for people working with embedded systems. - Embedded systems often use processors that are not the regular x86 - processors everyone is used to have on his PC. It can be PowerPC - processors, MIPS processors, ARM processors, etc.</p> - - <p>A compilation toolchain is the set of tools that allows to - compile code for your system. It consists of a compiler (in our - case, <code>gcc</code>), binary utils like assembler and linker - (in our case, <code>binutils</code>) and a C standard library (for - example <a href="http://www.gnu.org/software/libc/libc.html">GNU - Libc</a>, <a href="http://www.uclibc.org">uClibc</a> or <a - href="http://www.fefe.de/dietlibc/">dietlibc</a>). The system - installed on your development station certainly already has a - compilation toolchain that you can use to compile application that - runs on your system. If you're using a PC, your compilation - toolchain runs on an x86 processor and generates code for a x86 - processor. Under most Linux systems, the compilation toolchain - uses the GNU libc as C standard library. This compilation - toolchain is called the "host compilation toolchain", and more - generally, the machine on which it is running, and on which you're - working is called the "host system". The compilation toolchain is - provided by your distribution, and Buildroot has nothing to do - with it.</p> - - <p>As said above, the compilation toolchain that comes with your system - runs and generates code for the processor of your host system. As your - embedded system has a different processor, you need a cross-compilation - toolchain: it's a compilation toolchain that runs on your host system but - that generates code for your target system (and target processor). For - example, if your host system uses x86 and your target system uses ARM, the - regular compilation toolchain of your host runs on x86 and generates code - for x86, while the cross-compilation toolchain runs on x86 and generates - code for ARM.</p> - - <p>Even if your embedded system uses a x86 processor, you might interested - in Buildroot, for two reasons:</p> - - <ul> - <li>The compilation toolchain of your host certainly uses the GNU Libc - which is a complete but huge C standard library. Instead of using GNU - Libc on your target system, you can use uClibc which is a tiny C standard - library. If you want to use this C library, then you need a compilation - toolchain to generate binaries linked with it. Buildroot can do it for - you.</li> - - <li>Buildroot automates the building of a root filesystem with all needed - tools like busybox. It makes it much easier than doing it by hand.</li> - </ul> - - <p>You might wonder why such a tool is needed when you can compile - <code>gcc</code>, <code>binutils</code>, uClibc and all the tools by hand. - Of course, doing so is possible. But dealing with all configure options, - with all problems of every <code>gcc</code> or <code>binutils</code> - version it very time-consuming and uninteresting. Buildroot automates this - process through the use of Makefiles, and has a collection of patches for - each <code>gcc</code> and <code>binutils</code> version to make them work - on most architectures.</p> - - <h2><a name="download" id="download"></a>Obtaining Buildroot</h2> - - <p>Buildroot is available as daily CVS snapshots or directly using - CVS.</p> - - <p>The latest snapshot is always available at <a - href="http://uclibc.org/downloads/snapshots/buildroot-snapshot.tar.bz2">http://uclibc.org/downloads/snapshots/buildroot-snapshot.tar.bz2</a>, - and previous snapshots are also available at <a - href="http://uclibc.org/downloads/snapshots/">http://uclibc.org/downloads/snapshots/</a>.</p> - - <p>To download Buildroot using CVS, you can simply follow - the rules described on the "Accessing CVS"-page (<a href= - "http://www.uclibc.org/cvs_anon.html">http://www.uclibc.org/cvs_anon.html</a>) - of the uClibc website (<a href= - "http://www.uclibc.org">http://www.uclibc.org</a>), and download the - <code>buildroot</code> CVS module. For the impatient, here's a quick - recipe:</p> - - <pre> - $ cvs -d:pserver:anonymous@uclibc.org:/var/cvs login - $ cvs -z3 -d:pserver:anonymous@uclibc.org:/var/cvs co buildroot -</pre> - - <h2><a name="using" id="using"></a>Using Buildroot</h2> - - <p>Buildroot has a nice configuration tool similar to the one you can find - in the Linux Kernel (<a href= - "http://www.kernel.org/">http://www.kernel.org/</a>) or in Busybox - (<a href="http://www.busybox.org/">http://www.busybox.org/</a>). Note that - you can run everything as a normal user. There is no need to be root to - configure and use Buildroot. The first step is to run the configuration - assistant:</p> - -<pre> - $ make menuconfig -</pre> - - <p>For each entry of the configuration tool, you can find associated help - that describes the purpose of the entry.</p> - - <p>Once everything is configured, the configuration tool has generated a - <code>.config</code> file that contains the description of your - configuration. It will be used by the Makefiles to do what's needed.</p> - - <p>Let's go:</p> - -<pre> - $ make -</pre> - - <p>This command will download, configure and compile all the selected - tools, and finally generate a target filesystem. The target filesystem will - be named <code>root_fs_ARCH.EXT</code> where <code>ARCH</code> is your - architecture and <code>EXT</code> depends on the type of target filesystem - selected in the <code>Target options</code> section of the configuration - tool.</p> - - <h2><a name="custom_targetfs" id="custom_targetfs"></a>Customizing the - target filesystem</h2> - - <p>There are two ways to customize the resulting target filesystem:</p> - - <ul> - <li>Customize the target filesystem directly, and rebuild the image. The - target filesystem is available under <code>build_ARCH/root/</code> where - <code>ARCH</code> is the chosen target architecture. You can simply make - your changes here, and run make afterwards, which will rebuild the target - filesystem image. This method allows to do everything on the target - filesystem, but if you decide to completely rebuild your toolchain and - tools, these changes will be lost.</li> - - <li>Customize the target filesystem skeleton, available under - <code>target/default/target_skeleton/</code>. You can customize - configuration files or other stuff here. However, the full file hierarchy - is not yet present, because it's created during the compilation process. - So you can't do everything on this target filesystem skeleton, but - changes to it remains even you completely rebuild the cross-compilation - toolchain and the tools.<br /> - You can also customize the <code>target/default/device_table.txt</code> - file which is used by the tools that generate the target filesystem image - to properly set permissions and create device nodes. The - <code>target/default/skel.tar.gz</code> file contains the main - directories of a root filesystem and there is no obvious reason for which - it should be changed. These main directories are in an tarball inside of - inside the skeleton because it contains symlinks that would be broken - otherwise.</li> - </ul> - - <h2><a name="custom_busybox" id="custom_busybox"></a>Customizing the - Busybox configuration</h2> - - <p>Busybox is very configurable, and you may want to customize it. You can - follow these simple steps to do it. It's not an optimal way, but it's - simple and it works.</p> - - <ol> - <li>Make a first compilation of buildroot with busybox without trying to - customize it.</li> - - <li>Go into <code>build_ARCH/busybox/</code> and run <code>make - menuconfig</code>. The nice configuration tool appears and you can - customize everything.</li> - - <li>Copy the <code>.config</code> file to - <code>package/busybox/busybox.config</code> so that your customized - configuration will remains even if you remove the cross-compilation - toolchain.</li> - - <li>Run the compilation of buildroot again.</li> - </ol> - - <p>Otherwise, you can simply change the - <code>package/busybox/busybox.config</code> file if you know the options - you want to change without using the configuration tool.</p> - - <h2><a name="custom_uclibc" id="custom_uclibc"></a>Customizing the uClibc - configuration</h2> - - <p>Just like <a href="#custom_busybox">BusyBox</a>, <a - href="http://www.uclibc.org">uClibc</a> offers a lot of - configuration options. They allow to select various - functionalities, depending on your needs and limitations.</p> - - <p>The easiest way to modify the configuration of uClibc is to - follow these steps :</p> - - <ol> - - <li>Make a first compilation of buildroot without trying to - customize uClibc.</li> - - <li>Go into the directory - <code>toolchain_build_ARCH/uClibc/</code> and run <code>make - menuconfig</code>. The nice configuration assistant, similar to - the one used in the Linux Kernel or in Buildroot appears. Make - your configuration as appropriate.</li> - - <li>Copy the <code>.config</code> file to - <code>toolchain/uClibc/uClibc.config</code> or - <code>toolchain/uClibc/uClibc.config-locale</code>. The former - is used if you haven't selected locale support in Buildroot - configuration, and the latter is used if you have selected - locale support. - - <li>Run the compilation of Buildroot again</li> - - </ol> - - <p>Otherwise, you can simply change - <code>toolchain/uClibc/uClibc.config</code> or - <code>toolchain/uClibc/uClibc.config-locale</code> without running - the configuration assistant.</p> - - <h2><a name="buildroot_innards" id="buildroot_innards"></a>How Buildroot - works</h2> - - <p>As said above, Buildroot is basically a set of Makefiles that download, - configure and compiles software with the correct options. It also includes - some patches for various softwares, mainly the ones involved in the - cross-compilation tool chain (<code>gcc</code>, <code>binutils</code> and - uClibc).</p> - - <p>There is basically one Makefile per software, and they are named with - the <code>.mk</code> extension. Makefiles are split into three - sections:</p> - - <ul> - <li><b>package</b> (in the <code>package/</code> directory) contains the - Makefiles and associated files for all user-space tools that Buildroot - can compile and add to the target root filesystem. There is one - sub-directory per tool.</li> - - <li><b>toolchain</b> (in the <code>toolchain/</code> directory) contains - the Makefiles and associated files for all softwares related to the - cross-compilation toolchain : <code>binutils</code>, <code>ccache</code>, - <code>gcc</code>, <code>gdb</code>, <code>kernel-headers</code> and - <code>uClibc</code>.</li> - - <li><b>target</b> (in the <code>target</code> directory) contains the - Makefiles and associated files for softwares related to the generation of - the target root filesystem image. Four types of filesystems are supported - : ext2, jffs2, cramfs and squashfs. For each of them, there's a - sub-directory with the required files. There is also a - <code>default/</code> directory that contains the target filesystem - skeleton.</li> - </ul> - - <p>Each directory contains at least 3 files :</p> - - <ul> - <li><code>something.mk</code> is the Makefile that downloads, configures, - compiles and installs the software <code>something</code>.</li> - - <li><code>Config.in</code> is a part of the configuration tool - description file. It describes the option related to the current - software.</li> - - <li><code>Makefile.in</code> is a part of Makefile that sets various - variables according to the configuration given through the configuration - tool. For most tools it simply involves adding the name of the tool to - the <code>TARGETS</code> variable.</li> - </ul> - - <p>The main Makefile do the job through the following steps (once the - configuration is done):</p> - - <ol> - <li>Create the download directory (<code>dl/</code> by default). This is - where the tarballs will be downloaded. It is interesting to know that the - tarballs are in this directory because it may be useful to save them - somewhere to avoid further downloads.</li> - - <li>Create the build directory (<code>build_ARCH/</code> by default, - where <code>ARCH</code> is your architecture). This is where all - user-space tools while be compiled.</li> - - <li>Create the toolchain build directory - (<code>toolchain_build_ARCH/</code> by default, where <code>ARCH</code> - is your architecture). This is where the cross compilation toolchain will - be compiled.</li> - - <li>Setup the staging directory (<code>build_ARCH/staging_dir/</code> by - default). This is where the cross-compilation toolchain will be - installed. If you want to use the same cross-compilation toolchain for - other purposes, such as compiling third-party applications, you can add - <code>build_ARCH/staging_dir/bin</code> to your PATH, and then use - <code>arch-linux-gcc</code> to compile your application. In order to - setup this staging directory, it first removes it, and then it creates - various subdirectories and symlinks inside it.</li> - - <li>Create the target directory (<code>build_ARCH/root/</code> by - default) and the target filesystem skeleton. This directory will contain - the final root filesystem. To setup it up, it first deletes it, then it - uncompress the <code>target/default/skel.tar.gz</code> file to create the - main subdirectories and symlinks, copies the skeleton available in - <code>target/default/target_skeleton</code> and then removes useless - <code>CVS/</code> directories.</li> - - <li>Make the <code>TARGETS</code> dependency. This is where all the job - is done : all <code>Makefile.in</code> files "subscribe" targets into - this global variable, so that the needed tools gets compiled.</li> - </ol> - - <h2><a name="toolchain_standalone" id="toolchain_standalone"></a>Using the - uClibc toolchain without buildroot</h2> - - <p>By default, the cross-compilation toolchain is generated inside - <code>build_ARCH/staging_dir/</code>. But sometimes, it may be useful to - install it somewhere else, so that it can be used to compile other programs - or by other users. Moving the <code>build_ARCH/staging_dir/</code> - directory elsewhere is <b>not possible</b>, because they are some hardcoded - paths in the toolchain configuration.</p> - - <p>If you want to use the generated toolchain for other purposes, - you can configure Buildroot to generate it elsewhere using the - option of the configuration tool : <code>Build options -> - Toolchain and header file location</code>, which defaults to - <code>$(BUILD_DIR)/staging_dir/</code>.</p> - - <h2><a name="downloaded_packages" - id="downloaded_packages"></a>Location of downloaded packages</h2> - - <p>It might be useful to know that the various tarballs that are - downloaded by the <i>Makefiles</i> are all stored in the - <code>DL_DIR</code> which by default is the <code>dl</code> - directory. It's useful for example if you want to keep a complete - version of Buildroot which is know to be working with the - associated tarballs. This will allow you to regenerate the - toolchain and the target filesystem with exactly the same - versions.</p> - - <h2><a name="add_software" id="add_software"></a>Extending Buildroot with - more software</h2> - - <p>This section will only consider the case in which you want to - add user-space software.</p> - - <h3>Package directory</h3> - - <p>First of all, create a directory under the <code>package</code> - directory for your software, for example <code>foo</code>.</p> - - <h3><code>Config.in</code> file</h3> - - <p>Then, create a file named <code>Config.in</code>. This file - will contain the portion of options description related to our - <code>foo</code> software that will be used and displayed in the - configuration tool. It should basically contain :</p> - -<pre> -config BR2_PACKAGE_FOO - bool "foo" - default n - help - This is a comment that explains what foo is. -</pre> - - <p>Of course, you can add other options to configure particular - things in your software.</p> - - <h3><code>Makefile.in</code> file</h3> - - <p>Then, write a <code>Makefile.in</code> file. Basically, this is - a very short <i>Makefile</i> that adds the name of the software to - the list of <code>TARGETS</code> that Buildroot will generate. In - fact, the name of the software is the the identifier of the target - inside the real <i>Makefile</i> that will do everything (download, - compile, install), and that we study below. Back to - <code>Makefile.in</code>, here is an example : - -<pre> -ifeq ($(strip $(BR2_PACKAGE_FOO)),y) -TARGETS+=foo -endif -</pre> - - <p>As you can see, this short <i>Makefile</i> simply adds the - target <code>foo</code> to the list of targets handled by Buildroot - if software <i>foo</i> was selected using the configuration tool.</p> - - <h3>The real <i>Makefile</i></h3> - - <p>Finally, here's the hardest part. Create a file named - <code>foo.mk</code>. It will contain the <i>Makefile</i> rules that - are in charge of downloading, configuring, compiling and installing - the software. Below is an example that we will comment - afterwards.</p> - -<pre> - 1 ############################################################# - 2 # - 3 # foo - 4 # - 5 ############################################################# - 6 FOO_VERSION:=1.0 - 7 FOO_SOURCE:=less-$(FOO_VERSION).tar.gz - 8 FOO_SITE:=http://www.foosoftware.org/downloads - 9 FOO_DIR:=$(BUILD_DIR)/less-$(FOO_VERSION) - 10 FOO_BINARY:=foo - 11 FOO_TARGET_BINARY:=usr/bin/foo - 12 - 13 $(DL_DIR)/$(FOO_SOURCE): - 14 $(WGET) -P $(DL_DIR) $(FOO_SITE)/$(FOO_SOURCE) - 15 - 16 $(FOO_DIR)/.source: $(DL_DIR)/$(FOO_SOURCE) - 17 zcat $(DL_DIR)/$(FOO_SOURCE) | tar -C $(BUILD_DIR) $(TAR_OPTIONS) - - 18 touch $(FOO_DIR)/.source - 19 - 20 $(FOO_DIR)/.configured: $(FOO_DIR)/.source - 21 (cd $(FOO_DIR); \ - 22 $(TARGET_CONFIGURE_OPTS) \ - 23 CFLAGS="$(TARGET_CFLAGS)" \ - 24 ./configure \ - 25 --target=$(GNU_TARGET_NAME) \ - 26 --host=$(GNU_TARGET_NAME) \ - 27 --build=$(GNU_HOST_NAME) \ - 28 --prefix=/usr \ - 29 --sysconfdir=/etc \ - 30 ); - 31 touch $(FOO_DIR)/.configured; - 32 - 33 $(FOO_DIR)/$(FOO_BINARY): $(FOO_DIR)/.configured - 34 $(MAKE) CC=$(TARGET_CC) -C $(FOO_DIR) - 35 - 36 $(TARGET_DIR)/$(FOO_TARGET_BINARY): $(FOO_DIR)/$(FOO_BINARY) - 37 $(MAKE) prefix=$(TARGET_DIR)/usr -C $(FOO_DIR) install - 38 rm -Rf $(TARGET_DIR)/usr/man - 39 - 40 foo: uclibc ncurses $(TARGET_DIR)/$(FOO_TARGET_BINARY) - 41 - 42 foo-source: $(DL_DIR)/$(FOO_SOURCE) - 43 - 44 foo-clean: - 45 $(MAKE) prefix=$(TARGET_DIR)/usr -C $(FOO_DIR) uninstall - 46 -$(MAKE) -C $(FOO_DIR) clean - 47 - 48 foo-dirclean: - 49 rm -rf $(FOO_DIR) - 50 -</pre> - - <p>First of all, this <i>Makefile</i> example works for a single - binary software. For other softwares such as libraries or more - complex stuff with multiple binaries, it should be adapted. Look at - the other <code>*.mk</code> files in the <code>package</code> - directory.</p> - - <p>At lines 6-11, a couple of useful variables are defined :</p> - - <ul> - - <li><code>FOO_VERSION</code> : The version of <i>foo</i> that - should be downloaded.</li> - - <li><code>FOO_SOURCE</code> : The name of the tarball of - <i>foo</i> on the download website of FTP site. As you can see - <code>FOO_VERSION</code> is used.</li> - - <li><code>FOO_SITE</code> : The HTTP or FTP site from which - <i>foo</i> archive is downloaded. It must include the complete - path to the directory where <code>FOO_SOURCE</code> can be - found.</li> - - <li><code>FOO_DIR</code> : The directory into which the software - will be configured and compiled. Basically, it's a subdirectory - of <code>BUILD_DIR</code> which is created upon decompression of - the tarball.</li> - - <li><code>FOO_BINARY</code> : Software binary name. As said - previously, this is an example for a single binary software.</li> - - <li><code>FOO_TARGET_BINARY</code> : The full path of the binary - inside the target filesystem.</li> - - </ul> - - <p>Lines 13-14 defines a target that downloads the tarball from - the remote site to the download directory - (<code>DL_DIR</code>).</p> - - <p>Lines 16-18 defines a target and associated rules that - uncompress the downloaded tarball. As you can see, this target - depends on the tarball file, so that the previous target (line - 13-14) is called before executing the rules of the current - target. Uncompressing is followed by <i>touching</i> a hidden file - to mark the software has having been uncompressed. This trick is - used everywhere in Buildroot <i>Makefile</i> to split steps - (download, uncompress, configure, compile, install) while still - having correct dependencies.</p> - - <p>Lines 20-31 defines a target and associated rules that - configures the software. It depends on the previous target (the - hidden <code>.source</code> file) so that we are sure the software has - been uncompressed. In order to configure it, it basically runs the - well-known <code>./configure</code>script. As we may be doing - cross-compilation, <code>target</code>, <code>host</code> and - <code>build</code> arguments are given. The prefix is also set to - <code>/usr</code>, not because the software will be installed in - <code>/usr</code> on your host system, but in the target - filesystem. Finally it creates a <code>.configured</code> file to - mark the software as configured.</p> - - <p>Lines 33-34 defines a target and a rule that compiles the - software. This target will create the binary file in the - compilation directory, and depends on the software being already - configured (hence the reference to the <code>.configured</code> - file). It basically runs <code>make</code> inside the source - directory.</p> - - <p>Lines 36-38 defines a target and associated rules that install - the software inside the target filesystem. It depends on the - binary file in the source directory, to make sure the software has - been compiled. It uses the <code>install</code> target of the - software <code>Makefile</code> by passing a <code>prefix</code> - argument, so that the <code>Makefile</code> doesn't try to install - the software inside host <code>/usr</code> but inside target - <code>/usr</code>. After the installation, the - <code>/usr/man</code> directory inside the target filesystem is - removed to save space.</p> - - <p>Line 40 defines the main target of the software, the one - referenced in the <code>Makefile.in</code> file. This targets - should first of all depends on the dependecies of the software (in - our example, <i>uclibc</i> and <i>ncurses</i>), and then to the - final binary. This last dependency will call all previous - dependencies in the right order. </p> - - <p>Line 42 defines a simple target that only downloads the code - source. This is not used during normal operation of Buildroot, but - might be useful.</p> - - <p>Lignes 44-46 define a simple target to clean the software build - by calling the <i>Makefiles</i> with the appropriate option.</p> - - <p>Lines 48-49 define a simple target to completely remove the - directory in which the software was uncompressed, configured and - compiled.</p> - - <h3>Conclusion</h3> - - <p>As you can see, adding a software to buildroot is simply a - matter of writing a <i>Makefile</i> using an already existing - example and to modify it according to the compilation process of - the software.</p> - - <p>If you package software that might be useful for other persons, - don't forget to send a patch to Buildroot developers !</p> - - <h2><a name="links" id="links"></a>Ressources</h2> - - <p>To learn more about Buildroot you can visit these - websites:</p> - - <ul> - <li><a href="http://www.uclibc.org/">http://www.uclibc.org/</a></li> - <li><a href="http://www.busybox.net/">http://www.busybox.net/</a></li> - </ul> - - </div> -</body> -</html> |