SCRATCHBOX 2 README author: Lauri Leukkunen date: 2008-01-03 LICENSING All files are licensed under GNU LGPL version 2.1 unless specifically stated otherwise in the file itself. GENERAL NOTICE This is development code, it is broken. Don't expect to use it for anything resembling production use. However, I firmly believe this is infinitely more functional than Scratchbox 1.x can ever be. INSTALLATION You need git to work with sbox2, get it from http://git.or.cz/. Clone the scratchbox 2 repository: $ git clone git://anongit.freedesktop.org/git/sbox2 There are two ways to build sb2, with and without multilib support. To be able to run 32bit binaries on a 64bit host, do this: $ cd sbox2 $ ./autogen.sh $ make install-multilib prefix=$HOME/scratchbox If you only want your host's "native" version of the library, do: $ cd sbox2 $ ./autogen.sh $ ./configure --prefix=$HOME/scratchbox $ make install You need Qemu for cpu-transparency. As of 2007-09-11 it's recommended to use debian/unstable's qemu-0.9.0+20070816-1 (or newer), it's by far the best that can be used with sb2. Qemu has many issues on amd64 host systems, at least when trying to do user-space emulation of ARM. Better results can be achieved on 32bit i386 hosts. If you're targeting ARM you can get a good toolchain from CodeSourcery: http://www.codesourcery.com/gnu_toolchains/arm/download.html You need to build sb2 with multilib support to use CodeSourcery toolchains on amd64 host. Notice! Old Scratchbox 1 toolchains don't work with sb2. To use sb2 you need to get a rootfs for your target and put it into some useful directory, alternatively you can copy the necessary files into right places from your toolchain. The essential thing is that sb2 needs FHS compliant target directory structure to work. For an example of such a system you can look at the Maemo example later in this README. To complete sb2 target setup: $ mkdir $HOME/buildroot $ cd $HOME/buildroot [extract or copy your rootfs contents into place] $ $HOME/scratchbox/bin/sb2-init my_target /path/to/compiler/bin/arm-linux-gcc That will automatically generate a working target config for the compiler given on the command line and run sb2-build-libtool script to get you a nice working libtool for your compiler. If the sb2-build-libtool part fails for some reason (incorrect http proxy or something similar), you can always run it manually later. At this point you can simply run sb2: $ $HOME/scratchbox/bin/sb2 sb2-init made this target your default if you had no prior sb2 targets configured. To change the default use sb2-config -d your_target. Perhaps adding $HOME/scratchbox/bin to your PATH is also a good idea, put this in your $HOME/.bashrc: -- snip -- export PATH=$PATH:$HOME/scratchbox/bin -- snip -- After that you can run sb2 easily from anywhere and it'll just do its magic. MAEMO DEVELOPMENT First install sb2 as described above, or if you're using debian testing or unstable you can simply "apt-get install scratchbox2". If you're running a non-debian system you need to debootstrap debian/etch to some directory, sb2 can use it as a tool distribution. Download the latest rootstrap from: http://repository.maemo.org/stable/3.1/armel/maemo-sdk-rootstrap_3.1_armel.tgz Extract that to $HOME/maemo-root Edit $HOME/maemo-root/etc/apt/apt.conf so that it looks like this: -- snip -- APT { Architecture armel; } -- snip -- Then get a nice toolchain from the locations mentioned above. After that you can setup sb2 by running: $ cd $HOME/maemo-root $ sb2-init -m maemo maemo /path/to/compiler/bin/arm-none-linux-gnueabi-gcc If you want to use a separate tool distribution, do this instead: $ sb2-init -m maemo -t /etch_root maemo /path/to/compiler/bin/arm-linux-gcc Now you should have a fully functioning development environment. To try it out you can build for example fontconfig like this: $ sb2 apt-get source fontconfig $ cd fontconfig-2.4.1 $ sb2 dpkg-buildpackage -rfakeroot -d You don't need to be in $HOME/maemo-root to do that, I typically do all development work in $HOME/src. The "-d" switch is needed to skip checking build dependencies, this is one of the remaining TODO items of SB2. DIAGNOSING PROBLEMS WITH SB2 Sometimes everything does not work as expected, so it is good to know how to locate problems (typically problems are related to misconfigured mapping rules). Scratchbox 2 can produce extensive logs about all operations, but it does not do so by default. So the first step is to enable logging: Use the "-d" or "-L " options of "sb2". For example, $ sb2 -L info dpkg-buildpackage -rfakeroot -d will produce a log of most important actions that were performed by "dpkg-buildpackage" and all subprocesses started by it. The log will be created under ~/sb2_logs/ (The above command will also print out the exact name and location of the logfile.) The produced logfile can be quite huge, especially when using the higher logging levels. A logfile analyzer script, sb2-logz, can be used to extract essentials like error and warning messages and path mapping actions from the logged information; log level 'info' in enough for anything that sb2-logz needs. Higher logging levels ('debug', etc) are mostly useful only for developers of scratchbox 2. Another useful helper tool is "sb2-show", an utility which can be used to test path and command mapping rules while scratchbox 2 is active. For example, $ sb2-show path /etc/apt $ sb2-show -b apt-get path /etc/apt will show how the /etc/apt database has been mapped. The latter command uses "apt-get" as the name of the calling program (the results may be different depending on mapping mode, name of the calling program, etc) sb2-show can also be used to see how parameters to certain processes will be modified: $ sb2-show exec gcc foo.c shows which "gcc" would be started inside the sb2 session, together with the actual, possibly modified, arguments. The result depends on how sb2 was configured (see notes about sb2-init above) -- That's all folks, enjoy!