[uClibc] Playing with buildroot.
rob at landley.net
Mon Aug 4 21:36:52 MDT 2003
So I'm banging on buildroot (trying to revive my old hand-rolled Linux
distribution only based on ucLibc within the buildroot system this time) and
the first thing I notice is a lack of documentation (available from the
uclibc web page, anyway). So I banged together a quick howto, largely based
on an old post of Eric's that I had lying around on my hard drive.
It ain't done yet (excuse me, it am not done yet), and it's probably extremely
wrong in places, but it's a start. Flame away...
(P.S. There are two obvious FIXME entries to grep for, becuase my laptop is
slow enough that the build has been grinding away for something like four
hours (longer than it took me to write the howto) without coming close to
being done yet, and I don't remember what those suckers were called last
time. There are also some random todo items at the top which you can ignore
I may whip up a better version of this later in the evening. You never know.
-------------- next part --------------
What's USE_UCLIBC_TOOLCHAIN for? (What's the alternative?)
What does gcc_target mean, separately from uclibc_toolchain? (Didn't you
already do a two-pass build, and rebuild gcc in the chroot environment?)
I use "TARGETS+=linux", so describe that.
Why doesn't busybox implement tinylogin's functions?
The buildroot package automates the creation of a uClibc-only development
system. This can be run under an existing linux system via a "user mode
linux" kernel and a loopback mounted root partition, or booted and run as
a full fledged linux system.
To create one of these suckers, follow these steps:
1) Download the buildroot package from
(Buildroot does not have releases yet, the above link will grab a snapshot
of the current CVS version.)
2) Unpack the tarball and read the README file.
3) Edit the Makefile and adjust any options you feel like. The Makefile
has four sections:
A) configuration options.
A good first guess here is to set both USE_UCLIBC_SNAPSHOT and
USE_BUSYBOX_SNAPSHOT to false, and leave everything else alone your
B) TARGETS list.
This is the list of what to build. Most of the interesting configuration
is done by adding packages to the TARGETS list. Step 4 will talk all
about this; we'll come back to it.
C) Root filesystem type.
A special target at the end of your build creates a filesystem image
file. (An image file is a file that contains a virtual disk image,
I.E. a bunch of virtual sectors all in a row, formatted as a filesystem,
just like it would look like if it were on a block device like a ramdisk,
hard drive, or CD-ROM. You may have used an ISO cd-rom image file to
burn a CD, or a floppy image file to create a boot diskette. This is
similar. Step 7 of this HOWTO explains how to use this image file
once the build has created it.)
Since this image file gets formatted, we have to select the filesystem
type to format it as. EXT2 is the standard Linux filesystem type, and
that's the default. You can also select cramfs (a compressed read-only
filesystem, suitable for burning into ROM), or jffs2 (a filesystem
designed for use with flash memory).
You can leave this at the default (ext2root) your first time
D) Everything else.
There's generally no reason to play with the rest of the Makefile.
Someday, the first three sections may be broken out into a seperate
configuration file that's included from the Makefile; in the meantime,
just ignore the second half of the file unless you're curious how it
4) Select the packages you want to build.
The Makefile contains a number of example targets. You almost always want
"uclibc_toolchain", which builds three things:
A) uclibc itself
B) gcc (configured to links executables against uclibc instead of glibc).
B) the binutils package (linker, assembler, and other things needed
to actually make executables and libraries).
You need the uclibc toolchain to build anything else.
Beyond the toolchain, an absolutely minimal system will contain the
targets "busybox" and "tinylogin", to allow you to login and execute
standard unix commands. (Busybox is another project in the spirit of
uclibc, re-implementing tiny versions of most of the standard unix command
line utilities, and in the process providing a substitute for half a dozen
traditional packages like fileutils, textutils, sh-utils, sysvinit, bash...)
Adding targets appends them to the end of the list, and they get built in
order. This is important because some packages have prerequisites; for
example, if you want openssh you must first make zlib and openssl. Good
documentation on this sort of thing may be found on the Linux From Scratch
The make file contains a number of sample targets, including a group of
packages required to make a development with enough tools to compile
most other packakges, debugging tools, and network configuration tools
needed to make a standalone firewall or smart router.
The complete list of available targets can be found in the "make"
subdirectory: there are a bunch of makefiles in there that know how to
build existing packages under the uclibc environment created by buildroot.
All of makefiles in this directory are automatically included from the
top level Makefile (the line is "include make/*.mk"), and the target
to trigger each one is usually found near the end of the makefile in
question. (For example, in "autoconf.mk", the target is "autoconf:",
so you'd add "TARGETS+=autoconf" to the target list section of the top
level Makefile in order to have buildroot build it for you.)
5) Optionally copy any of the tarballs that buildroot needs into the sources/dl
directory. If, for example, you already have the gcc-3.2 tarball or the
linux-2.4.19 tarball, just copy them into place so you can avoid having
buildroot download them once again from the net.
Note that if you would like to download all the source for your selected
targets immediately (useful on a dialup connection, or taking a laptop
with you on a plane), the command is "make source". (Be sure to configure
your target list before doing this.) Once the build system has downloaded
a package, it keeps it around for future builds. A "make clean" won't
delete downloaded source packages (although a "make distclean" will).
By default, the build system will download each package as it finds it
needs it (using the "wget" command, which most modern Linux distributions
6) Run 'make' and wait a long time... There is a lot of stuff that needs to
be compiled, so be patient. Go to the kitchen and make yourself a nice
sandwich. Since buildroot will download any source files it needs which
are not already sitting in the sources/dl directory, if you have a slow net
connection you might consider starting this before you go to bed in the
hope that it will be done when you wake up. ;-)
7) When buildroot finishes, there will be a new Linux system sitting in
build/root. If you're an old hand at installing filesystems by hand,
you can copy it to a bootable partition, and use a boot disk or play with
lilo or grub. (One easy way to copy files while preserving their
permissions and ownership is to use a pipe between two instances of
tar, ala "tar cC build/root . | tar xvC /destinationdir". To learn how to
make a partition bootable, read the Linux Bootdisk HOWTO at
For pure testing purposes, you can chroot into the new system. While
logged in as root, go to the buildroot directory (where the Makefile is)
and type "chroot build/root /bin/sh --login", then try running stuff.
Type "exit" when you want to return to your original Linux system. See
"man chroot" for more info.
If you told the build to create any of the filesystem image targets, you
can loopback mount them and chroot into them. Try something vaguely like:
mount -o loop FIXME temp
chroot temp /bin/sh --login
Don't forget to "umount temp" when you're done with it. (It'll
automatically get unmounted next time you reboot if you forget, but in the
mean time it can be a neusance.)
If you used the "user-mode-linux" target, the build process will create a
special linux kernel that can be run as a normal application program. The
build process will also configure it to use the filesystem image you just
created as its root partition, and also configure it to contact your X
server and pop up some Xterm windows when it runs, so you can interact with
it. Just type FIXME and it should do the rest. (This is a much more
automated option: easy to use but also more complicated, and potentially
more difficult for newbies to understand how it all works.)
More information about the uClibc