Step-by-step Buildroot/Busybox Root File System

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: VMWare Player is free as well:

Contents

Introduction

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.

Prerequisites

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:

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: . 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:

Overview

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
wget 
wget .md5sum
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:

./buildroot-example/buildroot-2012.11/output/host/opt/ext-toolchain/bin/arm-none-linux-gnueabi-gcc

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.

./buildroot-example/buildroot-2012.11/output/host/opt/ext-toolchain/bin/arm-none-linux-gnueabi/libc

Build the Root File System

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

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

make

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 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 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
sync
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
/dev/disk/by-uuid/e139ce78-9841-40fe-8823-96a304a09859
                          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 google.com

# 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 192.168.50.144...
Lease of 192.168.50.144 obtained, lease time 86400
deleting routers
route: SIOCDELRT: No such process
adding dns 192.168.50.10

# ifconfig
eth0      Link encap:Ethernet  HWaddr 56:8C:5D:01:AA:6E  
          inet addr:192.168.50.144  Bcast:192.168.50.255  Mask:255.255.255.0
          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:127.0.0.1  Mask:255.0.0.0
          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 google.com
PING google.com (74.125.224.142): 56 data bytes
64 bytes from 74.125.224.142: seq=0 ttl=55 time=15.563 ms
64 bytes from 74.125.224.142: 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