polystrap/README

Polystrap is a tool to create a foreign architecture rootfs without needing
superuser privileges by using multistrap, fakeroot, fakechroot and qemu user
mode emulation from the qemu-user package.


QEMU USER MODE
==============

qemu >= 1.0 is required for this to work out of the box. For older qemu
versions, the (now outdated) instructions in the rest of this section:

To make qemu user mode emulation work you need to install the packages
qemu-user and binfmt-support. Until bug #632192 is fixed you will have to
provide properly filled /etc/qemu-binfmt/$arch/ directories. $arch is a qemu
arch (eg: arm for arm, armel and armhf). "properly filled" means, that you have
to provide a root directory tree in that directory that fits the architecture
you want to bootstrap debian for. There are a couple of ways to achieve that:

1. manually download and `dpkg -x` the required packages into
/etc/qemu-binfmt/$arch/

2. copy over a just extracted multistrap run for your target system into
/etc/qemu-binfmt/$arch/

3. run the following multistrap.conf, configured for your target system to
create a root directory tree that you copy into /etc/qemu-binfmt/$arch/

-%<----------------------------
[General]
arch=
directory=
cleanup=true
unpack=true
noauth=true
aptsources=Debian
bootstrap=Debian
allowrecommends=false
addimportant=false
omitrequired=true

[Debian]
packages=libc6 libselinux1 libacl1 man-db libstdc++6 libfreetype6 libx11-6 libfontconfig1
source=http://cdn.debian.net/debian
suite=sid
omitdebsrc=true
-%<----------------------------

You can also avoid all this trouble by either waiting for #632192 to be fixed
or by applying the patch from there to qemu.

Since support for QEMU_LD_PREFIX has now been added upstream it is now already
part of polystrap.sh


FAKEROOT/FAKECHROOT
===================

Additionally you will need to have copies of libfakechroot.so and
libfakeroot-sysv.so for your target architecture in /usr/lib/<arch-triplet>/.
Get the debian packages of fakeroot and fakechroot for your target architecture
and copy the shared libraries into /usr/lib/<arch-triplet>/. For example for
armel do:

sudo mkdir -p /usr/lib/arm-linux-gnueabi/
wget http://ftp.debian.org/debian/pool/main/f/fakeroot/fakeroot_1.18.1-1_armel.deb
dpkg-deb --fsys-tarfile fakeroot_1.14.5-1_armel.deb | sudo tar -xf - --strip-components=4 -C /usr/lib/arm-linux-gnueabi/ ./usr/lib/libfakeroot/libfakeroot-sysv.so
wget http://ftp.debian.org/debian/pool/main/f/fakechroot/libfakechroot_2.15-1_armel.deb
dpkg -x libfakechroot_2.15-1_armel.deb /

Alternatively, since libfakechroot is multiarch you can also do:

apt-get install libfakechroot:armel

if your system supports it instead of the last two lines.


INNER WORKINGS
==============

While I wanted to build without superuser privileges, multistrap would never
offer mechanisms that would allow me to do so. Hence I wrote this script which
wraps multistrap. Since I wanted to keep it as simple as possible, a fully
functional polystrap will need nothing more than a multistrap.conf, a hooks
directory and a rootfs tree skeleton. Stuff like packages directory, and config
file are optional and can be replaced by editing multistrap.conf and passing
commandline options. Without comments the scripts is currently around 120 lines
and I have no intention to make it much more complex.

Polystrap is invoked as such:

	./polystrap.sh BOARD

BOARD is a directory that at least contains a multistrap.conf. The
multistrap.conf may contain variables from polystrap.sh.

In the normal case BOARD will contain some additional bits.

	BOARD/config - A file that is sourced by ./polystrap.sh and
	                  contains variable declarations like:
	                      SUITE   - stable, testing, unstable
	                      ARCH    - armel, armhf, amd64, i386
	                      ROOTDIR - where the rootfs is created
	                      MIRROR  - debian mirror to use for packages
	                  The file is not strictly needed because the options
	                  can also be set by commandline arguments and the
	                  script will fall back to ./default/config.
	                  Correct settings for ARCH and ROOTDIR are necessary
	                  for proper operation, whereas other parameters are
	                  only used if your multistrap.conf references them.
	BOARD/debconfseed.txt - as the name suggests
	BOARD/hooks  - A directory that contains files that are sourced by
	                  polystrap after packages are installed.
	BOARD/packages - Contains files with one debian package per line.
	                    Grouping packages by that allows easier selection.
	BOARD/root   - Contains a rootfs tree that is copied to the target
	                  directory after packages are unpacked by multistrap.

Reasonable examples of how those pieces look like can be found in the defaults
directory.

Everything from the BOARD/config file can be overwritten by commandline
options:

	-s suite
	-a arch
	-d rootdir
	-m mirror
	-v verbose (set -x)
	-f force (overwrite existing directories)

Additionally the following option allows to specify a list of packages that is
then used instead of the contents of the BOARD/packages directory:

	-p packages

How the script works:

 *) re-execute itself in fakeroot
 *) source default/config
 *) source BOARD/config
 *) determine package selection by BOARD/packages or commandline argument
 *) create multistrap.conf in /tmp from BOARD/multistrap.conf
 *) run multistrap
 *) copy contents of BOARD/root
 *) copy qemu usermode binary
 *) set debconf selections
 *) run preinst scripts
 *) configure packages
 *) source BOARD/hooks
 *) cleanup
 *) generate tarball

When creating a directory for a new target one can either just copy the defaut
directory or use the ./newtarget.sh script which will use symlinks where it
makes sense, will not copy the whole package selection and will set hostname
according to the target name.