SYNOPSIS

sb2 [options] [command] [arguments] [...]

DESCRIPTION

sb2 runs command in a scratchbox2 session. If no command is given, an interactive shell is started.

Scratchbox2 is typically used to create a transparent cross-compiling environment for developing programs and compiling software packages for e.g. embedded devices.

The environment created by sb2 has essential differences to the host OS environment:

First, a virtual file system view is presented to the applications. In practise that means that the file names (paths) which an application uses may be modified before the OS does its operations; applications observe a different file system that what the real file system is. For example, common directories like /bin, /usr/lib and /lib can be changed to point to target-specific directories, which contain files for a different CPU architecture than what the host has.

Second, scratchbox2 makes execution of foreign binaries completely transparent. Target's binaries can be executed on the host just as if they were host's binaries; scratchbox2 will start a CPU transparency method automatically whenever needed (Qemu is typically used for this).

The result is that the development machine appears as a virtual target system to the software development tools, and complex tools (like GNU Autotools) can be used directly.

Scratchbox2 works by intercepting library calls of dynamically linked binaries. It uses a flexible and highly configurable rule engine, when deciding when, what, and how to modify parameters of the intercepted calls; this is completely transparent to the users and applications. Scratchbox2 2 does not need any special privileges or kernel-level services; it is completely based on features that are available for all ordinary users.

Configuration data is stored to a target (see sb2-init(1) for details about creating a target). The target contains defaults for all settings that are needed when a session is created.

A new session is created every time when the sb2 command is used (unless one of the persistent session control options is present - see options -S,-J and -D below).

OPTIONS

-c

When creating a session, also create a private copy of the target root filesystem (rootstrap). Modifications done to the copy will be thrown away when the session is destroyed. Note that the copy operation can be really slow, depending on the size of the file system, but if the copy goes to a ramdisk, overall performance may much be better (see also option -W).

-C DIR

When creating a session, create copy of DIR and use it as the target root filesystem (rootstrap). Note that this can be really slow. See also option -c.

-d

Use debug mode: same as -L debug

-D FILE

Delete a persistent session associated with FILE. Warning: this does not check if the session is still in use! (see also -S and -J)

-e

Same as -m emulate: Use emulation mode, avoid executing any host binaries except qemu. See mapping modes below.

-f args

additional fakeroot arguments (see option -R)

-g

Create a new session with setsid(); useful when executing commands in the background (i.e. creates a system session and a new process group, and detaches from the controlling terminal. See setsid(2) for more info)

-G file

Append process group number to a file.

-h

Print help.

-J FILE

Join a persistent session associated with FILE (see also -D and -S)

-L LEVEL

Enable logging. Following values for LEVEL are available (in order of increasing level of details): error, warning, notice, info, debug, noise, noise2. The default is warning. Logs can be post-processed with sb2-logz, a tool which produces summaries and visualizes various things that were logged.

-m MODE

Use one of the pre-defined mapping modes. See mapping modes below.

-M FILE

Read mapping rules from FILE.

-O OPTIONS

Set options for the selected mapping mode. OPTIONS is a mode-specific string.

-Q BUGLIST

Emulate bugs of scratchbox 1 (BUGLIST consists of letters: 'x' enables exec permission checking bug emulation).

-r

Disable creating reverse mapping rules: functions like getcwd() and realpath() will always return the real path.

-R

"superuser mode": Execute commands in fakeroot environment (see fakeroot(1) for details). Depending on the selected mapping mode, this may also disables some mode-specific features, like simulated write protection of the target filesystem.

-s DIRECTORY

Use redirection rules from the DIRECTORY given in argument.

-S FILE

Create a persistent session: Write session information to FILE (see also -D and -J)

-t TARGET

Define TARGET to use. Use sb2-config -d TARGET to set a default.

-T DIRECTORY

Use DIRECTORY as tools_root (override the value which was specified to sb2-init when the target specification was created).

-u

Disable automatic configuration upgrade.

-v

Display version number.

-W DIR

Use DIR as the session directory when creating the session (The default is to create the session in /tmp). DIR must be an absolute path and must not exist. Note that long pathnames may cause trouble with socket operations, so try to keep DIR as short as possible.

EXAMPLES

sb2 ./configure

sb2 make

sb2 -eR make install

sb2 -R -m emulate make install

MAPPING MODES

Scratchbox2 contains several ready-made rulesets, called mapping modes, for different purposes. This manual page presents only the basics of each. Full details can be found from the rulesets themselves.

There are three development-oriented modes, that are intended for cross-compilation:

"simple" makes only the very basic modifications to the file environment: For example, /usr/include refers to /usr/include in the target root file system, not to the real /usr/include of the host (and the same applies to /lib, /usr/lib, and many other directories). Typical toolchain commands, i.e. commands that are used to create binary programs (like gcc, as and ld) refer to tools that were supplied with the the cross-compiler which was configured with sb2-init (also when used with full pathname: /usr/bin/gcc, /usr/bin/as, etc)

The "simple" mode usually takes other tools directly from the host OS. This approach means that simple tools work fine, and well-behaving OSS projects can be compiled with the "simple" mode. The drawback is that there are some cases, where such a simple approach fails.

The other two development modes, "accel" and "devel" have more complete support for different tools, but these are not necessarily as easy to set up as the "simple" mode is. Both "accel" and "devel" are intended to be used with a separate "tools root" directory, consisting of host-compatible binaries of the same programs that exist in the target file system as foreign binaries (e.g. target root can contain arm binaries, whereas tools root has x86 binaries of the exactly versions of the same programs). This is configured with the -t option of sb2-init(1).

In addition to the development-oriented modes, scratchbox2 also has an "emulate" mode, which sets up an environment without development tools: It maps as many paths to the target root as possible. It can be used for installing programs to the target filesystem and testing them.

"tools" mode is very much like "emulate", except that there most things are mapped to tools root.

"nomap" mode is a special mapping mode, which is mostly useful only for debugging purposes: It does not apply any file system related mappings, but otherwise scratchbox2 functions are fully operational.

FILES

$HOME/.scratchbox2/*

$HOME/sb2_logs

/usr/share/scratchbox2/*

AUTHORS

Lauri T. Aarnio, Riku Voipio