Ubuntu Wiki

This page explains how to create a Debian/Ubuntu rootfs from scratch using debootstrap and QEMU.

This is not the recommended nor the easiest way to create a Debian/Ubuntu armel rootfs; see ARM/RootfsFromScratch for other ways.

Prerequisites

You need:

• debootstrap; your debootstrap should be recent enough to debootstrap the suite you're interested in
• one of qemu-arm-static (syscall emulation) or qemu-system-arm (machine emulation)
• e2fsprogs or some mkfs.something tool if you want to create an actual filesytem
• a kernel for qemu/versatile/cortex-a8

TODO document name of packages, perhaps pointing at a PPA with backports. TODO use lucid versatile kernel when available

First stage debootstrap

debootstrap bootstraps a Debian/Ubuntu system in multiple steps which can be divided in two stages: the parts running code/tools from the build environment, and the parts running code/tools from the target environment.

For the first stage, run something like:

    sudo debootstrap \
        --arch=armel \
        --keyring=/usr/share/keyrings/ubuntu-archive-keyring.gpg \
        --verbose \
        --foreign \
        karmic \
        rootfs

The arguments tells debootstrap respectively to:

• bootstrap for armel
• verify the downloaded data with the installed Ubuntu keyring (from the ubuntu-keyring package); if you want to install e.g. Debian, point at the Debian keyring instead (in the debian-archive-keyring package)
• give some progress information
• only do the first phase of the bootstrapping
• target the Ubuntu 9.10 (karmic) suite
• use "rootfs" as target directory

Things you might want to customize:

• by default, only packages from the "main" component are used, you can enable other components (such as "restricted", "universe", and "multiverse" for Ubuntu and "contrib" and "non-free" for Debian) with the --components= flag
• you can include/exclude some packages via the --include= and --exclude= flags
• you can select different package selections depending on the intended use of the rootfs via the --variant= flag; for instance, --variant=minbase will create a minimal environment with essential packages and apt, while --variant=buildd will install build-essential packages

Check the debootstrap(8) manpage for details. TODO link to man page

Second stage debootstrap using QEMU

QEMU sports two types of emulation:

• machine emulation: this emulates a complete computer, including a virtual CPU, a virtual video card, a virtual clock, a virtual SCSI controller etc.
• syscall emulation: this translates code from one architecture to another, remapping system calls (calls to the kernel) between the two architectures

QEMU's syscall emulation is much faster than machine emulation, but both are relatively slow when compared to native programs for your computer. One major drawback of syscall emulation is that it that some syscalls are not emulated, so some programs might now work, also when building programs, these might configure themselve for the features of the kernel they run on instead of what the target architecture actually supports.

For rootfs creation, using syscall emulation is probably fine for core packages, but you might run into issues with higher level ones.

Using syscall emulation

While qemu-arm can be used to run a single armel binary from the command-line, it's impractical to use it to run a program which will fork and execute other programs. Also, because qemu-arm itself uses shared libraries and the ld.so dynamic linker/loader from the build environment, it's impractical to copy it in the rootfs to use it with chroot-ed programs. So the following instructions expect that you're using a static version of qemu-arm ("qemu-arm-static"), and that your build environment supports the binfmt-misc module, this modules allows running any executable matching some configured pattern with an interpreter of your choice.

    # Ubuntu 10.04 (lucid)
    sudo apt-get install qemu-kvm-extras-static

(Under Debian, the package is named qemu-user-static and under Ubuntu 9.10 (karmic) it's called qemu-arm-static.)

Under Debian and Ubuntu, the package should automatically pull in the "binfmt-support" package and registers the qemu-arm format; check with:

    cat /proc/sys/fs/binfmt_misc/qemu-arm

(the format is named "arm" under Ubuntu 9.10 (karmic)).

Because we're going to chroot into the rootfs directory, the kernel will look for the interepreter in the chroot; copy the interpreter in the chroot:

    sudo cp /usr/bin/qemu-arm-static rootfs/usr/bin

Enter the rootfs chroot and run the second-stage:

    sudo chroot rootfs /bin/bash
    /debootstrap/debootstrap --second-stage

And you're done! You can create a tarball of the rootfs directory, or copy the files into an actual filesystem; see below. TODO add link

You might want to do some system configuration before using this rootfs on devics though; see below. TODO add link

You may also re-enter the chroot as above, e.g. to install additional packages, but note that usual chroot rules apply, so you will have to mount /proc manually, perhaps bind-mount /dev/pts or /tmp depending on programs you're trying to run, and you should be careful that installin packages might start (duplicate) services/jobs in the chroot or kill ones from outside the chroot!

Using machine emulation

Install qemu-system-arm (you don't need a static version):

    # Ubuntu 10.04 (lucid)
    sudo apt-get install qemu-kvm-extras

(Under Debian and Ubuntu 9.04 (jaunty) and earlier the package is named qemu.)

Create a filesystem image from the rootfs directory; see below. TODO add link

Grab a pre-built kernel for ARM "Versatile" boards patched to run with Cortex-A8 CPU (ARMv7). TODO add link to official lucid kernel

    wget http://people.canonical.com/~lool/versatile-cortex-a8-zImage

Start qemu as follows:

    qemu-system-arm \
        -M versatilepb \
        -cpu cortex-a8 \
        -hda rootfs.img \
        -m 256 \
        -kernel versatile-cortex-a8-zImage \
        -append 'rootwait root=/dev/sda init=/bin/sh rw'

The arguments tells qemu ARM machine emulation respectively to:

• emulate a Versatile PB board
• emulate a Cortex A8 CPU (ARMv7, what the kernel expects and supports all Debian/Ubuntu releases)
• use the rootfs.img file as the contents of the emulated SCSI hard disk
• emulate 256 MB of RAM
• use the downloaded kernel
• and pass some arguments to the kernel to set the root device and start a shell instead of starting /sbin/init

Once booted, run:

    /debootstrap/debootstrap --second-stage

And you're done!

You might want to do some system configuration before using this rootfs on devics though; see below. TODO add link