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-static package.

The proper qemu-*-static binary must be properly configured
(eg. /etc/qemu-binfmt/arm pointing to /usr/arm-linux-gnueabi/ with
xapt-installed libc and possibly other packages); package
binfmt-support (which is only a "Recommends" of qemu-user-static) must
also be installed.

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 PLATFORM

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

In the normal case PLATFORM will contain some additional bits.

	PLATFORM/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.
	PLATFORM/debconfseed.txt - as the name suggests
	PLATFORM/hooks  - A directory that contains files that are sourced by
	                  polystrap after packages are installed.
	PLATFORM/packages - Contains files with one debian package per line.
	                    Grouping packages by that allows easier selection.
	PLATFORM/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 PLATFORM/config file can be overwritten by commandline
options:

	-s suite
	-a arch
	-d rootdir
	-m mirror

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

	-p packages

How the script works:

 *) re-execute itself in fakeroot
 *) source default/config
 *) source PLATFORM/config
 *) determine package selection by PLATFORM/packages or commandline argument
 *) create multistrap.conf in /tmp from PLATFORM/multistrap.conf
 *) run multistrap
 *) copy contents of PLATFORM/root
 *) copy qemu usermode binary
 *) set debconf selections
 *) run preinst scripts
 *) configure packages
 *) source PLATFORM/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.

Example config and multistrap.conf for usage of armhf is given in the default
directory as config.armhf and multistrap.conf.armhf. Some fakechroot bugs
(#611156) is unfortunately blocking this functionality right now.