diff options
Diffstat (limited to 'polystrap/README')
| -rw-r--r-- | polystrap/README | 156 |
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. |