sb2-init(1) [debian man page]
sb2-init(1) sb2-init man page sb2-init(1) NAME
sb2-init - initialize a target for scratchbox2 SYNOPSIS
sb2-init [OPTION]... [TARGETNAME] [COMPILER[:SPECS]] [SECONDARY_COMPILER...] DESCRIPTION
sb2-init initializes a target for scratchbox2. If no options or other parameters are given, already initialized targets are listed. A scratchbox2 target is simply a light-weight, symbolic name for a configuration set. A target does not contain anything that is active, like running processes; hence a user never "works inside a target". Instead, sessions are used for all active operations. Sessions are created by the sb2 command. sb2-init is expected to be run in the directory you want to use as the target root filesystem. TARGETNAME is the name of the target to initialize. If it refers to an existing target, then the target is re-initialized. Otherwise a new one is created. COMPILER is full path to a cross-compiler (gcc), of the form $HOME/arm-2006q3/bin/arm-linux-gcc. An optional SPECS parameter is path to the compiler specs file. If more than one compiler is specified, additional compilers are available by version number (e.g. if the primary is known as "gcc" and "gcc-4.1", the secondary may be "gcc-3.4", etc) Note that the compiler is usually used during the target creation process to determine CPU architecture of the target system. OPTIONS
-c "command" specify cpu transparency command, for example: "qemu-arm", "sbrsh" or "qemu-arm -R 256M". CPU transparency method is the program which is used to execute foreign binaries, that the host computer can not execute directly. -p "command" specify cpu transparency command for staticly linked native binaries. -r [hostname] generate sbrsh config using remote device address -l [hostname] NFS server/localhost address seen by remote device -d set target as default scratchbox2 target (default target can also be set later with the sb2-config command) -m [mapping_mode] use mapping_mode as default. Default for this is "simple" -h Print help. -n don't build libtool for the target -N don't generate localization files for the target -s skip checks for target root's /usr/include etc. -t [tools_dir] set directory containing the build tools distribution -C "options" add extra options for the compiler, for example: -C "-fgnu89-inline" -A arch manually override target architecture -M arch manually override machine name (see uname(2)). This defaults to the target architecture (see option -A) -v display version EXAMPLES
mkdir $HOME/buildroot cd $HOME/buildroot [fetch a rootfs from somewhere and extract it here] sb2-init -c qemu-arm TARGET /path/to/cross-compiler/bin/arm-linux-gcc FILES
$HOME/.scratchbox2/* SEE ALSO
sb2(1), sb2-config(1), qemu(1) BUGS
No known bugs at this time. AUTHORS
Lauri T. Aarnio 2.2 17 December 2010 sb2-init(1)
Check Out this Related Man Page
sb2(1) sb2 man page sb2(1) 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 applica- tion 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 applica- tions. 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 set- tings 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 visu- alizes 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 possi- ble. 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 map- pings, 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)