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 will 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 provide a PPA with backports.

= Building the Root Filesystem =

The initial image of the root filesystem can be done manually via "debootstrap", or more easily via the "mk-sbuild" wrapper.

== mk-sbuild ==

Trivially easy:
{{{
   mk-sbuild --arch armel lucid
}}}

== debootstrap ==

=== 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 with QEMU ===

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

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 [[#Creating a filesystem from a directory|Creating a filesystem from a directory]].

You might want to do some system configuration before using this rootfs on devices though; see [[#System configuration|System configuration]].

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 [[#Creating a filesystem from a directory|Creating a filesystem from a directory]].

Grab a pre-built kernel for ARM "Versatile" boards patched to run with Cortex-A8 CPU (ARMv7).  Use the [[https://launchpad.net/ubuntu/+source/linux|latest Lucid kernel]], or the netboot image, which may not always work:
{{{
    wget http://ports.ubuntu.com/ubuntu-ports/dists/lucid/main/installer-armel/current/images/versatile/netboot/vmlinuz
}}}

Start qemu as follows:
{{{
    qemu-system-arm \
        -M versatilepb \
        -cpu cortex-a8 \
        -hda rootfs.img \
        -m 256 \
        -kernel vmlinuz \
        -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
}}}

= System configuration =
After bootstrapping, a Debian/Ubuntu installation isn't quite complete; depending on the intended use, some final things have to be setup.

You might want to do some system configuration before using this rootfs on devics though; see [[#System configuration|System configuration]].

== fstab ==

The "mountall" process requires an entry in `/etc/fstab` for the root partition.  Normally, it's best to use UUIDs to refer to the rootfs as to be independent of the device path/name; for instance:
{{{
    UUID=01234567-89ab-cdef-0123-456789abcdef / ext4 relatime,errors=remount-ro 0 1
}}}
but for the initial machine emulation, just use the default disk path, e.g.:
{{{
    /dev/sda / ext4 relatime,errors=remount-ro 0 1
}}}

== Users and passwords ==

Set a root password with:
{{{
    passwd
}}}

and create an additional non-root user (e.g. ubuntu) with:
{{{
    adduser ubuntu
}}}

== APT sources ==

Edit etc/apt/sources.list and configure some APT sources; e.g. for Ubuntu 10.04 (lucid):
{{{
    deb http://ports.ubuntu.com/ubuntu-ports/ lucid main
}}}
(This will have been done already if you used `mk-sbuild`)

== Kernel ==

Install the official kernel, for later use.
{{{
    apt-get install linux-image-versatile
}}}

== Hosts and hostname ==

Give a name to the host device by creating an etc/hostname file with just the short name (e.g. qemu):
{{{
    qemu
}}}

And add a basic etc/hosts file referencing that short name and definit localhost:
{{{
    127.0.0.1 localhost qemu
}}}

== Virtual network setup ==

You probably want a loopback interface (lo) and if you're not using Network-Manager to setup the network, you probably want to bring up the virtual ethernet card; create an etc/network/interfaces file with:
{{{
    auto lo
    iface lo inet loopback

    auto eth0
    iface eth0 inet dhcp
}}}

== Serial console ==

TODO

= Creating an Image file from a directory =

First, check how much space the files from the rootfs dir would use when copied into a filesystem of a specific block size; for example for a blocksize of 4096 bytes (see the documentation of your filesystem to check which blocksize it uses):
{{{
    du -s -B 4096 rootfs
}}}
This will return the number of blocks which your filesystem uses, so multiply this number by the blocksize to get the minimum size of your filesystem.

Next, add to that amount the number in bytes of extra space you want in the filesystem.

Create a file, preferably a sparse one, which will hold the rootfs, for instance for a rootfs of 300 000 000 bytes:
{{{
    dd if=/dev/zero of=rootfs.img bs=1 count=0 seek=300M
}}}

Then format the filesystem, e.g. for ext4 with 4096 bytes blocks:
{{{
    mkfs.ext4 -b 4096 -F rootfs.img
}}}

Mount the filesystem and move the files over:
{{{
    mount -o loop rootfs.img /mnt
    sudo cp -a rootfs/. /mnt/
    umount /mnt
}}}

Copy the kernel to outside the image:
{{{
    cp rootfs/boot/vmlinuz* .
    ln -s vmlinuz-* vmlinuz
}}}

= Starting QEMU =

Now you can start QEMU on the disk image:
{{{
    qemu-system-arm \
        -M versatilepb -cpu cortex-a8 \
	-m 256 \
	-drive file=rootfs.img,media=disk \
        -kernel vmlinuz -append 'root=/dev/sda rootwait'
}}}