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

2.2                                               1 April 2012                                            sb2(1)