Provided by: scratchbox2_2.2.4-1debian1_amd64 
NAME
sb2 - crosscompiling environment
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/*
SEE ALSO
sb2-init(1), sb2-config(1), sb2-show(1), sb2-logz(1), sb2-session(1), fakeroot(1), qemu(1)
BUGS
No known bugs at this time.
AUTHORS
Lauri T. Aarnio, Riku Voipio