Instructions for System Administrator

1. Installing Scratchbox

You will need root privileges for this part of the Scratchbox installation.

  1. Uncompress the Scratchbox binary tar-ball to the / directory:

    # tar -zxvf /mnt/cdrom/scratchbox-version.tar.gz

    Note: before doing this, you may either wish to mount a partition with multiple gigabytes of free space to /scratchbox or make /scratchbox to be a sym-link to somewhere where you have adequate free space.

  2. After extraction, run the script:

    # /scratchbox/

    This will take some time as it e.g. copies all the (over 10000) device nodes from your /dev/ to /scratchbox/dev/. It will add sbox user group to your machine.

  3. Repeat this for each user of the Scratchbox:

    # /scratchbox/sbin/sbox_adduser username

    This will add the user to 'sbox' user group, create the Scratchbox user directory and mount several directories (/dev, /proc, /tmp) under user directory.

This is all that needs to be done as the root user for basic Scratchbox functionality.

(To be able to cross-compile more complex software which uses 'configure' scripts (such as glib, gtk, etc.) you need to enable the Scratchbox CPU Transparency feature. This is explained later on once you've compiled some software for x86 using the Scratchbox.)

2. Rebooting Scratchbox System

Rebooting your machine will clear away all the mounts that Scratchbox has done and CPU transparency registration for binfmt_misc. So, to get your Scratchbox working again after reboot, you have to run as root the command:

/scratchbox/sbin/sbox_ctl start

It will register the CPU transparency client and mount directories inside the sandbox. Alternatively you can add 'sbox_ctl' command as an init script to your /etc/init.d/ runlevel directories.

3. Upgrading Scratchbox

In case you already have installed an earlier version of Scratchbox, and just want to update it to one on the Scratchbox CD, this lists the steps in upgrading Scratchbox:

3.1. STEP 1

Before starting the upgrade, Scratchbox users should clean up the Scratchbox compiler cache, target and home directories from files which are specific to the old Scratchbox and it's toolchains and exit from Scratchbox shells, for example:

$ /scratchbox/users/[username]/ [sbox-ARM: ~] ccache -C [sbox-ARM: ~] sbox-config --reset-target [sbox-ARM: ~] sbox-config --select-target PC [sbox-PC: ~] sbox-config --reset-target [sbox-PC: ~] make -C [your source dir] distclean [sbox-PC: ~] exit

Rest of the operations have to be done outside Scratchbox as root, after nobody's using Scratchbox (people have exited from Scratchbox shells).

3.2. STEP 2

If you've used CPU Transparency, unmount your NFS mounts on the ARM device and stop the NFS server on your desktop machine so that you don't get stale NFS file handles on the ARM device.

On ARM device:

# umount $(mount|grep [your username])

On your desktop:

# /etc/init.d/nfs stop

3.3. STEP 3

Unmount all Scratchbox mounts on Scratchbox machine with the utility provided by Scratchbox:

# /scratchbox/sbin/sbox_umount_all

Then you can use the 'mount ' command to check if something is still mounted under the /scratchbox/ -directory. For more information, see "Uninstalling Scratchbox" in 4. Uninstalling Scratchboxfor Scratchbox installation instructions.

3.4. STEP 4

Move old Scratchbox (or a link to it) out of the way:

# cd / # mv scratchbox scratchbox.old

3.5. STEP 5

Install a new version of Scratchbox. Best is if you have each new scratchbox directory with it's own version number and just link that to directory required by Scratchbox:

# tar -zxvf /path/to/scratchbox-version.tar.gz -C / # mv /scratchbox /scratchbox-version # ln -s /scratchbox-version /scratchbox # /scratchbox/

For more information, see 1. Installing Scratchbox for the installation instructions.

3.6. STEP 6

Install all Scratchbox users that were in old Scratchbox to the new Scratchbox and copy their home directory contents there too:

# cd /scratchbox.old/users/ # for i in *; do /scratchbox/sbin/sbox_adduser $i; done # tar cf - */home|tar -C /scratchbox/users/ -xvf -

3.7. STEP 7

Make sure that the version of 'sbrshd ' daemon on your ARM device is same as the version of the 'sbrsh ' client in the Scratchbox . You can check this by giving '-v ' option to both.

If the same ARM device needs to be used by different Scratchbox versions, you can run the new Sbrshd daemon on a different port. New Scratchbox version users need then just to update their '.sbrsh' files to have the correct port number after the target IP address. For more information, see CPU transparency installation.

3.8. STEP 8

Check that your setup is otherwise OK:

# exit $ groups

if 'groups' doesn't report 'sbox' as one of the groups, you need to re-login so that your group information is updated.

3.9. STEP 9

Before restarting the NFS server for CPU transparency, you need to (re-)create your targets for the new Scratchbox version:

$ /scratchbox/users/[username]/ [sbox-PC: ~] sbox-config --list-compilers [sbox-PC: ~] sbox-config --create-target=ARM --compiler-name=[ARM compiler] [sbox-ARM: ~] exit $ su # /etc/init.d/nfs start # exit

3.10. STEP 10

Then you can test how the new Scratchbox works.

3.11. STEP 11

After testing the new Scratchbox you have two options:

3.12. STEP 12

Then the other Scratchbox users can add their Scratchbox cross-compilation targets back, this time using (possibly) updated compiler toolchains. Note that the target names should be the same, or NFS export file has to be edited correspondingly.

4. Uninstalling Scratchbox

Do NOT "uninstall" the Scratchbox or the user directories just using 'rm -r'! You would then remove also files from directories that are mounted under user directories (e.g. /tmp dir contains X11 socket, so you would need to relogin to X).

There's a utility called '/scratchbox/sbin/sbox_umount_all' which you have to use before removing the Scratchbox or any of it's user directories. You can use the 'mount' command to check if something is still mounted under the /scratchbox/ -directory.

After doing the unmounts, you can remove the Scratchbox.