diff --git a/buildroot-documentation.html b/buildroot-documentation.html new file mode 100644 index 0000000000..a65d47fd86 --- /dev/null +++ b/buildroot-documentation.html @@ -0,0 +1,607 @@ + + + + + + Buildroot - Usage and documentation + + + + + +
+
+

Buildroot

+
+ +

Usage and documentation by Thomas Petazzoni. Contributions from + Karsten Kruse, Ned Ludd, Martin Herren.

+ +

Last modification : $Date: 2004/12/20 19:35:20 $

+ + + +

About Buildroot

+ +

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 (http://www.uclibc.org/), a tiny C standard + library.

+ +

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.

+ +

A compilation toolchain is the set of tools that allows to + compile code for your system. It consists of a compiler (in our + case, gcc), binary utils like assembler and linker + (in our case, binutils) and a C standard library (for + example GNU + Libc, uClibc or dietlibc). 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.

+ +

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.

+ +

Even if your embedded system uses a x86 processor, you might interested + in Buildroot, for two reasons:

+ + + +

You might wonder why such a tool is needed when you can compile + gcc, binutils, uClibc and all the tools by hand. + Of course, doing so is possible. But dealing with all configure options, + with all problems of every gcc or binutils + version it very time-consuming and uninteresting. Buildroot automates this + process through the use of Makefiles, and has a collection of patches for + each gcc and binutils version to make them work + on most architectures.

+ +

Obtaining Buildroot

+ +

Buildroot is available as daily CVS snapshots or directly using + CVS.

+ +

The latest snapshot is always available at http://uclibc.org/downloads/snapshots/buildroot-snapshot.tar.bz2, + and previous snapshots are also available at http://uclibc.org/downloads/snapshots/.

+ +

To download Buildroot using CVS, you can simply follow + the rules described on the "Accessing CVS"-page (http://www.uclibc.org/cvs_anon.html) + of the uClibc website (http://www.uclibc.org), and download the + buildroot CVS module. For the impatient, here's a quick + recipe:

+ + 
+ $ cvs -d:pserver:anonymous@uclibc.org:/var/cvs login
+ $ cvs -z3 -d:pserver:anonymous@uclibc.org:/var/cvs co buildroot
+
+ +

Using Buildroot

+ +

Buildroot has a nice configuration tool similar to the one you can find + in the Linux Kernel (http://www.kernel.org/) or in Busybox + (http://www.busybox.org/). 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:

+ +
+ $ make menuconfig
+
+ +

For each entry of the configuration tool, you can find associated help + that describes the purpose of the entry.

+ +

Once everything is configured, the configuration tool has generated a + .config file that contains the description of your + configuration. It will be used by the Makefiles to do what's needed.

+ +

Let's go:

+ +
+ $ make
+
+ +

This command will download, configure and compile all the selected + tools, and finally generate a target filesystem. The target filesystem will + be named root_fs_ARCH.EXT where ARCH is your + architecture and EXT depends on the type of target filesystem + selected in the Target options section of the configuration + tool.

+ +

Customizing the + target filesystem

+ +

There are two ways to customize the resulting target filesystem:

+ + + +

Customizing the + Busybox configuration

+ +

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.

+ +
    +
  1. Make a first compilation of buildroot with busybox without trying to + customize it.
    2. + +
  2. Go into build_ARCH/busybox/ and run make + menuconfig. The nice configuration tool appears and you can + customize everything.
    3. + +
  3. Copy the .config file to + package/busybox/busybox.config so that your customized + configuration will remains even if you remove the cross-compilation + toolchain.
    4. + +
  4. Run the compilation of buildroot again.
    5. +
+ +

Otherwise, you can simply change the + package/busybox/busybox.config file if you know the options + you want to change without using the configuration tool.

+ +

Customizing the uClibc + configuration

+ +

Just like BusyBox, uClibc offers a lot of + configuration options. They allow to select various + functionalities, depending on your needs and limitations.

+ +

The easiest way to modify the configuration of uClibc is to + follow these steps :

+ +
    + +
  1. Make a first compilation of buildroot without trying to + customize uClibc.
    2. + +
  2. Go into the directory + toolchain_build_ARCH/uClibc/ and run make + menuconfig. The nice configuration assistant, similar to + the one used in the Linux Kernel or in Buildroot appears. Make + your configuration as appropriate.
    3. + +
  3. Copy the .config file to + toolchain/uClibc/uClibc.config or + toolchain/uClibc/uClibc.config-locale. 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. + +
  4. Run the compilation of Buildroot again
    5. + +
+ +

Otherwise, you can simply change + toolchain/uClibc/uClibc.config or + toolchain/uClibc/uClibc.config-locale without running + the configuration assistant.

+ +

How Buildroot + works

+ +

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 (gcc, binutils and + uClibc).

+ +

There is basically one Makefile per software, and they are named with + the .mk extension. Makefiles are split into three + sections:

+ + + +

Each directory contains at least 3 files :

+ + + +

The main Makefile do the job through the following steps (once the + configuration is done):

+ +
    +
  1. Create the download directory (dl/ 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.
    2. + +
  2. Create the build directory (build_ARCH/ by default, + where ARCH is your architecture). This is where all + user-space tools while be compiled.
    3. + +
  3. Create the toolchain build directory + (toolchain_build_ARCH/ by default, where ARCH + is your architecture). This is where the cross compilation toolchain will + be compiled.
    4. + +
  4. Setup the staging directory (build_ARCH/staging_dir/ 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 + build_ARCH/staging_dir/bin to your PATH, and then use + arch-linux-gcc 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.
    5. + +
  5. Create the target directory (build_ARCH/root/ 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 target/default/skel.tar.gz file to create the + main subdirectories and symlinks, copies the skeleton available in + target/default/target_skeleton and then removes useless + CVS/ directories.
    6. + +
  6. Make the TARGETS dependency. This is where all the job + is done : all Makefile.in files "subscribe" targets into + this global variable, so that the needed tools gets compiled.
    7. +
+ +

Using the + uClibc toolchain without buildroot

+ +

By default, the cross-compilation toolchain is generated inside + build_ARCH/staging_dir/. 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 build_ARCH/staging_dir/ + directory elsewhere is not possible, because they are some hardcoded + paths in the toolchain configuration.

+ +

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 : Build options -> + Toolchain and header file location, which defaults to + $(BUILD_DIR)/staging_dir/.

+ +

Location of downloaded packages

+ +

It might be useful to know that the various tarballs that are + downloaded by the Makefiles are all stored in the + DL_DIR which by default is the dl + 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.

+ +

Extending Buildroot with + more software

+ +

This section will only consider the case in which you want to + add user-space software.

+ +

Package directory

+ +

First of all, create a directory under the package + directory for your software, for example foo.

+ +

Config.in file

+ +

Then, create a file named Config.in. This file + will contain the portion of options description related to our + foo software that will be used and displayed in the + configuration tool. It should basically contain :

+ +
+config BR2_PACKAGE_FOO
+        bool "foo"
+        default n
+        help
+	     This is a comment that explains what foo is.
+
+ +

Of course, you can add other options to configure particular + things in your software.

+ +

Makefile.in file

+ +

Then, write a Makefile.in file. Basically, this is + a very short Makefile that adds the name of the software to + the list of TARGETS that Buildroot will generate. In + fact, the name of the software is the the identifier of the target + inside the real Makefile that will do everything (download, + compile, install), and that we study below. Back to + Makefile.in, here is an example : + +

+ifeq ($(strip $(BR2_PACKAGE_FOO)),y)
+TARGETS+=foo
+endif
+
+ +

As you can see, this short Makefile simply adds the + target foo to the list of targets handled by Buildroot + if software foo was selected using the configuration tool.

+ +

The real Makefile

+ +

Finally, here's the hardest part. Create a file named + foo.mk. It will contain the Makefile rules that + are in charge of downloading, configuring, compiling and installing + the software. Below is an example that we will comment + afterwards.

+ +
+     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
+
+ +

First of all, this Makefile 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 *.mk files in the package + directory.

+ +

At lines 6-11, a couple of useful variables are defined :

+ + + +

Lines 13-14 defines a target that downloads the tarball from + the remote site to the download directory + (DL_DIR).

+ +

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 touching a hidden file + to mark the software has having been uncompressed. This trick is + used everywhere in Buildroot Makefile to split steps + (download, uncompress, configure, compile, install) while still + having correct dependencies.

+ +

Lines 20-31 defines a target and associated rules that + configures the software. It depends on the previous target (the + hidden .source file) so that we are sure the software has + been uncompressed. In order to configure it, it basically runs the + well-known ./configurescript. As we may be doing + cross-compilation, target, host and + build arguments are given. The prefix is also set to + /usr, not because the software will be installed in + /usr on your host system, but in the target + filesystem. Finally it creates a .configured file to + mark the software as configured.

+ +

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 .configured + file). It basically runs make inside the source + directory.

+ +

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 install target of the + software Makefile by passing a prefix + argument, so that the Makefile doesn't try to install + the software inside host /usr but inside target + /usr. After the installation, the + /usr/man directory inside the target filesystem is + removed to save space.

+ +

Line 40 defines the main target of the software, the one + referenced in the Makefile.in file. This targets + should first of all depends on the dependecies of the software (in + our example, uclibc and ncurses), and then to the + final binary. This last dependency will call all previous + dependencies in the right order.

+ +

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.

+ +

Lignes 44-46 define a simple target to clean the software build + by calling the Makefiles with the appropriate option.

+ +

Lines 48-49 define a simple target to completely remove the + directory in which the software was uncompressed, configured and + compiled.

+ +

Conclusion

+ +

As you can see, adding a software to buildroot is simply a + matter of writing a Makefile using an already existing + example and to modify it according to the compilation process of + the software.

+ +

If you package software that might be useful for other persons, + don't forget to send a patch to Buildroot developers !

+ +

Ressources

+ +

To learn more about Buildroot you can visit these + websites:

+ + + +
+ +