scratchbox2
===========

scratchbox2 - ``sb2`` for short - is a cross-compiling environment. At its
core, it is simply a collection of bash scripts that set up and chroot into a
``qemu`` environment, yet there is much more to it: ``sb2`` has support for a
lot of different architectures, sets up all the needed paths and linker
variables, networking and many other features.

The scratchbox2 tool is developed at the mer project's GitLab instance under
`mer-core/scratchbox2 <https://git.merproject.org/mer-core/scratchbox2>`_.

``sb2`` is part of the :doc:`Sailfish SDK suite <sailfish-sdk>` and resides
at ``/usr/bin/sb2`` in the SDK chroot.

Usage
^^^^^

.. code::

   sb2 [OPTION]... [COMMAND] [PARAMETERS]

If no ``COMMAND`` is given, a bash shell in the scratchbox2 environment is
started.

Options
^^^^^^^

+-------------+----------------------------------------------------------------------------------------+
| Argument    | Explanation                                                                            |
+=============+========================================================================================+
| -v          | display version                                                                        |
+-------------+----------------------------------------------------------------------------------------+
| -L level    | enable logging (levels=one of error,warning,notice,net,info,debug,noise,noise2,noise3) |
+-------------+----------------------------------------------------------------------------------------+
| -d          | debug mode: log all redirections (logging level=debug)                                 |
+-------------+----------------------------------------------------------------------------------------+
| -h          | print this help                                                                        |
+-------------+----------------------------------------------------------------------------------------+
| -t TARGET   | target to use, use sb2-config -d TARGET to set a default                               |
+-------------+----------------------------------------------------------------------------------------+
| -e          | emulation mode                                                                         |
+-------------+----------------------------------------------------------------------------------------+
| -m MODE     | use mapping mode MODE                                                                  |
+-------------+----------------------------------------------------------------------------------------+
| -M file     | read mapping rules from "file"                                                         |
+-------------+----------------------------------------------------------------------------------------+
| -n NET_MODE | use networking rules NET_MODE                                                          |
+-------------+----------------------------------------------------------------------------------------+
| -s DIRECTORY| load mapping scripts from alternative location                                         |
+-------------+----------------------------------------------------------------------------------------+
| -Q BUGLIST  | emulate bugs of the old scratchbox 1 (BUGLIST consists of                              |
|             | letters: 'x' enables exec permission checking bug emulation)                           |
+-------------+----------------------------------------------------------------------------------------+
| -O options  | set options for the selected mapping mode ("options" is                                |
|             | a mode-specific string)                                                                |
+-------------+----------------------------------------------------------------------------------------+
| -R          | use simulated root permissions (activates the Vperm subsystem)                         |
+-------------+----------------------------------------------------------------------------------------+
| -U UID.GID  | use UID and GID as owner and group of "unknown" files                                  |
|             | (for all files that are unknown to the Vperm subsystem)                                |
+-------------+----------------------------------------------------------------------------------------+
| -p          | Do not simulate special FS privileges of the "root"                                    |
|             | user, when option -R is active                                                         |
+-------------+----------------------------------------------------------------------------------------+
| -S file     | Write session information to "file" (see option -J)                                    |
+-------------+----------------------------------------------------------------------------------------+
| -J file     | Don't create a new session; join an existing one (see -S)                              |
+-------------+----------------------------------------------------------------------------------------+
| -D file     | delete an old session (see -S). Warning: this does not                                 |
|             | check if the session is still in use!                                                  |
+-------------+----------------------------------------------------------------------------------------+
| -P file     | print all logs related to a persistent session (see -S)                                |
+-------------+----------------------------------------------------------------------------------------+
| -W dir      | Use "dir" as the session directory when creating the session                           |
|             | ("dir" must be absolute path and must not exist. N.B. long                             |
|             | pathnames here may cause trouble with socket operations)                               |
+-------------+----------------------------------------------------------------------------------------+
| -c          | When creating a session, also create a private copy                                    |
|             | of target_root (rootstrap). Note that this can be                                      |
|             | really slow, depending on the size of the orig.target_root                             |
+-------------+----------------------------------------------------------------------------------------+
| -C dir      | When creating a session, create copy of "dir" and use it as the                        |
|             | target_root (rootstrap).                                                               |
+-------------+----------------------------------------------------------------------------------------+
| -T dir      | use "dir" as tools_root (overriding the value from config file)                        |
+-------------+----------------------------------------------------------------------------------------+
| -u          | Disable automatic configuration upgrade.                                               |
+-------------+----------------------------------------------------------------------------------------+
| -g          | Create a new session with setsid(); useful when executing                              |
|             | commands in the background                                                             |
+-------------+----------------------------------------------------------------------------------------+
| -G file     | Append process group number to "file"                                                  |
+-------------+----------------------------------------------------------------------------------------+
| -b dir      | Produce graphs and log summaries to directory dir                                      |
|             | (implies '-L info', graphs are created by sb2-logz and                                 |
|             | 'dot', if the graphviz package is available)                                           |
+-------------+----------------------------------------------------------------------------------------+
| -B dir      | As -b, but also include process accounting data.                                       |
|             | (This may require special permissions, because acct(2)                                 |
|             | system call is used)                                                                   |
+-------------+----------------------------------------------------------------------------------------+
| -q          | quiet; don't print debugging details to stdout etc.                                    |
+-------------+----------------------------------------------------------------------------------------+
| -N          | Do not delete the session dir even if sb2 script fails to                              |
|             | enter the session                                                                      |
+-------------+----------------------------------------------------------------------------------------+
| -x OPTIONS  | specify additional options for "sb2d"                                                  |
+-------------+----------------------------------------------------------------------------------------+

Examples
^^^^^^^^

.. code::

    sb2 ./configure
    sb2 make
    sb2 -e make install
    sb2 -m emulate make install