Step-by-step Buildroot/Busybox Root File System

From odroid US
Jump to: navigation, search

This tutorial is for Developers. It is written to work starting with the odroidu2 ubuntu SD-Card image, for example: odroidu2_20130104-linaro-ubuntu-desktop-uSDeMMC.img.xz.

This tutorial is not for Android developers.

It was tested on a "clean" Debian 6 machine, a VMWare virtual machine. You can find your own copy here: Debian6t VM VMWare Player is free as well: VMWare Player



Did you know you can easily make a very small custom-built Linux system? The key is to use the famous "Buildroot" package. This tutorial presents an example to get you started.

You can add additional packages as you like. Many products have been built using this technique with busybox playing the central role.


  • You MUST have access to the serial console -- use the USB/Serial adapter [check actual Hardkernel name]
  • You need an SD-card reader/writer
  • You need to start with an SD-Card loaded with the odroid ubuntu image: odroidu2_20130104-linaro-ubuntu-desktop-uSDeMMC.img.xz. You can read about how to install it here: Step-by-step Ubuntu SD Card Setup
  • You need a Linux host (or virtual machine) running a Debian-based distribution: Debian, Ubuntu, Mint, Knoppix, etc. This is because the buildroot scripts pick up packages, including an ARM toolchain that are automatically installed.
  • For this tutorial, you can use the provided odroidu2 kernel -- or build your own, see: Kernel Compiling. The kernel must have the network driver (smsc95xx) built-in rather than built as a kernel module. This lets us bring up the network interface once the root file system is installed.
  • You need to be able to write the resulting root file system image to the SD-Card. See: Updating from Root File System Images


    We are going to:

  • Do some setup on the host
  • Download the example files and extract them
  • Expand the buildroot package and add the odroidu2 configuration
  • Use make to pull in all required packages and prepare the root file system image
  • Write the image to SD-Card
  • Boot the buildroot root file system on our odroid

    Host Setup

    Make sure you have the neccessary programs installed

    # update the list of available packages
    # as root:
    apt-get update
    # We need the basics to allow us to build packages on the host, like make, gcc and so on
    apt-get -y install build-essential bison flex gettext

    Download Example Files

    You can use your browser, or use web get to get the example files tarball.

    # Go to some convenient folder, home if you like
    cd ~
    # Get the example files
    md5sum -c buildroot-example.tgz.md5sum
    # Assuming the md5sum is correct, continue
    tar -xvf buildroot-example.tgz
    cd buildroot-example

    Here are the files we now have:

  • rootfs.tar.gz. The resulting root file system image. You can write this to your SD-Card if you just want to see it work
  • buildroot-2012.11.tar.bz2. This is the current version of buildroot
  • odroidu2_just_busybox_defconfig. This is the tested buildroot configuration we need, it only includes busybox and nothing else.
  • nfs-mounting-boot.tgz. This is a boot partition image. You can extract this to your SD-Card boot partition, if you don't want to build your own kernel we need a kernel that included the smsc95xx driver for odroid-U2 in order to bring up the network.

    Expand buildroot and Configure it

    In the buildroot-example directory

    # expand the tarball
    tar -xvjf buildroot-2012.11.tar.bz2 
    # Add our configuration
    cp odroidu2_just_busybox_defconfig buildroot-2012.11/configs/
    # move to the buildroot top directory.  This is where you drive buildroot from
    cd buildroot-2012.11
    # and select our configuration
    make odroidu2_just_busybox_defconfig

    Some Toolchain Trivia

    You can skip this section, and come back to it later. The topic of toolchains can be confusing.

    This example if configured to use an external, downloaded toolchain -- a specific one packaged by CodeSourcery. You don't have to use this toolchain, it is possible to have buildroot build one from scratch. Seriously, why would you, unless for curiosity's sake? If you want to use a paid version of CodeSourcery, you may do that as well, but you need to modify the buildroot configuration to make it work.

    Buildroot installs a "private" copy of the cross-compiler. You can use it too, to build for ARM by including it in the path. The arm cross compiler binary is automatically installed to:


    The system libraries and binaries get copied to the root file system we build. These live in an area called the "sysroot" as you may see it in documentation.


    Build the Root File System

    I hope this amazes you! The buildroot guys have done a terrific service to the community. Visit them here: Buildroot

    The make could take some time, depending on which packages you already have installed.


    That's all there is to it.

  • ./output/images/rootfs.tar.gz holds the root file system tarball
     ls output/build

    These are the packages that were downloaded, configured and patched for cross-building (some are host packages, used during the build): busybox-1.20.2 host-ccache-3.1.7 host-fakeroot-1.18.2 host-makedevs-undefined

    Write the Root File System to SD-Card

    See this tutorial Updating from Root File System Images if you don't know what to do with ./output/images/rootfs.tar.gz

    Hint: untar the file to the SD-Card rootfs partition

    Write the Boot Partition Contents

    If you want to be able to bring up the network once you boot the buildroot root file system, you need a kernel configured with smsc95xx network driver built in. The kernel built for Step-by-step NFS-mounted Root File System will do. You can expand the included tarball nfs-mounting-boot.tgz into the boot partition if you like.

    [someone please check these steps] Insert the SD-Card, you may need to mount it. Assuming the mount point on your host is /media/boot, then

    As root user:

    cd /media/boot
    # Be real careful here.  This deletes all files.  Make sure you recognize the contents of the directory as the mounted SD-Card boot partition 
    # and NOT YOUR HOST boot partition.  Really.  Double check.
    rm -rf *
    # expand it
    tar -cvzf /home/user/buildroot-example/nfs-mounting-boot.tgz
    cd ..

    Unmount the boot partition, something like: (where X is the drive letter designation)

    umount /dev/sdX1

    Boot your odroid

    Make sure to unmount the SD-Card and put it back into the odroid SD-Card slot, then power it up.

    The default login is username: root No password is needed.

    The kernel loads, and uInitrd runs. It mounts the rootfs partition and does a switch_root to start init. Here is the banner:

    Welcome to Buildroot
    odroidu2-1 login:root
    Welcome to Buildroot
    odroidu2-1 login: root

    Check the kernel version:

    # uname -a
    Linux odroidu2-1 3.0.57 #4 SMP Fri Jan 18 21:42:20 UTC 2013 armv7l GNU/Linux

    How big is the root file system? (about 16MiB) Let's see:

    # df -h
    Filesystem                Size      Used Available Use% Mounted on
    udev                     10.0M         0     10.0M   0% /dev
    tmpfs                   396.8M    168.0K    396.6M   0% /tmp
                              5.4G     16.3M      5.1G   0% /
    tmpfs                   992.0M         0    992.0M   0% /dev/shm

    Let's see which applets are available in our configuration of busybox (you can add more)

    # busybox
    BusyBox v1.20.2 (2013-01-18 16:44:02 PST) multi-call binary.
    Copyright (C) 1998-2011 Erik Andersen, Rob Landley, Denys Vlasenko
    and others. Licensed under GPLv2.
    See source distribution for full notice.
    Usage: busybox [function] [arguments]...
       or: busybox --list[-full]
       or: busybox --install [-s] [DIR]
       or: function [arguments]...
            BusyBox is a multi-call binary that combines many common Unix
            utilities into a single executable.  Most people will create a
            link to busybox for each function they wish to use and BusyBox
            will act like whatever it was invoked as.
    Currently defined functions:
            [, [[, addgroup, adduser, ar, arping, ash, awk, basename, blkid,
            bunzip2, bzcat, cat, catv, chattr, chgrp, chmod, chown, chroot, chrt,
            chvt, cksum, clear, cmp, cp, cpio, crond, crontab, cut, date, dc, dd,
            deallocvt, delgroup, deluser, devmem, df, diff, dirname, dmesg, dnsd,
            dnsdomainname, dos2unix, du, dumpkmap, echo, egrep, eject, env,
            ether-wake, expr, false, fdflush, fdformat, fgrep, find, fold, free,
            freeramdisk, fsck, fuser, getopt, getty, grep, gunzip, gzip, halt,
            hdparm, head, hexdump, hostid, hostname, hwclock, id, ifconfig, ifdown,
            ifup, inetd, init, insmod, install, ip, ipaddr, ipcrm, ipcs, iplink,
            iproute, iprule, iptunnel, kill, killall, killall5, klogd, last, less,
            linux32, linux64, linuxrc, ln, loadfont, loadkmap, logger, login,
            logname, losetup, ls, lsattr, lsmod, lsof, lspci, lsusb, lzcat, lzma,
            makedevs, md5sum, mdev, mesg, microcom, mkdir, mkfifo, mknod, mkswap,
            mktemp, modprobe, more, mount, mountpoint, mt, mv, nameif, netstat,
            nice, nohup, nslookup, od, openvt, passwd, patch, pidof, ping,
            pipe_progress, pivot_root, poweroff, printenv, printf, ps, pwd, rdate,
            readlink, readprofile, realpath, reboot, renice, reset, resize, rm,
            rmdir, rmmod, route, run-parts, runlevel, sed, seq, setarch,
            setconsole, setkeycodes, setlogcons, setserial, setsid, sh, sha1sum,
            sha256sum, sha512sum, sleep, sort, start-stop-daemon, strings, stty,
            su, sulogin, swapoff, swapon, switch_root, sync, sysctl, syslogd, tail,
            tar, tee, telnet, test, tftp, time, top, touch, tr, traceroute, true,
            tty, udhcpc, umount, uname, uniq, unix2dos, unlzma, unxz, unzip,
            uptime, usleep, uudecode, uuencode, vconfig, vi, vlock, watch,
            watchdog, wc, wget, which, who, whoami, xargs, xz, xzcat, yes, zcat

    Let's bring the network up and test it by pinging

    # ifconfig eth0 up
    [   48.864404] ADDRCONF(NETDEV_UP): eth0: link is not ready
    # [   50.453230] ADDRCONF(NETDEV_CHANGE): eth0: link becomes ready
    [   50.454235] smsc95xx 1-2:1.0: eth0: link up, 100Mbps, full-duplex, lpa 0xC5E1
    # Start the DHCP daemon -- built into busybox
    # udhcpc
    udhcpc (v1.20.2) started
    Sending discover...
    Sending select for
    Lease of obtained, lease time 86400
    deleting routers
    route: SIOCDELRT: No such process
    adding dns
    # ifconfig
    eth0      Link encap:Ethernet  HWaddr 56:8C:5D:01:AA:6E  
              inet addr:  Bcast:  Mask:
              inet6 addr: fe80::548c:5dff:fe01:aa6e/64 Scope:Link
              UP BROADCAST RUNNING MULTICAST  MTU:1488  Metric:1
              RX packets:26 errors:0 dropped:0 overruns:0 frame:0
              TX packets:8 errors:0 dropped:0 overruns:0 carrier:0
              collisions:0 txqueuelen:1000 
              RX bytes:3185 (3.1 KiB)  TX bytes:1188 (1.1 KiB)
    lo        Link encap:Local Loopback  
              inet addr:  Mask:
              inet6 addr: ::1/128 Scope:Host
              UP LOOPBACK RUNNING  MTU:16436  Metric:1
              RX packets:12 errors:0 dropped:0 overruns:0 frame:0
              TX packets:12 errors:0 dropped:0 overruns:0 carrier:0
              collisions:0 txqueuelen:0 
              RX bytes:824 (824.0 B)  TX bytes:824 (824.0 B)
    # ping
    PING ( 56 data bytes
    64 bytes from seq=0 ttl=55 time=15.563 ms
    64 bytes from seq=1 ttl=55 time=15.577 ms

    Next Steps

    You can add packages, like openssl, dropbear, or any of hundreds of others by doing 'make menuconfig' in the buildroot-2012.11 directory. It can be an iterative process since you generally need to make dependent libraries before the apps that need them.

    You can add applets to busybox by running 'make menuconfig' in the output/build/busybox-1.20.2 directory

  • Personal tools