[uClibc] Playing with buildroot.

Rob Landley 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 
for now...)

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
      first time.

   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
   website: http://www.linuxfromscratch.org

   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:

     mkdir temp
     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 mailing list