Buildroot

- -

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

- -

Last modification : $Id: buildroot-documentation.html,v 1.2 2004/12/28 19:15:20 andersen Exp $

- -

About Buildroot
Obtaining Buildroot
Using Buildroot
Customizing the target filesystem
Customizing the Busybox - configuration
Customizing the uClibc - configuration
How Buildroot works
Using the uClibc toolchain
Using the uClibc toolchain - outside of Buildroot
Location of downloaded packages
Extending Buildroot with more - Software
Ressources

- -

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:

- -

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.
Buildroot automates the building of a root filesystem with all needed - tools like busybox. It makes it much easier than doing it by hand.

- -

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:

- -

Customize the target filesystem directly, and rebuild the image. The - target filesystem is available under build_ARCH/root/ where - ARCH 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.
Customize the target filesystem skeleton, available under - target/default/target_skeleton/. 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.
- You can also customize the target/default/device_table.txt - file which is used by the tools that generate the target filesystem image - to properly set permissions and create device nodes. The - target/default/skel.tar.gz 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.

- -

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.

- -

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

- -

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 :

- -

Make a first compilation of buildroot without trying to - customize uClibc.
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.
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.
Run the compilation of Buildroot again

- -

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 software, 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:

- -

package (in the package/ 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.
toolchain (in the toolchain/ directory) contains - the Makefiles and associated files for all software related to the - cross-compilation toolchain : binutils, ccache, - gcc, gdb, kernel-headers and - uClibc.
target (in the target directory) contains the - Makefiles and associated files for software 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 - default/ directory that contains the target filesystem - skeleton.

- -

Each directory contains at least 2 files :

- -

something.mk is the Makefile that downloads, configures, - compiles and installs the software something.
Config.in is a part of the configuration tool - description file. It describes the option related to the current - software.

- -

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

- -

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.
Create the build directory (build_ARCH/ by default, - where ARCH is your architecture). This is where all - user-space tools while be compiled.
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.
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.
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.
Add the TARGETS dependency. This should generally check - if the configuration option for this package is enabled, and if so then - "subscribe" this package to be compiled by adding it to the TARGETS - global variable.

- -

Using the - uClibc toolchain

- -

You may want to compile your own programs or other software - that are not packaged in Buildroot. In order to do this, you can - use the toolchain that was generated by Buildroot.

- -

The toolchain generated by Buildroot by default is located in - build_ARCH/staging_dir/. The simplest way to use it - is to add build_ARCH/staging_dir/bin/ to your PATH - environnement variable, and then to use - arch-linux-gcc, arch-linux-objdump, - arch-linux-ld, etc.

- -

For example, you may add the following to your - .bashrc (considering you're building for the MIPS - architecture and that Buildroot is located in - ~/buildroot/) :

- -

-export PATH=$PATH:~/buildroot/build_mips/bin/
-

- -

Then you can simply do :

- -

-mips-linux-gcc -o foo foo.c
-

- -

Important : do not try to move the toolchain to an other - directory, it won't work. There are some hard-coded paths in the - gcc configuration. If the default toolchain directory - doesn't suit your needs, please refer to the Using the uClibc toolchain outside of - buildroot section.

- -

Using the - uClibc toolchain outside of 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.

- -

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
-    51 #############################################################
-    52 #
-    53 # Toplevel Makefile options
-    54 #
-    55 #############################################################
-    56 ifeq ($(strip $(BR2_PACKAGE_FOO)),y)
-    57 TARGETS+=foo
-    58 endif
-
-

- -

First of all, this Makefile example works for a single - binary software. For other software 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 :

- -

FOO_VERSION : The version of foo that - should be downloaded.
FOO_SOURCE : The name of the tarball of - foo on the download website of FTP site. As you can see - FOO_VERSION is used.
FOO_SITE : The HTTP or FTP site from which - foo archive is downloaded. It must include the complete - path to the directory where FOO_SOURCE can be - found.
FOO_DIR : The directory into which the software - will be configured and compiled. Basically, it's a subdirectory - of BUILD_DIR which is created upon decompression of - the tarball.
FOO_BINARY : Software binary name. As said - previously, this is an example for a single binary software.
FOO_TARGET_BINARY : The full path of the binary - inside the target filesystem.

- -

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 - that will be eventually be used by the top level - Makefile to download, compile, and then install - this package. This target should first of all depends on all - needed dependecies of the software (in our example, - uclibc and ncurses), and also depend on the - final binary. This last dependency will call all previous - dependencies in the correct 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.

- -

Lines 51-58 adds the target foo to the list - of targets to be compiled by Buildroot by first checking if - the configuration option for this package has been enabled - using the configuration tool, and if so then "subscribes" - this package to be compiled by adding it to the TARGETS - global variable. The name added to the TARGETS global - variable is the name of this package's target, as defined on - line 40, which is used by Buildroot to download, compile, and - then install this package.

- - -

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:

- -

Buildroot

+ +

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

+ +

Last modification : $Id: buildroot-documentation.html,v 1.2 2004/12/28 19:15:20 andersen Exp $

+ +

About Buildroot
Obtaining Buildroot
Using Buildroot
Customizing the target filesystem
Customizing the Busybox + configuration
Customizing the uClibc + configuration
How Buildroot works
Using the uClibc toolchain
Using the uClibc toolchain + outside of Buildroot
Location of downloaded packages
Extending Buildroot with more + Software
Ressources

+ +

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:

+ +

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.
Buildroot automates the building of a root filesystem with all needed + tools like busybox. It makes it much easier than doing it by hand.

+ +

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:

+ +

Customize the target filesystem directly, and rebuild the image. The + target filesystem is available under build_ARCH/root/ where + ARCH 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.
Customize the target filesystem skeleton, available under + target/default/target_skeleton/. 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.
+ You can also customize the target/default/device_table.txt + file which is used by the tools that generate the target filesystem image + to properly set permissions and create device nodes. The + target/default/skel.tar.gz 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.

+ +

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.

+ +

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

+ +

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 :

+ +

Make a first compilation of buildroot without trying to + customize uClibc.
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.
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.
Run the compilation of Buildroot again

+ +

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 software, 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:

+ +

package (in the package/ 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.
toolchain (in the toolchain/ directory) contains + the Makefiles and associated files for all software related to the + cross-compilation toolchain : binutils, ccache, + gcc, gdb, kernel-headers and + uClibc.
target (in the target directory) contains the + Makefiles and associated files for software 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 + default/ directory that contains the target filesystem + skeleton.

+ +

Each directory contains at least 2 files :

+ +

something.mk is the Makefile that downloads, configures, + compiles and installs the software something.
Config.in is a part of the configuration tool + description file. It describes the option related to the current + software.

+ +

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

+ +

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.
Create the build directory (build_ARCH/ by default, + where ARCH is your architecture). This is where all + user-space tools while be compiled.
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.
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.
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.
Add the TARGETS dependency. This should generally check + if the configuration option for this package is enabled, and if so then + "subscribe" this package to be compiled by adding it to the TARGETS + global variable.

+ +

Using the + uClibc toolchain

+ +

You may want to compile your own programs or other software + that are not packaged in Buildroot. In order to do this, you can + use the toolchain that was generated by Buildroot.

+ +

The toolchain generated by Buildroot by default is located in + build_ARCH/staging_dir/. The simplest way to use it + is to add build_ARCH/staging_dir/bin/ to your PATH + environnement variable, and then to use + arch-linux-gcc, arch-linux-objdump, + arch-linux-ld, etc.

+ +

For example, you may add the following to your + .bashrc (considering you're building for the MIPS + architecture and that Buildroot is located in + ~/buildroot/) :

+ +

+export PATH=$PATH:~/buildroot/build_mips/bin/
+

+ +

Then you can simply do :

+ +

+mips-linux-gcc -o foo foo.c
+

+ +

Important : do not try to move the toolchain to an other + directory, it won't work. There are some hard-coded paths in the + gcc configuration. If the default toolchain directory + doesn't suit your needs, please refer to the Using the uClibc toolchain outside of + buildroot section.

+ +

Using the + uClibc toolchain outside of 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.

+ +

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
+    51 #############################################################
+    52 #
+    53 # Toplevel Makefile options
+    54 #
+    55 #############################################################
+    56 ifeq ($(strip $(BR2_PACKAGE_FOO)),y)
+    57 TARGETS+=foo
+    58 endif
+
+

+ +

First of all, this Makefile example works for a single + binary software. For other software 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 :

+ +

FOO_VERSION : The version of foo that + should be downloaded.
FOO_SOURCE : The name of the tarball of + foo on the download website of FTP site. As you can see + FOO_VERSION is used.
FOO_SITE : The HTTP or FTP site from which + foo archive is downloaded. It must include the complete + path to the directory where FOO_SOURCE can be + found.
FOO_DIR : The directory into which the software + will be configured and compiled. Basically, it's a subdirectory + of BUILD_DIR which is created upon decompression of + the tarball.
FOO_BINARY : Software binary name. As said + previously, this is an example for a single binary software.
FOO_TARGET_BINARY : The full path of the binary + inside the target filesystem.

+ +

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 + that will be eventually be used by the top level + Makefile to download, compile, and then install + this package. This target should first of all depends on all + needed dependecies of the software (in our example, + uclibc and ncurses), and also depend on the + final binary. This last dependency will call all previous + dependencies in the correct 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.

+ +

Lines 51-58 adds the target foo to the list + of targets to be compiled by Buildroot by first checking if + the configuration option for this package has been enabled + using the configuration tool, and if so then "subscribes" + this package to be compiled by adding it to the TARGETS + global variable. The name added to the TARGETS global + variable is the name of this package's target, as defined on + line 40, which is used by Buildroot to download, compile, and + then install this package.

+ + +

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:

+ +

Buildroot

About Buildroot

Obtaining Buildroot

Using Buildroot

Customizing the - target filesystem

Customizing the - Busybox configuration

Customizing the uClibc - configuration

How Buildroot - works

Using the - uClibc toolchain

Using the - uClibc toolchain outside of buildroot

Location of downloaded packages

Extending Buildroot with - more software

Package directory

Config.in file

The real Makefile

Conclusion

Ressources

Buildroot

About Buildroot

Obtaining Buildroot

Using Buildroot

Customizing the + target filesystem

Customizing the + Busybox configuration

Customizing the uClibc + configuration

How Buildroot + works

Using the + uClibc toolchain

Using the + uClibc toolchain outside of buildroot

Location of downloaded packages

Extending Buildroot with + more software

Package directory

Config.in file

The real Makefile

Conclusion

Ressources

`Config.in` file

`Config.in` file