sandboxrc(5) UNIX Programmer's Manual sandboxrc(5)
NAME
sandboxrc - description of internals of sandbox rc files
SYNOPSIS
/sandbox/rc_files/local
/sandbox/rc_files/local.tmpl
/sandbox/rc_files/shared
/sandbox/rc_files/shared.tmpl
/sandbox/rc_files/sets
${HOME}/.sandboxrc
DESCRIPTION
There are two types of rc files described in this document;
the rc files which are part of a sandbox and the rc files
which are associated with a user. The rc files associated
with each sandbox are: /sandbox/rc_files/local,
/sandbox/rc_files/local.tmpl, /sandbox/rc_files/shared,
/sandbox/rc_files/shared.tmpl, and /sandbox/rc_files/sets.
Each sandbox will have these five rc files and may have
additional versions of /sandbox/rc_files/local if the user
wants to create multiple local environments for the sandbox.
The rc file ${HOME}/.sandboxrc is associated with the user.
Normally this is the only rc file associated with the user,
but the user can make multiple versions of this file.
Syntax:
The local, shared, and template rc files associated with the
sandboxes share a common syntax. Each line is of one of two
forms:
<target> <value>*
or
<key word>* <target> [<value>*]
An example of the first case is:
rcs_owner devrcs
of the second case:
replace source_base ${sandbox_base}/src
If there is no key word, the value of the target is checked.
If it is already set, it is not changed. If it is not set,
it is given the value of value. A target is always a single
word.
A value can be explicit, a string, or a variable. A string
is surrounded by quotes and can contain spaces and
Printed 1/23/91 10/3/90 1
sandboxrc(5) UNIX Programmer's Manual sandboxrc(5)
variables. A variable starts with a '$' and is expanded; if
the variable is not set, the value will be left empty.
Legal key words include:
include
used to include another file in the current rc file.
This key word takes a target but no value.
setenv
makes the target an environment variable set to value.
on machine
indicates the entry is to be used only when the current
system matches the machine type.
replace
puts the current value into target even if target is
already set. Most lines in the shared and local sand-
box rc files contain this key word.
A line can contain more than one key word, such as:
replace on mips setenv TARGET_MACHINE PMAX
RC File: /sandbox/rc_files/local
The sandbox rc file local is used to customize the behavior
of a particular sandbox. Any variable changed in this file
will have affect locally but will not be propagated to any
other sandbox.
The file is located under the directory
/sandbox-base/sandbox-name/rc_files
and is found in each build and each sandbox.
A generic local rc file has very little information in it as
it is primarily for the developer's use. An example would
be:
include ./shared
replace setenv OBJECTDIR ../obj/${target_machine}
replace setenv LPATH ${LPATH}
replace setenv INCDIRS ${INCDIRS}
replace setenv LIBDIRS ${LIBDIRS}
replace setenv SHLIBDIRS ${SHLIBDIRS}
The first line includes the local shared rc file, the next
overrides any existing value for the location of the object
directory. The remainder of the rc file simply sets the
environment variables to their current values. They are
placed in the file so users will have easy access to the
Printed 1/23/91 10/3/90 2
sandboxrc(5) UNIX Programmer's Manual sandboxrc(5)
most commonly modified variables. and include LPATH, INC-
DIRS, LIBDIRS, and SHLIBDIRS.
The variable LPATH represents the search path executables
use when looking for other executables, for example, where
to look for cpp. INCDIRS holds the -I list to pass to the
compiler for searching for include files. Normally this
search is done in each export tree. LIBDIRS holds the -L
list to pass to the compiler for searching for libraries,
also normally in each export tree. SHLIBDIRS represents the
search path for the shared libraries.
RC File: /sandbox/rc_files/local.tmpl
The local.tmpl rc file is identical to the local rc file at
this time. This is because there is currently no transla-
tion needed between the two files. Because that may not
always be the case, the local.tmpl file is exists.
RC File: /sandbox/rc_files/shared
A Build's shared File
Each build has a version of the shared rc file which is much
larger than a sandbox's. Much of the information in it is
specific to a build and is normally never changed.
The build's shared rc file is the only sandbox rc file which
does not normally include other sandbox rc files. This is
because builds, themselves, are not backed by anything. It
is not unusual for information in the build's shared rc file
to be replaced or added to by subsequent rc files.
The following is an example of the contents of a build's
shared file taken from latest.
replace on mips setenv MACHINE mips
replace on mips setenv TARGET_MACHINE PMAX
replace on mips setenv target_machine pmax
replace on mmax setenv MACHINE mmax
replace on mmax setenv TARGET_MACHINE MMAX
replace on mmax setenv target_machine mmax
replace on i386 setenv MACHINE i386
replace on i386 setenv TARGET_MACHINE AT386
replace on i386 setenv target_machine at386
sandbox_base /project/osc/build/latest
source_base ${sandbox_base}/src
tools_base ${sandbox_base}/tools/${target_machine}
object_base ${sandbox_base}/obj/${target_machine}
export_base ${sandbox_base}/export/${target_machine}
rcs_cover ${tools_base}/lib/rcsauth
rcs_host skippy
rcs_base /u3/dev/rcs
Printed 1/23/91 10/3/90 3
sandboxrc(5) UNIX Programmer's Manual sandboxrc(5)
rcs_owner devrcs
check_out_config "LATEST;include ${sandbox_base}/CONFIG"
build_makeflags -cF
on mips setenv MACHO_GCC_EXEC_PREFIX "${tools_base}/macho/"
on mips setenv COFF_GCC_EXEC_PREFIX "${tools_base}/gcc/"
on mmax setenv MACHO_GCC_EXEC_PREFIX "${tools_base}/macho/"
on mmax setenv COFF_GCC_EXEC_PREFIX "${tools_base}/gcc/"
on i386 setenv OBJECT_FORMAT A_OUT
on i386 setenv ARCHIVE_FORMAT ASCARCH
on i386 setenv A_OUT_GCC_EXEC_PREFIX "${tools_base}/gcc/"
replace setenv SITE OSF
replace setenv OWNER bin
replace setenv GROUP bin
release_cover /bin/echo
release_owner root
release_base ${sandbox_base}/release/${target_machine}
release_lock ${sandbox_base}/release/${target_machine}/release_lock
stage latest latest norm
stage default default norm
replace setenv MAKEFILEPATH MAKETOP}/usr/lib/makefiles
replace setenv SOURCEDIR ""
replace setenv BACKED_SOURCEDIR ${source_base}
replace setenv EXPORTBASE ${export_base}
replace setenv MIGCOM ${tools_base}/lib/migcom
replace setenv LEXER ${source_base}/usr/ccs/lib/lex/ncform
replace setenv YACCPAR ${source_base}/usr/ccs/lib/yaccpar
replace setenv INCDIRS -I${export_base}/usr/include
replace setenv LIBDIRS -L${export_base}/usr/ccs/lib
replace setenv SHLIBDIRS -L${export_base}/usr/shlib
replace setenv LPATH ""
The first nine lines set the type of machine the user is
running on. There are three, slightly different forms of
the same information for each machine primarily because of
historic reasons. The next five lines set the various sand-
box directories, followed by four lines which describe how
to access the source control. The line following that,
check_out_config, establishes the places to look for check-
out revision information.
There is line to set default make flags, and then seven
lines for machine specific compiler information. The next
nine lines provide information for the installation process,
the site specific designation, the default owner and group,
and six lines which the program release uses.
These lines are followed by seven environment variables
which provide location information. MAKEFILEPATH gives the
location of the common makefiles, SOURCEDIR,
BACKED_SOURCEDIR, and EXPORTBASE provide locations within
the backing tree and sandbox. MIGCOM gives the location of
migcom which is the executable mig invokes. LEXER provides
Printed 1/23/91 10/3/90 4
sandboxrc(5) UNIX Programmer's Manual sandboxrc(5)
the location of the form file lex needs, and YACCPAR gives
the location of yaccpar which is called by yacc.
The final four lines provide path information: INCDIRS tells
the compiler where to search for include files, LIBDIRS
tells the compiler where to search for libraries, and SHLIB-
DIRS tells the compiler where to search when building for
shared libraries, The last path, LPATH, is not used any
more.
A Sandbox's shared File
The sandbox's version of the shared rc file is an abbrevi-
ated version of the build's. The only original line is the
addition of include ../link/rc_files/shared which includes
the backing tree's shared rc file through the sandbox's link
directory. Every sandbox contains this include line until a
build is reached, thus the local rc file contains all the
information from all its parents regardless of how many lev-
els it is backed by.
The following is an example of the contents of a sandbox's
shared rc file:
include ../link/rc_files/shared
replace sandbox_base /path/to/sandbox
replace source_base ${sandbox_base}/src
replace object_base ${sandbox_base}/obj/${target_machine}
replace export_base ${sandbox_base}/export/${target_machine}
replace setenv SOURCEBASE ${source_base}
replace setenv SOURCEDIR ${BACKED_SOURCEDIR}
replace setenv BACKED_SOURCEDIR ${source_base}:${SOURCEDIR}
replace setenv LEXER ${LEXER}
replace setenv YACCPAR ${YACCPAR}
replace setenv EXPORTBASE ${export_base}
replace setenv INCDIRS "-I${export_base}/usr/include ${INCDIRS}"
replace setenv LIBDIRS "-L${export_base}/usr/ccs/lib ${LIBDIRS}"
replace setenv LPATH ""
With the exception of the include line, all the entries are
found in the build's shared rc file and are overwritten by
the sandbox's using the key word replace. The sandbox_base
line will contain the actual path and name of the sandbox.
INCDIRS and LIBDIRS are redefined by adding a new path to
the beginning of their existing values. This is because the
search path for header files and libraries needs to begin
locally but continue through the backing trees if they are
not found.
RC File: /sandbox/rc_files/shared.tmpl
Printed 1/23/91 10/3/90 5
sandboxrc(5) UNIX Programmer's Manual sandboxrc(5)
The shared.tmpl rc file is the template from which the
shared rc file is created. It is identical to the shared rc
file except for the line defining sandbox_base. The line in
the template file is:
replace sandbox_base
When a template file is converted to an actual shared rc
file, the line gets changed to something like:
replace sandbox_base /project/osc/sandboxes/suzieq
The template is also copied to the new sandbox so it can be
used as the template for any child sandboxes to the new
sandbox.
Since the two files are identical except for this line, no
example is given of a template file.
RC File: /sandbox/rc_files/sets
Sets are the logical working areas inside a sandbox. A set
can contain any number of files which will be listed in the
files under src: .BCSset-user_setname. A default set is
created by mksb at the time the sandbox is created and usu-
ally has the same name as the sandbox. The sets rc file
contains the names of all sets created in the sandbox and
their default set directories.
When a new set is created by workon, it is added to the
list. mksb also puts the name of the default set into this
file with the keyword default.
The syntax for this file is:
default setname
set setname setdir
set setname setdir
The first line defines the default set, the set in this
sandbox to use if the environment variable BCSSET is not
set. Each line after that gives the name of the set and its
set directory. The set directory always starts with a
period, ".", so if there is no set directory, the line will
look something like:
set motif .
There is a line in this format for each set which has been
created in the sandbox. When the user does a workon to the
setname, workon cd's to the setdir under the sandbox's
source directory.
RC File: ${HOME}/.sandboxrc
Printed 1/23/91 10/3/90 6
sandboxrc(5) UNIX Programmer's Manual sandboxrc(5)
Each user has at least one rc file for sandbox information
which, if it doesn't exist, will be created by mksb. The
default location and name of the file is ${HOME}/.sandboxrc
but the -rc filename option allows users to have more than
one of these files.
This file contains information needed by all the sandbox
tools including: mksb, resb, workon, bcs, and bsubmit. It
contains the name of the default sandbox, the sandbox to use
when the environment variable SANDBOX is not set, and it
contains the mapping between the sandboxes and their base
directories. The mappings between sandboxes and bases is
done using wildcards. It also contains a list of the sand-
boxes and fields for creating and populating new sandboxes
which only mksb uses.
In the example that follows, the user has given musical
names to each of her sandboxes. The default sandbox is sym-
phony. Concerto, another sandbox, has a base directory of
/project/osc/sandboxes/shared while the sandbox song has the
base directory /users/suzieq. Any sandbox whose name ends
in motif has a base directory of
/project/osc/sandboxes/suzieq/motif. Finally, any sandbox
which has not yet been designated and which didn't match a
wild card entry has the base directory
/project/osc/sandboxes/suzieq. In this example, symphony,
serenade, and aria fall into this category. Concerto-motif
and opera-motif match *motif while the other two sandboxes
are designated specifically.
The remainder of the file contain the names of the sandboxes
and the mksb rules. Comments start with a '#' character.
# the default sandbox; if environment variable SANDBOX is not set, use
# this sandbox
default symphony
# base directory for each sandbox; use wild cards to expand sandbox
# names
base concerto /project/osc/sandboxes/shared
base song /users/suzieq
base *motif /project/osc/sandboxes/suzieq/motif
base * /project/osc/sandboxes/suzieq
# list of sandboxes and optional sandbox rc file; this file defaults to
# /base/sandbox/rc_files/local
# This field can be absolute or it is taken to be relative from
# /base/sandbox
sb serenade
sb symphony rc_file/debug
sb concerto
sb concerto-motif
sb song /tmp/sb_rcfile
Printed 1/23/91 10/3/90 7
sandboxrc(5) UNIX Programmer's Manual sandboxrc(5)
sb opera-motif
sb aria
# specific input for the command "mksb"
# the default directory to build sandboxes in
mksb default_sandbox_base /project/osc/sandboxes/suzieq
# the machine(s) to build machine dependent directories for
mksb default_machines pmax:mmax
# should tools be copied into place, linked, or left backed?
# values can be 'c', 'l', or 'b'
mksb copy_link_tools c
# should obj directories be copied into place, linked or left backed?
# if linked or copied, list the directories, separated by
# colons, which should be linked or copied. '/' can be used for all.
# NOTE: machine directories must be included
mksb copy_link_objs l /pmax/usr/include:/mmax/usr/lib/libsys
# should sources be copied into place, linked, or left backed?
# if linked or copied, list the directories, separated by
# colons, which should be linked or copied. '/' can be used for all.
# NOTE: machine directories must be included
mksb copy_link_sources b /
In the mksb rules, the default_sandbox_base gives the same
information as the -dir option on the mksb command line and
the default_machines the same as information as the -m
option.
This file can be modified using the -c option in mksb or by
simply editing it.
RELATED INFORMATION
latest(7), mksb(1), sandbox(7), workon(1).
Printed 1/23/91 10/3/90 8