A sandbox represents a developer's private build area. To avoid the need to compile an entire project, only the small pieces currently being modified by the developer are normally copied to the user's sandbox. The remainder of the build environment comes from one (or more) backing trees to which the user has read-only access. The backing tree will hold an image of the source and compiled objects and libraries for the target architecture.
The use of backing trees requires some support from the underlying build system and appropriate construction of Makefiles (or their equivalent). Systems with the needed functionality include GNU Make, CMake and Scons. The fundamental ideas are to separate the output directories for objects from the directories holding the source code and exploit a mechanism like GNU Make's VPATH to search multiple directories for a required dependency.
Note: while it is typical for a sandbox to be backed by a single backing tree, this implementation permits multiple backing trees to be chained. This is often used when developers are collaborating on experimental or incompatible changes; an intermediate backing tree is used to share work in progress and override images that would normally have come from a production backing tree.
At a given moment in time, a sandbox is typically associated with a single target architecture. It can be rebased to a different target architecture using the resb command and the sb_retarget command will automatically be run on the next workon invocation to regenerate any architecture-specific configuration files.
A developer may use multiple sandboxes to keep progress on independent work units separated; common best practice is to pursue work on only one feature or defect in a given sandbox, though sometimes work units are interrelated. It is almost always a bad idea to tackle an emergency bug fix in a sandbox were work was already underway; these unscheduled but focused work activities should be handled in a distinct sandbox that is removed after the bug fixes are committed. Sandboxes can be rebased against historical backing trees to compile a new version of previously deployed executables and libraries while remaining compatible with the data structures as they were defined for those releases. This is most useful when releasing object-code-only distributions and one needs to apply bug fixes against releases previously shipped to customers, which may have incompatible data structure layouts and function names, etc. that differ from the current source code images.
A user's sandbox descriptions are stored in a sandbox rc file,
typically $HOME/.sandboxrc. It can be
overridden by the -rc fileName argument
on most commands. While logically a “database” that
maintains a list of sandboxes and their associated attributes, this
is realized via a simple text file structure and it can be modified
by a text editor if the need arises.
The following commands are used when working with sandboxes. Each command is described in detail later.
/opt/backingTrees.
$HOME/sandboxes.
$HOME/.sandboxrc.A backing tree directory structure can be prepared using the mkbt command. Depending on the administrative environment, this command might normally only be used by an administrator preparing shared resources, but it can be used by a single developer who specifies a backing tree root under their respective home directory. Most sandbox users will not have occasion to use the mkbt command. The most common usage of this utility is from automatically run scripts created by an administrator that setup a build tree, extract current source from a source code repository and perform a compile.
usage: mkbt [ btroot btRoot] [ ta targetArchitecture] ... bt backingTree [...]
-btroot = specify alternate backing tree root, default is "/opt/backingTrees"
-ta = target architecture, default is native;
"all" means prepare for all supported
"avail" means prepare for all locally supported
The root of backing tree is normally obtained from BT_ROOT_DIR, which defaults to /opt/backingTrees if not set.
The mkbt command prepares several architecture-specific directories and configuration files. If no target architecture is specified, only configuration related to the local native build architecture is performed. The alias of “avail” can be used to set up the configuration for all locally-supported architectures. The alias of “all” can be used to set up the configuration for all known architectures.
In some environments, there may be no distinction between these three options. However, a not atypical case would be an environment where a cross-compiler exists for Windows on Linux x86 systems and is not present on Sun SPARC hardware running Solaris nor PowerPC hardware running AIX or Linux. Similarly, native compilation by Microsoft Visual Studio might be a known platform, but it would not be performed by the Linux or Solaris hosts. If the backing tree is to be visible to all platforms (requiring it to be exported as a networked file system), then using “-ta all” is arguably the best choice. If hosts have their own copies of backing trees, then “-ta avail” could be preferred.
A user can create a new sandbox tree using the mksb command. A sandbox root starting with the user's HOME directory will be altered to replace that prefix with “~”. This permits the sandbox configuration file to be used on alternate hosts that might mount the network file system holding the user's home directory in a different location. This issue frequently arises when one host “owns” the user's home directory and other hosts (perhaps running different operating systems) have different naming conventions.
usage: mksb [ i] [ rc rcFile] [ btroot btRoot=/opt/backingTrees] [ sbroot sbRoot=/home/geoff/sandboxes] [ desc description] [ ta targetArch] [ force] sb sandboxName bt backingTree [...]
-i = interactive mode
-rc = specify alternate rc file, default is "$HOME/.sandboxrc"
-btroot = specify alternate backing tree root, default is "/opt/backingTrees"
-sbroot = specify alternate sandbox root, default is "$HOME/sandboxes"
-desc = descriptive note for sandbox to help identify its purpose
-ta = desired target architecture
-force = allow mksb to tolerate existing sandbox directory
The resb command can be used to rebase an existing sandbox. Normally installed as an alias for mksb. If already in a workon shell, the sb sandbox argument may be omitted and will be inferred to be the current sandbox.
usage: resb [-i] [-rc rcFile] [-btroot btRoot=/opt/backingTrees] [ sbroot sbRoot=/home/geoff/sandboxes] [ desc description] [ ta targetArch] sb sandboxName bt backingTree [...]
-i = interactive mode
-rc = specify alternate rc file, default is "$HOME/.sandboxrc"
-btroot = specify alternate backing tree root, default is "/opt/backingTrees"
-sbroot = specify alternate sandbox root, default is "$HOME/sandboxes"
-desc = descriptive note for sandbox
-ta = desired target architecture
Some build environments may require configuration files to be updated when a sandbox's target architecture has been changed. The sb_retarget utility is an internal script that will automatically be run by the first workon performed after a resb command alters the target architecture (using the -ta argument). The current implementation deals with regeneration of Makefiles derived from CMakeLists.txt files; if the build system does not use cmake, the script has no effect.
The rmsb command is used to remove an existing sandbox. It is normally installed as an alias for mksb. An existing sandbox's corresponding entries will be deleted from the sandbox rc file; however the local sandbox directory structure will not be removed unless the -force flag is specified. If more than one sandbox name referenced the same sandbox tree, rmsb will refuse to delete the sandbox tree.
usage: rmsb [ i] [ rc rcFile] [ force] sb sandboxName
-i = interactive mode
-rc = specify alternate rc file, default is /home/user/.sandboxrc
A list of available backing trees can be obtained with the lsbt command. The backing tree names are normally separated by colons, but this character can be overridden with the -s option.
usage: lsbt [{ n| f}] [ s separator] [ btroot backingTreeRoot=/opt/backingTrees]
-n = list only backing tree name
-f = list full path name of backing tree (default)
-btroot = backing tree root, default is "/opt/backingTrees"
default output separator: ":"
The sandboxes maintained by a user can be obtained with the lssb command. One sandbox name is displayed per output line. If verbose mode is selected with the -v option, the root directory and description of the sandbox will also be displayed.
usage: lssb [ v] [ rc rcFile]
-rc = alternate rc file, default is $HOME/.sandboxrc
The sbinfo utility is a convenience program used to display information about the current sandbox.
The output looks similar to:
sandbox: sbconv targetArch: Linux.x86_64 buildArch: Linux.x86_64
The workon command is the most frequently used sandbox-related command because one only creates a sandbox once, but will frequently workon it. The workon command can be used to run commands in the context of a sandbox, but usually the command argument will not be specified. If a command is not specified, a sub-shell is created with the appropriate environment. The shell to be used will be taken from the SB_SHELL environment variable; if this is not set, the current SHELL will be used.
The SB_USE_SSH_AGENT environment variable can be set to either 1 or 0 (it defaults to 0). If set to 1 or -ssh is specified, then an ssh-agent is automatically started if one was not already available and the user's ssh keys are added to it. In contrast, the -nossh option prevents the launch of an ssh-agent and loading of the user's ssh keys. In development environments that make use of cross-machine file transfers and have the appropriate public keys distributed amongst the host population, SB_USE_SSH_AGENT will normally be set to 1.
usage: workon sb sandboxName [ ta targetArchitecture] [ bt backingTree] [ ba buildArchitecture] [ rc rcFile] [{-ssh | -nossh}] [cmd ....]
-ta = specify target architecture
-rc = override sandbox rc file, default="$HOME/.sandboxrc"
-bt = override backing tree
-ba = specify build architecture (not normally used)
-ssh = setup ssh keys and start ssh-agent if needed
The buildArch command is used to display the available target architectures supported by the build infrastructure.
usage: buildArch [ s separator] [ btroot backingTreeRoot] [ ba | ta | all]
-all = list all available architectures
-ba = list current build architecture
-ta = list current target architecture
The getsbattr command implements a standard interface for retrieving sandbox-related attributes. This interface should be used in preference to directly accessing the sandbox rc file as it permits all of the implementation details to be altered without requiring modifications to applications. The sandbox name is optional if used within a workon session as it defaults to the name of the local sandbox.
usage: getsbattr [ v] [ null] [ sb sandboxName] [ rc rcFile] attrName ...
-v = prefix results with attribute name
-null = report null string rather than [undefined]
The setsbattr command implements a standard interface for modifying sandbox-related attributes. This interface should be used in preference to directly accessing the sandbox rc file as it permits all of the implementation details to be altered without requiring modifications to applications. The sandbox name is optional if used within a workon session as it defaults to the name of the local sandbox.
Attribute value pairs can be specified using contiguous elements with an equals-sign separator or as space-separated pairs.
usage: setsbattr [ sb sandboxName] [ rc rcFile] attrName=value ...
The setsbattr command implements a standard interface for modifying sandbox-related attributes. This interface should be used in preference to directly accessing the sandbox rc file as it permits all of the implementation details to be altered without requiring modifications to applications. The sandbox name is optional if used within a workon session as it defaults to the name of the local sandbox.
usage: delsbattr [ sb sandboxName] [ rc rcFile] attrName ...
The pathedit command is a generic convenience utility that can append, prepend or remove elements from a list, typically a colon-separate list of directories.
usage: pathedit [{ a| r| p}] [ s separator] initialPath arg [...]
-a = append, -p = prepend, -r = remove
default mode: "a" separator: ":"
The findFile command is a generic convenience utility that will search a set of colon-separated directory paths for a file. If no file is found, an exit status of 1 is returned; otherwise 0 is returned. The full path name of the found files is displayed, one per line.
usage: findFile [ 1 | all] [ s separator] fileOrDirName path [...]
path can contiguous elements, default separator is a colon
-s separator = define alternate path separator character
-1 = report first entry found only (-2 = first two, etc.)
-all = report all entries found (default)
In the context of a sandbox, findFileInSB will search a set of sandbox trees for a file appearing at the corresponding location in the chain of sandbox trees. Any file name paths that are passed as an absolute path name (i.e., beginning with a “/”) or explicitly relative to the current or parent directory are returned as-is; no search will be performed. This utility is commonly used by scripts to locate the Makefile for a sandbox or appropriate configuration files. The -all option searches all trees whereas -allbt selects all backing trees but not the local sandbox; -sb selects the local sandbox tree, -bt1 selects for first backing tree, -bt2 selects the second backing tree, etc.
usage: findFileInSB [ q] [ s separator] [ d additionalDir] { all | allbt | sb | bt1 | bt2 | ... } ... fileName [...]
The insb command is a convenience utility that allows one to invoke a command with file name arguments that are obtained after having located the indicated file using findFileInSB. For example, “insb vi Makefile” will start the vi text editor using the file name of the Makefile corresponding to the current location in the sandbox tree. Arguments and anything that can not be resolved to a file name will be passed as-is. There are two special cases. If a file name begins with the “@” character, the local sandbox will not be searched. If a file name begins with the “%” character, the file name portion will be used as-is. Example usage:
insb vi source.c
insb gvimdiff source.c @source.c
insb lpr -P :printer2 source.h
usage: insb command fileName [...]
NOTES: arguments beginning with "-" are passed as-is.
If a fileName begins with "%", the fileName portion is used as-is.
If a fileName begins with "@", the local sandbox is not searched.
This is useful to compare local vs. backing tree files:
insb diff source.c @source.c
The sbdiff command is a sandbox-aware convenience utility that is typically used to display differences between the image of a file in a local sandbox and its original state or current state in a source code repository.
usage: sbdiff [{ r revision | local | committed }] [ diff] [ nows] [ using prog] fileName [...]
By default, the differences between the original state of the file and its current local (-local) state are displayed to highlight the modifications that have been made. An explicit revision can be specified or the most recent committed version can be selected using the -committed flag.
If differences in white space are not intended to be significant, the -nows option can be specified.
By default, the gvimdiff program will be used to visually display the contrast between the selected files; however, the -diff option can be used to select the text-only output from the diff utility and the -using option can be used to specify an arbitrary comparison program.
The sbmake utility is a cover script for a make-like program that searches the sandbox and backing trees for a corresponding makefile. By default, it will search for sb.Makefile, Makefile and makefile. Note that this order is not identical to that of GNU make, which looks for makefile before Makefile. An arbitrary set of potential file names can be specified using the -f option in appropriate combinations.
The desired make command can be provided in the SB_MAKE_COMMAND environment variable or via the -m command line option; it defaults to /usr/bin/make.
Note: the absolute path is used to avoid any possibility of sbmake recursively invoking itself, but this does require that the SB_MAKE_COMMAND environment variable be set appropriately if the make program to be used is not /usr/bin/make.
usage: sbmake [ m makeCmd] [ C dir] [ f file][...]
Developers who do not want to add sbmake into their repertoire of commands can add an alias for make to sbmake, but this is perhaps best done in $STS/BuildEnv/shell_rc.csh:
setenv SB_MAKE_COMMAND `which make`
alias make sbmake
or $STS/BuildEnv/shell_rc.bash:
SB_MAKE_COMMAND=`which make; export SB_MAKE_COMMAND
alias make sbmake
The sbmake utility works outside of the context of a sandbox, so it is feasible to use it in situations where make would normally have been invoked. For example, as the makeprg in $HOME/.vimrc:
:set makeprg=/opt/backingTrees/bin/sbmake\ $*
The sbrel utilty outputs the subtree path below a sandbox or backing tree. It is most often used on the command line to conveniently switch between directories, but can be used by scripts to determine the context of a directory path. The path to be evaluated is normally taken from the current working directory, but can be provided as a command line argument. The -showroot argument can be used to output the root of the path rather than the common subtree component. In general, one should expect `pwd` to be equal to `sbrel -showroot``sbrel`.
usage: sbrel [ showroot] [completeDirPath]
Examples:
cd $BT1`sbrel` # change to directory under $BT1
cd $STO`sbrel` # change to object directory
cd $STS`sbrel` # change to sandbox directory
The sbscan utility is effectively a sandbox-aware combination of the find and egrep utilities. The default -top option will search from the root of each selected sandbox and backing tree, whereas the -rel option restricts the search to only the same relative subtree across the selected sandbox and backing trees. If the default -partial option is used, only the portion of the path below the root of search trees is output (note that the root will vary depending on whether -top or -rel was in effect). In contrast, the -full option outputs the entire path name of a file. The -suffix option can be used to specify a file name pattern; it defaults to '*.hc*', which is intended to select C/C++ source and header files.
A set of sandbox and backing tree roots can be specified using -all or combinations of -sb, -allbt, -bt1, -bt2, etc. If none are specified, the default behavior is to search only the local sandbox.
usage: sbscan [ top | rel] [ full | partial] { [ all] | [ allbt] |[ sb] [ bt1] [ bt2] [ bt3] [ bt4] } [ d dir] ... [ o file] [ suffix fileNamePattern] pattern ...
-top = start search from top of tree
-rel = start search from relative position within tree
-full = emit full path names
-partial = emit partial path below tree root
-all = search sandbox and all backing trees
-allbt = search all backing trees
-sb = search sandbox
-btN = search backing tree N in chain
-d dir = add an arbitrary tree to be searched
-o file = also output result into file
-suffix = file name search pattern
Default file name pattern is *.[hc]*
Default is start search from top of tree
Default is to emit partial path below tree
Default is to just search local sandbox
Examples:
# display all makefiles that reference CXXFLAGS
sbscan -suffix '*akefile' -all CXXFLAGS
# display all makefiles under the current working directory
# that reference CXXFLAGS
sbscan -suffix '*akefile' -all -rel CXXFLAGS
The sbsvnget utility is a sandbox-aware interface to Subversion that can make appropriate svn checkout and update invocations to retrieve selected source files. Normally, a Subversion checkout will retrieve an entire source tree, which defeats one of the benefits of using sandboxes. If normal svn checkout requests are done on subsets of the source tree, they appear as distinct, unrelated checkouts and commands like svn status, svn diff, svn commit, etc. would have to be invoked against the distinct checkout roots.
In contrast, sbsvnget enables retrieval of just the files of interest, while keeping the directory structure under the sandbox as a single Subversion checkout. The sbsvnget utility is aware of relative position within a sandbox tree and ensures that the directory hierarchy in the sandbox is in parallel with that of the repository.
The host and root path of the repository can be specified via environment variables (SVN_HOST and SVN_PATH), sandbox-specific attributes (sb_svnServer and sb_svnRoot, set by the user via setsbattr) or command-line arguments (-server and -path).
usage: sbsvnget [ server modeAndhostName] [ path pathToRepository] [-force] dirOrFileName ...
The -force option can be used to take over an existing directory tree. It is not normally used, but is useful when a sandbox has already had directories and some new files added prior to the first sbsvnget.
Most of the environment variables documented below are set by the workon command, but there are a handful reserved for use by an administrator or user.
The two key exceptions are the BT_ROOT_DIR and SB_ROOT_DIR variables, which are never set by any of the commands. They are reserved for use by an administrator or user to point the framework at alternate locations. The SB_MAKE_COMMAND variable is also not set by any script; if /usr/bin/make is not in use, this variable must be set appropriately for correct operation by sbmake.
/opt/backingTrees.
A user or administrator can set this environment variable to
override the default backing tree root directory on the local
system. All commands that reference this directory take a -btroot
argument which can also be used
to achieve the required effect.$HOME/sandboxes.
A user can set this environment variable to override the user's
default sandbox collection root. All commands that reference this
directory take a -sbroot
argument which can also be used
to achieve the required effect, but this is error-prone and
intended for use by scripts rather than humans.The following variables are automatically set by workon.
$SB_ROOT_DIR/$SB_NAME.NOTE: the SB_BUILD_ARCH and SB_TARGET_ARCH environment variables are often identical; however, they will always be different when utilizing support for a cross-compiler (e.g., compiling for Windows targets on an x64 Linux host). The feature can also be exploited to support incompatible compilation options, such as enabling various profiling options or compiling for a different addressing mode (e.g., 32-bit vs. 64-bit). In general, SB_BUILD_ARCH will be used to find utilities used during the build process by the local machine, like deployment utilities. It may also include specification of utilities such as the compiler, assembler, linker, etc., but these are often associated with the target architecture.
Various global configuration files are maintained in the $BT_ROOT_DIR/config directory. These specify the supported architectures, customization scripts for the build and target environment, and shell-specific rc files. When a new backing tree is created, symbolic links of the appropriate files are made from the $BT_ROOT_DIR into the backing tree's $BT/BuildEnv directory. This permits each backing tree to have custom configuration files, but they start out using common images. Consequently, normally any updates to the master versions will have immediate effect in all backing trees except those in which effort was made to create unique copies.
Note: backing trees are identified by the existence of their BuildEnv directory; the lsbt command uses the presence of a BuildEnv directory to find appropriate trees rooted under $BT_ROOT_DIR.
The list of all available target architectures is provided in the ALL_supportedArchitectures.txt file. The subset of locally supported architectures is provided in either `hostname s`_supportedArchitectures.txt or `buildArch -ba`_supportedArchitectures.txt. In some environments, the backing trees will be placed on a network file system and visible to machines with heterogeneous operating systems and processor architectures and not all platforms will be capable of compiling for non-native targets. The three distinct files thus indicate the extent of all platforms supported by the local development infrastructure, those available on a specific machine and those supported by any of the build machines with a given operating system/processor combination.
Sometimes it is useful to define a virtual custom architecture that is associated with the definition of compiler flags which are incompatible with normal defaults (e.g., --test-coverage). This can be done by the owner of the build system by editing the config/ALL_supportedArchitectures.txt file, but a developer can define their own variants by creating an $ST/BuildEnv directory and creating one of the three Architectures.txt files. For example, one might add a Linux.x86_64.coverage entry to correspond to a build with test coverage enabled and create a $ST/config/targetEnv.Linux.x86_64.coverage_sh.txt configuration file with all of the desired configuration definitions.
There are several optional configuration files consumed by the workon command that can be used to customize the environment. These files all end in “_sh.txt” to indicate they are shell scripts intended to be included rather than executed directly.
The preTreeEnv_sh.txt file is used by the workon command to setup any specialization specific to the backing tree chain. Often this file will not be present and will only be used when project-specific customization is required. The corresponding postTreeEnv_sh.txt file will be processed after all other configuration files have been consumed.
The buildEnv_`buildArch ba`_sh.txt file is used by the workon command to setup any specialization needed in the configuration environment for the build architecture. Content in this file would typically define settings related to the local build infrastructure. The similar targetEnv_`buildArch ta`_sh.txt file is used by the workon command to setup any specialization required by the configuration for the target architecture, such as compiler name, optimization flags, machine architecture, etc. Typically, this will involve specifying an alternate C/C++ compiler in the CC and CXX environment variables and appropriate values for the TARGET_ARCH environment variable (e.g., “-m64 -fPIC”). For cross-compilation, it will also usually involve specifying an alternate linker and library archive utility.
As a final step, a sbEnv_sh.txt will be processed if present. This file is often used for developer-specific customizations.
These files are consumed by the workon command and must be valid for processing by the /bin/sh interpreter. The defined order:
preTreeEnv_sh.txt
buildEnv_`buildArch -ba`_sh.txt
targetEnv_`buildArch -ta`_sh.txt
postTreeEnv_sh.txt
sbEnv_sh.txt
Users can use the command shell of their choice. After preparing the sandbox environment, the workon command passes a shell_rc.`basename ${SB_SHELL}` script to the spawned subshell. The scripts must be written in the respective language for the selected SHELL. Consequently, it is suggested that the complexity of these scripts should be minimized to avoid duplicated effort and generally used only to implement shell-specific functionality, like setting a command prompt. Customizing the appropriate buildEnv_*_sh.txt or targetEnv_*_sh.txt file is the preferred mechanism as only one set of modifications will be required.
The sandbox rc format appears as a collection of lines formatted as demonstrated below:
SB_${sbName}_${attribute}_ value
The ${sbName} portion corresponds to the sandbox's name and the ${attribute} portion is the name of the desired parameter. Note that there is always an underscore after the attribute name. The sandbox rc file is modified by the mksb command (and its variants resb and rmsb). It is a simple text file and can be easily edited by humans, though this will normally not be done. Instead, the mksb utility will be used to create the appropriate records. Other scripts use the getsbattr, setsbattr and delsbattr utilities to modify the sandbox rc file; this level of abstraction permits replacing the mechanism for storing sandbox attributes persistently without requiring modification of the sandbox-related commands.
The file format for the sandbox attributes supports an arbitrary number of parameters and can be extended at any time without affecting previously implemented applications. There are 3 mandatory attributes, sbname, sbroot and btpath:
The format of a sandbox rc file is illustrated below:
SB_test1_sbname_ test1
SB_test1_sbroot_ ~/sandboxes/test1
SB_test1_btpath_ /opt/backingTrees/tree1:/opt/backingTrees/tree2
SB_test1_defaultTargetArch_ Linux.x86_64
SB_test1_description_ Sample sandbox
mkbt -bt tree1
mksb -sb test1 -bt tree1 -desc “Sample sandbox”
workon -sb test1
resb -sb test1 -ta Windows.i686
To get started, one needs to know where the backing trees will be maintained. This will normally be set by the system administrator and, by default, this will be under /opt/backingTrees. If this is not the case, the BT_ROOT_DIR environment variable should be set to point at the appropriate directory. It is possible to pass a -btroot option to commands that need to be aware of the BT_ROOT_DIR, but this is extra effort and prone to error.
The SB_ROOT_DIR environment variable serves to specify the default directory under which a user's sandboxes should be created. If not set and the -sbroot command line option is not specified, the default of of $HOME/sandboxes will be used by the mksb command. Since every sandbox has its root maintained in the sandbox rc file, a sandbox can be stored anywhere.
The location of the user's sandbox rc file that stores the parameters associated with each sandbox is usually $HOME/.sandboxrc. It is possible to specify an alternative configuration file using the -rc command line option, but it would be rare to find a compelling reason to use an alternate name or file.
A user can specify the shell they wish to use in workon sessions by setting the SB_NAME environment variable to the full path of the shell (e.g., /bin/csh). If not set, the shell in use at the time of the workon invocation will be used. A typical scenario is one in which the system administrator has mandated the use of /bin/sh for login shells but a developer prefers to use /bin/csh for development work.
The sbsvnget utility can use the environment variable SVN_HOST and SVN_PATH to access a Subversion repository. If only a single repository is in use locally, it can be extremely convenient to set these variables.
Typically, an administrator sets up an automated process that uses the mkbt command to create a new backing tree, extract the most current source code image from a repository and do a complete build. If successful, a symbolic link with an appropriate name (e.g., current) will be created to point at the new backing tree. Developers can use that symbolic name as a backing tree and have their sandboxes automatically backed by the most recent successful build. In a similar fashion, an image of production releases is maintained, making it easy for developers to immediately compile against any production release in use by customers.
Sandboxes are created using the mksb command. One needs to know the name of the sandbox to be created and the backing tree(s) with which it should be associated. One can get a list of the available backing trees by issuing the lsbt command. The name of the sandbox is entirely up to the developer, but must be something representable as a directory name. It should not use white space even if the local filesystem is capable of storing such names.
The mksb command has a simple interactive mode (requested via the -i flag) that will prompt for required parameters:
$ mksb -i
/opt/backingTrees/bin/mksb: sandbox name was not specified.
Enter name of sandbox: sbtest
/opt/backingTrees/bin/mksb: no backing trees specified.
Available backing trees: current test1 release
Enter backing tree name or path: current
Developers usually quickly become proficient with the mksb command and will just enter the needed arguments on the command line. A description can be added to annotate the intended usage of the sandbox if the name itself was not sufficiently informative.
mksb -sb sbtest -bt current -desc 'Feature 53126'
Once a sandbox is created, a developer makes use of it via a workon command.
A developer usually issues a workon command to begin a development session:
workon -sb sbtest
When a development session is complete, the shell is closed (usually via control-D or an explicit exit).
It is possible to use a workon command to invoke a command in the context of a sandbox. For example:
workon -sb sbScan -suffix makefile CXXFLAGS
This usage is most commonly found in scripts.
Each sandbox has a default target architecture, which can be altered with the resb command. It is also possible to set a different target architecture for the duration of the current workon session using the -ta option. This can be useful when a developer wants to use the same sandbox and compile for multiple machine architectures.