.TH sb2 1 "1 April 2012" "2.2" "sb2 man page"
.SH NAME
sb2 \- crosscompiling environment
.SH SYNOPSIS
.B sb2
[options] [command] [arguments] [...]
.SH DESCRIPTION
.B sb2
runs command in a scratchbox2 session. If no command is given, an interactive shell is started.
.PP
Scratchbox2 is typically used to create a
.I transparent cross-compiling environment
for developing programs and compiling software packages for e.g. embedded devices.
.PP
The environment created by
.B sb2
has essential differences to the host OS environment:
.PP
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.
.PP
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 
.I CPU transparency method
automatically whenever needed (Qemu is typically used for this).
.PP
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.
.PP
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.
.PP
Configuration data is stored to a
.I 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.
.PP
A new session is created every time when the
.B sb2
command is used (unless one of the persistent session control options is present -
see options -S,-J and -D below).
.SH OPTIONS
.TP
\-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).
.TP
\-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.
.TP
\-d
Use debug mode: same as
.B -L debug
.TP
\-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)
.TP
\-e
Same as
.B -m emulate:
Use emulation mode, avoid executing any host binaries except qemu.
See
.B mapping modes
below.
.TP
\-f args
additional fakeroot arguments (see option -R)
.TP
\-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)
.TP
\-G file
Append process group number to a file.
.TP
\-h
Print help.
.TP
\-J FILE
Join a persistent session associated with FILE (see also -D and -S) 
.TP
\-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
.I warning.
Logs can be post-processed with 
.I sb2-logz,
a tool which produces summaries and visualizes various things that were logged.
.TP
\-m MODE
Use one of the pre-defined mapping modes.  See
.B mapping modes
below.
.TP
\-M FILE
Read mapping rules from FILE.
.TP
\-O OPTIONS
Set options for the selected mapping mode. OPTIONS is a mode-specific string.
.TP
\-Q BUGLIST
Emulate bugs of scratchbox 1 (BUGLIST consists of letters: 'x' enables exec permission checking bug emulation).
.TP
\-r
Disable creating reverse mapping rules: functions like getcwd() and realpath() will always return the real path.
.TP
\-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.
.TP
\-s DIRECTORY
Use redirection rules from the DIRECTORY given in argument.
.TP
\-S FILE
Create a persistent session: Write session information to FILE
(see also -D and -J)
.TP
\-t TARGET
Define TARGET to use. Use
.I sb2-config -d TARGET
to set a default.
.TP
\-T DIRECTORY
Use DIRECTORY as tools_root (override the value which was specified to sb2-init when the target specification was created).
.TP
\-u
Disable automatic configuration upgrade.
.TP
\-v
Display version number.

.TP
\-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.

.SH EXAMPLES
.TP
sb2 ./configure
.TP
sb2 make
.TP
sb2 -eR make install
.TP
sb2 -R -m emulate make install

.SH MAPPING MODES
Scratchbox2 contains several ready-made rulesets, called
.I mapping modes,
for different purposes. This manual page presents only the
basics of each. Full details can be found from the
rulesets themselves.
.PP
There are three development-oriented modes, that are intended for
cross-compilation:
.PP
"simple" makes only the very basic modifications to the file environment:
For example,
.I /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
.I gcc, as
and
.I ld)
refer to tools that were supplied with the the cross-compiler which was configured with
.I sb2-init
(also when used with full pathname: /usr/bin/gcc, /usr/bin/as, etc)
.PP
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.
.PP
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).
.PP
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.
.PP
"tools" mode is very much like "emulate", except that there most
things are mapped to tools root.
.PP
"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.

.SH FILES
.P
.I $HOME/.scratchbox2/*
.P
.I $HOME/sb2_logs
.P
.I /usr/share/scratchbox2/*
.SH SEE ALSO
.BR sb2-init (1),
.BR sb2-config (1),
.BR sb2-show (1),
.BR sb2-logz (1),
.BR sb2-session (1),
.BR fakeroot (1),
.BR qemu (1)
.SH BUGS
No known bugs at this time.
.SH AUTHORS
.nf
Lauri T. Aarnio, Riku Voipio
.fi