initial import of 'polystrap' debian tool

From http://anonscm.debian.org/gitweb/?p=emdebian/polystrap.git;a=summary

This imports 83ba112abb8f173254c60611b5a24ca0a72ca58f, from
from Tue, 9 Oct 2012 15:36:02 -0400 (21:36 +0200)

1 files changed, 156 insertions, 0 deletions

diff --git a/polystrap/README b/polystrap/README
new file mode 100644
index 000000000..a781bfcad
--- /dev/null
+++ b/polystrap/README
@@ -0,0 +1,156 @@
+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.