usage: Print metavariables in SHOUTY letters.

[sw-tools] / sw.1

.\" -*-nroff-*-
.\"
.\" $Id$
.\"
.\" Manual page for `sw'
.\"
.\" (c) 1999 EBI
.\"
.
.\"----- Licensing notice ---------------------------------------------------
.\"
.\" This file is part of sw-tools.
.\"
.\" sw-tools is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" (at your option) any later version.
.\" 
.\" sw-tools is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\" 
.\" You should have received a copy of the GNU General Public License
.\" along with sw-tools; if not, write to the Free Software Foundation,
.\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
.
.\"----- Style hacking ------------------------------------------------------
.
.de VS \" Start a sort-of verbatim block
.sp 1
.in +5n
.nf
.ft B
..
.de VE \" Stop a sort-of verbatim block
.ft R
.fi
.in -5n
.sp 1
..
.de hP \" Start an indented paragraph with a bold right-aligned label
.IP
\fB\h'-\w'\\$1\ 'u'\\$1\ \fP\c
..
.
.ie \n(.g \{\
. fam P
. ds mw \fR[\f(BImdw\fR]
.\}
.el .ds mw \fR[\fBmdw\fR]
.ie t .ds o \(bu
.el .ds o o
.ds sw \fBsw\fP
.
.\"----- Main manual text ---------------------------------------------------
.
.TH sw 1 "25 May 1999" sw-tools
.PD 1
.
.\"--------------------------------------------------------------------------
.
.SH "NAME"
.
sw \- tool for convenient software installation
.
.\"--------------------------------------------------------------------------
.
.SH "SYNOPSIS"
.
.nf
\fBsw \-\-help
\fBsw \-\-help-full
\fBsw \-\-version
\fBsw \-\-archname
\fBsw \-\-remote \fIcommand

\fBsw all\-arch
\fBsw arch
\fBsw commit
\fBsw \fR[\fB\-fbip\fR] [\fB\-a \fIarch\fB,\fIarch\fR...] [\fB\-o \fIstyle\fR] \fBconfigure \fR[\fIconfigure-arg\fR...]
\fBsw host \fIarch
\fBsw \fR[\fB\-f\fR] [\fB\-a \fIarch\fB,\fIarch\fR...] \fBlinktree
\fBsw listarch
\fBsw \fR[\fB\-fbip\fR] [\fB\-a \fIarch\fB,\fIarch\fR...] [\fB\-o \fIstyle\fR] \fBmake \fR[\fImake-arg\fR...]
\fBsw only\-arch \fIarch \fR[\fIarch\fR...]
\fBsw reset
\fBsw rsh \fIhost\fR|\fIarch \fR[\fIcommand \fR[\fIargument\fR...]]
\fBsw \fR[\fB\-fbip\fR] [\fB\-a \fIarch\fB,\fIarch\fR...] [\fB\-o \fIstyle\fR] \fBrun \fIcommand \fR[\fIargument\fR...]
\fBsw setup \fIpackage version \fR[\fImaintainer\fR]
\fBsw \fR[\fB\-f\fR] [\fB\-a \fIarch\fB,\fIarch\fR...] \fBsnaplink \fIfile \fR[\fIfile\fR...]
\fBsw status
.ft R
.fi
.
.\"--------------------------------------------------------------------------
.
.SH "INTRODUCTION"
.
The \*(sw tool attempts to take a lot of the work out of building and
installing source packages across multiple architectures.  This section
will describe how to use \*(sw's features to best advantage in a number
of common situations.
.PP
To keep things concrete, I'll describe how things are done at the EBI,
although there's nothing EBI-specific about the \*(sw program itself.
For details about how we handle software at EBI, see the
.B Local quirks
section below.
.PP
By the way, this is quite a large manual.  I recommend that you print a
copy onto paper and peruse it in a leisurely fashion, rather than
squinting at a monitor.
.
.\"--------------------------------------------------------------------------
.
.SH "SUMMARY OF BUILDING PACKAGES"
.
First, the
.B Autoconf
case:
.VS
.BI "sw setup " "package version"
.B "sw only \c"
.IR "arch " [ arch ...]
.ft B
sw configure
sw make
sw \-i make install
sw commit
.VE
Secondly, the
.RB non- Autoconf
case:
.VS
.BI "sw setup " "package version"
.B "sw only \c"
.IR "arch " [ arch ...]
.B "sw linktree"
.BI "sw snaplink \c"
.IR "file " [ file ...]
.I [edit the appropriate files]
.ft B
sw make
sw \-i make install
sw commit
.VE
.
.\"--------------------------------------------------------------------------
.
.SH "8 STEPS TO INSTALLING A PACKAGE"
.
The following steps will guide you through your first (and maybe second)
package installations.  In the description, I'll use
.RI ` package '
to refer to the package's name, and
.RI ` version '
to refer to its version number.
.PP
Not all the important features and options are described in this part of
the manual.  View it more as a taster for the sorts of things \*(sw can
do, and a suggestion
.SS "1.  Download the source distribution"
Download the package's source distribution.  This will normally be in an
archive called something like
.IB package - version .tar.gz\c
\&.  At EBI, we put source archive files in
.BR /sw/common/tr .
.SS "2.  Unpack the source tree"
Unpack the source tree into the standard source directory.  Each source
tree should have its own directory.  Most well-packaged source
distributions unpack themselves into a neat directory, but less
fastidious programmers make archives which scatter files all over the
current directory.
.PP
At EBI, we put the source trees in
.BR /sw/common/src ,
so unpacking a well-formed source distribution looks like:
.VS
cd /sw/common/src
.BI "gzip \-dc ../tr/" package \- version ".tar.gz | tar xfv \-"
.VE
Ill-formed source distributions involve making the directory for the
package first, changing into it, and then unpacking into the current
directory:
.VS
cd /sw/common/src
.BI "mkdir " package \- version
.BI "cd " package \- version
.BI "gzip \-dc ../../tr/" package - version ".tar.gz | tar xfv \-"
.VE
When you've finished unpacking, make sure that your current directory is
the top level directory of the source tree you unpacked.
.SS "3.  Tell \\*(sw what you're up to"
Now you need to tell \*(sw what you're working on.  It will keep track of
this and other bits of information in a little file and refer to it
every now and then.  It will also whinge at you and refuse to cooperate
if it can't find its little file, so it's as well to oblige.
.PP
To tell \*(sw to create this little file and initialize it with sensible
values, you just need to say
.VS
.BI "sw setup " "package version"
.VE
What could be easier?
.SS "4.  Restrict the build to particular architectures"
Some packages don't work on all architectures, either because the author
wasn't sufficiently good at writing portable software, or because the
program's doing inherently nonportable things.
.PP
If that's the case, then you need to tell \*(sw to only build on the
architectures that really work.  Do this with the
.RB ` "sw only" '
command.  For example, if your package only works on Linux and Solaris,
say:
.VS
sw only i386-linux sparc-solaris
.VE
You can get a list of the architecture names that \*(sw understands by
typing
.VS
sw listarch
.VE
With a little bit of luck, these names ought to be self-explanatory.
.PP
If your package is properly portable and works everywhere then you don't
need to do anything for this step.  Skip on to the next one.
.SS "5.  Configure the package"
Now it gets complicated.  If the package you're building uses
.B Autoconf
to configure itself for its current environment then you're in luck.
You can tell an
.B Autoconf
package because there's a script called
.B configure
in the top source directory, and a file called
.BR Makefile.in .
If it
.I does
use
.B Autoconf
then run
.VS
sw configure
.VE
to configure the package on all the platforms it's meant to be built
for.  When you've done that, move onto the next step.
.PP
If the package
.I doesn't
use
.B Autoconf
then all is not lost (although it may be worthwhile complaining at the
package's author or maintainers).  You need to make a collection of
.IR "link trees" ,
one for each architecture.  These link trees are little replicas of the
main source tree but with symbolic links instead of the real source
files.  To make the link trees, run
.VS
sw linktree
.VE
Now, that's not actually quite what you wanted.  It's made a link for
.I every
file in the source tree.  Unfortunately, there are some files you'll
(probably) have to modify for each architecture in order to configure
the package to build properly.  You can turn links in the link trees
into real independently editable files by
.I snapping
the links.  Say for example that
.B Makefile
and
.B config.h
need to be modified for each architecture.  Running the command
.VS
sw snaplink Makefile config.h
.VE
is sufficient to do the right thing.
.PP
Now you must edit the snapped files to configure the package.  Make sure
that the install directories are correctly set.  At EBI, all the
software should be configured so that architecture neutral files end up
under
.B /sw/common
and architecture-specific files end up under
.BI /sw/common/arch/ arch\c
\&.
.SS "6.  Build the package"
Now you've laid the groundwork, everything ought to be easy.  Making the
program ought to involve simply typing
.VS
sw make
.VE
and waiting for a while.  If you had the
.B curses
library available when \*(sw was built, then your terminal will split
itself into little independently scrolling windows showing you the
progress for each architecture.  If you're not privileged enough to have
.B curses
then you get the output appropriately tagged with architecture names,
which is unfortunately fairly hard to read.
.SS "7.  Install the package"
Most source packages (and almost certainly all
.B Autoconf
ones) have a
.B make
target
.RB ` install '
which installs the program correctly.  You can run this from \*(sw by
saying
.VS
sw \-i make install
.VE
The little
.RB ` \-i '
option there tells \*(sw that this is the
.IR "install step" .
When an architecture completes this step correctly, it's marked as being
properly installed, and \*(sw doesn't bother thinking about it again.
.PP
If you
.I don't
have an
.RB ` install '
makefile target, then you have to install things manually.  That's not
much fun, so moan at the package's author.  When you've finished
fiddling with installation, run
.VS
sw -i run true
.VE
just to tell \*(sw that you've installed everything OK.  (This is a bit
of a kludge.)
.SS "8.  Update the index"
Now that everything's built and installed, there's just one more command
to type:
.VS
sw commit
.VE
This makes \*(sw update its main index of installed packages, telling it
which architectures packages are installed on, and who did it.
.
.\"--------------------------------------------------------------------------
.
.SH "REFERENCE INTRODUCTION"
.
That was a gentle introduction.  This section contains the complete
reference to
.BR sw :
far more detail that you probably want.  If that's really the case, try
running
.VS
sw \-\-help\-full
.VE
to read the available help text.  There's quite a lot of it, and it
ought to keep you occupied for a while.
.PP
The basic \*(sw command line looks a bit like:
.sp 1
.RS 5 
.B sw 
.RI [ options ]
.RI [ command
.RI [ argument ...]]
.RE
.sp 1
If you just say
.VS
sw
.VE
at the shell prompt, \*(sw gives you an extremely terse usage summary
and quits.  You have to tell it to do
.IR something .
Most of the time you do this by giving \*(sw a
.IR command ,
like
.RB ` setup '
or
.RB ` make '
so that it knows what to do.  There are some strange command line
options which cause \*(sw to do more exotic things, though.
.
.\"--------------------------------------------------------------------------
.
.SH "IMPLEMENTATION ODDITIES"
.
The \*(sw program that users use is really a small architecture-neutral
shell script, which works out the current architecture and executes the
appropriate architecture-specific main program.  It's done this way so
that \*(sw knows that it can use the shell script to start itself up on
a remote host with a different architecture, something which it does
quite a lot.  The only feature provided by the front-end shell script is
the
.B \-\-archname
command line option, which shouldn't be used by anyone except \*(sw's build procedure anyway.
.
.\"--------------------------------------------------------------------------
.
.SH "COMMAND LINE OPTION REFERENCE"
.
Any \*(sw command line options can be put in the
.B SW
environment variable.  The \*(sw program will read space-separated
options from this variable before it reads the command line itself.
.PP
The \*(sw program usually understands two different names for each
option: a traditional Unix single-character name, and a long GNU-style
name.  The short options behave in the normal Unix way: you can join
them together into single words with a
.RB ` \- '
at the front, for example.  The long names are always preceded by a
double dash.  You can abbreviate long names as much as you like, as long
as the resulting abbreviation is unambiguous.  In the descriptions
below, both the short and long names of the options are shown, but for
reasons of brevity required arguments are only shown for the long form.
.PP
There are conceptually two types of \*(sw command line options: those
which, usually for reasons of consistency with other programs, cause
\*(sw to do something immediately; and those which store some settings
for particular commands.  The latter type are generally more useful.
It's worth bearing in mind, though, that the options are only used by a
few commands.  The command reference describes exactly which commands
use which options.
.PP
The complete list of command line options understood by the current
version of \*(sw is as follows:
.TP
.B "\-h, \-\-help"
Writes a fairly brief summary of \*(sw's command line options and a usage line for each of \*(sw's commands to standard output, and exits successfully.
.TP
.B "\-H, \-\-help\-full"
Writes a summary of \*(sw's command line options and a full paragraph of description for each of \*(sw's commands to standard output, and exits successfully.  There's a lot of
text generated by this option.  I recommend you pipe it through a pager
so that you can actually read it.
.TP
.B "\-v, \-\-version"
Writes \*(sw's version number to standard output and exits successfully.  This is handy
when trying to decide whether your version of \*(sw has a particular feature, for example.
.TP
.B "\-u, \-\-usage"
Writes a usage message so terse as to be nearly useless to standard
output and exits successfully.  This is different from just running
.RB ` sw '
because although both print the same useless message, running \*(sw without any arguments is considered an error, so the message is sent to
standard error and \*(sw will exit unsuccessfully.
.TP
.BI "\-a, \-\-arch " arch , arch\fR...
For commands which affect multiple architectures: only affect the
architectures specified.  The architecture names may be separated by
commas, spaces or both, although clearly commas are most convenient on
the command line.  Architecture names may be abbreviated as long as the
abbreviation is not ambiguous.
.IP
This option overrides any other decisions that \*(sw might make about which architectures to process based on the
.B only\-arch
list and the list of correctly built architectures for the current
package.
.TP
.B "\-f, \-\-force"
For commands which affect multiple architectures: affect even
architectures that have been successfully built.  This has no effect if
there's a
.RB ` \-a '
option in force.
.TP
.B "\-i, \-\-install"
For build commands: this is the final install step, so label architectures
which successfully complete it as having been completely built.  It's
normal to specify this option on the
.RB ` "make install" '
build command.
.TP
.BI "\-o, \-\-output " style
For build commands: select a style for the build output to be displayed
in.  See the section
.B "Build commands"
for more details on output styles.
.TP
.B "\-b, \-\-beep"
For build commands: make a beep noise when the build finishes.  This
provides a handy reminder if you're getting on with something else while
waiting for a long build.  Use
.RB ` +b '
or
.RB ` \-\-no\-beep '
to turn this option off.  This option is disabled by default, although
may be enabled in the
.B SW
environment variable.
.TP
.B "\-p, \-\-percent"
For build commands: enable translation of
.RB ` % '-escape
sequences in command strings.  These are described in more detail
in the section
.B "`%'-escape sequences"
below.  Use
.RB ` +p '
or
.RB ` --no-percent '
to turn the option off.  This option is enabled by default, although may
be disabled in the
.B SW
environment variable.
.PP
The remaining options aren't really intended for users.  They're helpful
for \*(sw's own purposes, though, and described here for completeness' sake.  They
don't have standard Unix short name equivalents, because they're not
usually useful for users.
.TP
.B "\-\-archname"
Writes the \*(sw architecture name of the current host to standard output.  This is used
by \*(sw's configuration script to determine the current architecture name.  This
option is actually handled by a small shell script rather than by being
passed on to the main program.  You shouldn't use this option yourself:
use the
.RB ` arch '
command instead.  Because this option is handled by the shell script,
and the script isn't very clever, you can't abbreviate
.B \-\-archname
on the command line, and it doesn't conflict with the similarly named
but completely different
.B \-\-arch
option, which you can still abbreviate all the way down to just
.RB ` \-\-a '.
.TP
.BI "\-\-me " name
Sets \*(sw's idea of its program name to
.IR name .
This is intended for use by \*(sw's front-end shell script, but isn't
actually needed at the moment.  I can't see why you'd want to play with
this option, but it shouldn't do any harm.
.TP
.BI "\-\-remote " remote-command
Used by \*(sw when running commands on remote hosts.  Don't use this yourself: it puts \*(sw into a very unfriendly mode and requires that you communicate with it
using a bizarre binary packet protocol.  If you really must know more
about this, see the source code: it's quite well documented, really.
.
.\"--------------------------------------------------------------------------
.
.SH "TERMINOLOGY"
.
The descriptions below make use of some technical terms:
.TP
.B "architecture restriction"
A state created by the
.B only\-arch
command, restricting the
.I "default build architectures"
to those listed as arguments to the command.  An architecture
restriction may be cleared by
.B all\-arch
command.
.TP
.B "build architectures"
The architectures which a
.I "build command"
will process.  If the
.RB ` \-a '
option is specified on the command line, then its argument specifies the
build architectures for this command; otherwise, the
.I "default build architectures"
are used.
.TP
.B "build command"
A command which executes a process on multiple hosts simultaneously and
reports the results.  The processes executed usually perform some part
of the building of a package.  Currently, the build commands are
.B run
and its derivatives
.B configure
and
.BR make .
.TP
.B "default build architectures"
The architectures which, in the absence of a
.RB ` \-a '
command line option, are affected by a
.IR "build command" .
To determine the default build architectures, \*(sw reads the list of all architectures from the
.B archtab
file, and filters it: if the
.RB ` \-f '
command line option is
.I not
specified, then architectures marked as
.I "successfully built"
are removed from the list; if there is an
.I "architecture restriction"
in force, then the list is further filtered according to the
restriction.
.TP
.B "successfully built"
A package is considered to be successfully built on a given architecture
if a build command given the
.RB ` \-i '
command-line option succeeds on a host of that architecture.  The list
of successfully built architectures can be cleared by the
.B reset
command.  The
.RB ` \-f '
option causes \*(sw to ignore whether architectures have been successfully built when
determining the
.IR "default build architectures" .
.
.\"--------------------------------------------------------------------------
.
.SH "COMMAND REFERENCE"
.
This section describes all of the available \*(sw commands, in alphabetical order.
.
.SS all\-arch
Clears an architecture restriction set by
.RB ` only\-arch '.
Subsequent build commands will run across all known architectures not
yet successfully built, unless overridden by the
.RB ` \-a '
command-line option, or a later
.RB ` only\-arch '
command.
.
.SS arch
Writes the name of the local host's architecture to standard output.
The architecture name is built into \*(sw at compile time.
.SS commit
Writes information from the
.B .sw\-info
file to the installed packages index file
.IB prefix /sw-index\fR.
.PP
\*(sw performs some checks before committing information to the index
file.  Firstly, all the expected architectures must be successfully
built.  Secondly, the script
.IB prefix /share/sw-precommit\fR
is run, if it exists.  This script must exit successfully if the commit
is to proceed.  The script can be configured to enforce local policy
requirements on installed software.
.PP
The
.B sw-precommit
script is passed a single argument, which is the package name to be
committed.  Other useful information is passed in the environment:
.TP
.B SW_PACKAGE
The package name (again).
.TP
.B SW_VERSION
The package version number.
.TP
.B SW_MAINTAINER
The package's maintainer.
.TP
.B SW_DATE
The last date on which the package was modified.
.TP
.B SW_ARCHLIST
The list of architectures on which the package has been built (separated
by spaces or commas).
.TP
.B SW_PREFIX
The installation prefix with which \*(sw was configured.
.PP
The script should report any errors it finds to its standard error
stream.
.
.SS configure \fR[\fIconfigure-arg\fR...]
Equivalent to the command
.VS
.BI "run ../configure \-\-prefix=" prefix " " configure-arg\fR...
.VE
where
.I prefix
is the installation prefix with which \*(sw itself was configured.  If you want to specify a different prefix, pass
your own
.B \-\-prefix
argument.
.PP
It is expected that administrators will set up a file
.IB prefix /share/config.site
which sets up other Autoconf parameters once the prefix has been
chosen.  See the Autoconf manual for more information.
.
.SS host \fIarch\fR
Writes to standard output the name of a host with requested architecture
.IR arch .
The hostname is read from the
.B archtab
file.
.
.SS linktree
Builds symbolic link trees.  For each of the build architectures, a
directory with the architecture's name is created containing a symbolic
link corresponding to each file in the main source tree.  Thus, a `make'
in the link tree will fetch the source files correctly, but place the
objects in the link tree rather than the main source tree, so that
object files from different architectures don't interfere with each
other.
.PP
If the link trees already exist, then rerunning
.B linktree
will update the links.  This might be useful if the links somehow become
invalid.
.PP
To turn some of the links in the link trees into real files, use the
.B snaplink
command.
.
.SS listarch
Writes a list of all known architecture names to standard output.  The
list is obtained by reading the
.B archtab
file.
.
.SS make \fR[\fImake-arg\fR...]
Equivalent to
.VS
.BI "run make " make-arg\fR...
.VE
in all respects.
.
.SS only\-arch \fIarch arch\fR...
Imposes an architecture restriction.  Until cancelled by a later
.B only\-arch
or
.B all\-arch
command, the default build architectures will be limited to the
architectures listed on the command line.  Architecture names may be
abbreviated as long as the abbreviation is not ambiguous.
.
.SS reset
Clears the
.I "successfully built"
status of all architectures.
.
.SS rsh \fIhost\fR|\fIarch \fR[\fIcommand \fR[\fIargument\fR...]]
Runs
.I command
on a remote host, passing it the list of
.IR argument s.
The
.B "sw rsh"
command is unlike the standard
.B rsh
program and its replacements:
.hP \*o
The
.I command
and
.IR argument s
are not subjected to further shell expansion on the remote host.
.hP \*o
The command is run with the remote current directory the same as the
local current directory, rather than the remote user's home directory.
.hP \*o
The command is passed an environment constructed from the local
environment, the default remote environment, and
.B sw\-env
files, as described in the section
.B "Remote environment"
below.
.hP \*o
The remote command is run with standard input attached to
.BR /dev/null :
there is no way of running an interactive remote command through
.BR sw.
.PP
The host on which to run the remote command may be specified as one of:
a standard host name (or IP address), an architecture name (which may
.I not
be abbreviated) signifying a host of the appropriate architecture, or
the special name
.RB ` \- '
signifying the current host.  (This last option may not sound useful,
but it's handy for testing.)
.
.SS run \fIcommand \fR[\fIargument\fR...]
Runs a command on all build architectures.
.PP
For each build architecture
.IR arch ,
\*(sw finds a host with the appropriate architecture, by choosing either
the local host or reading the hostname from the
.B archtab
file.  It then performs the following actions on that host:
.hP 1.
Sets the current directory to be the subdirectory named
.I arch
of the directory from which the command was issued.  This directory is
created if it doesn't already exist.
.hP 2.
Sets up an environment constructed from the environment prevailing when
the command was issued, the default environment set up by
.B rsh
(or whatever equivalent remote execution program was actually used), and
the
.B sw\-env
files, as described in the section
.B "Remote environment"
below.
.hP 3.
Executes the program named
.I command
passing it the given
.IR argument s.
.PP
The command name and arguments may be subject to
.RB ` % '-escape
substitution, depending on whether the
.B \-p
option is enabled.  
.RB ` % '-escape
sequences are described in the section
.B "`%'-escape sequences"
below.
.PP
Output from the command is both appended to the file
.IB arch/.build-log
and output in some
.IR "output style" ,
as specified by the
.RB ` \-o '
command-line option.  See the section
.B "Output styles"
below for more details.
.PP
If the
.RB ` \-i '
option was given on the command line, each architecture on which the
command succeeds (i.e., reports a zero exit code) is marked as
.IR "successfully built" ,
and further build commands will not affect it unless the
.RB ` \-f '
command line option is passed, until a
.B reset
command is performed.
.
.SS setup \fIpackage version \fR[\fImaintainer\fR]
Sets up various pieces of information required by \*(sw.  The
information here will be added into the main index file by a
.B commit
command.  The information is maintained in a file named
.B .sw\-info
in the current directory.
.PP
The
.I package
should be the basic name of the package, with versioning information
stripped off, e.g.,
.RB ` emacs '
or
.RB ` perl ',
not
.RB ` emacs\-19.34 '.
The
.I version
should be the version number of the package.  The
.I maintainer
should be the name of the person principally responsible for maintaining
the package's local installation.  If this isn't specified, the calling
user's name is used as the maintainer.
.PP
The
.B setup
command must be run before any build command.
.
.SS snaplink \fIfile \fR[\fIfile\fR...]
Creates architecture-specific versions of a file.  Every
.I file
named on the command line is copied to
.IB arch / file
for every build architecture
.IR arch ,
overwriting any existing file or symbolic link of that name.  If
.I file
contains leading directories then destination directories are created as
necessary for the output files.  Note that the `snap' operation doesn't
actually need to follow creation of link trees.
.
.\"--------------------------------------------------------------------------
.
.SH "`%'-ESCAPE SUBSTITUTION"
.
If the
.B \-p
option is enabled, build commands and arguments are subject to
.RB ` % '-escape
substitution before being executed.  Certain two-character sequences,
with the first character
.RB ` % '
are replaced with strings, as follows:
.TP
.B %a
The architecture name of the host executing the command.
.TP
.B %h
The hostname of the host executing the command.
.TP
.B %P
The directory prefix with which \*(sw was installed.
.TP
.B %p
The name of the package being built.
.TP
.B %v
The version number of the package being built.
.TP
.B %u
The name of the maintainer of the package being built.
.TP
.B %%
A literal
.RB ` % '
character.
.PP
Any
.RB ` % '
sequences which aren't understood are left as they are.
.
.\"--------------------------------------------------------------------------
.
.SH "OUTPUT STYLES"
.
Output from a build command is presented in one of a number of named
.IR "output styles" .
The style name
.RB ` plain '
is always defined: it simply prefixes each line of output with the
name of the architecture which generated the line, which isn't actually
particularly easy to read.  Other output styles may have been configured
into \*(sw when it was compiled.
.PP
The set of output styles supported by \*(sw varies according to how it
was configured.  In any particular \*(sw program, you might have some of
the following:
.TP
.B plain
Simply prefixes each output line with the name of the architecture it
came from.  This is quite hard to read, but it doesn't require any
special operating system support or clever terminal.
.TP
.B curses
Splits the terminal into independently scrolling areas, one for each
architecture, with a status line for each.  Waits for a keypress when
all architectures are finished building.
.PP
The
.RB ` plain '
style is used when the selected style doesn't work (for example, you
don't have a sufficiently capable terminal for curses output).
.PP
Output style names can be abbreviated as long as the abbreviation is
unambiguous.  You can find the list of available output styles by
executing the command
.VS
sw \-o help run
.VE
(which is a little counter-intuitive, I know).
.PP
The author has plans to implement an X-based output style, but hasn't
got around to it yet.
.
.\"--------------------------------------------------------------------------
.
.SH "REMOTE ENVIRONMENT"
.
The environment for a remote command (executed either through the
.B rsh
command, or a build command) is set up as follows:
.hP \*o
The complete environment passed to \*(sw is used as a basis.
.hP \*o
Any environment variables defined by the remote execution program
(usually
.BR rsh )
override corresponding variables in the basis environment.
.hP \*o
The
.B SW_ARCH
variable is set to the name of the remote host's architecture.
.hP \*o
Variable assignments are read from the global 
.IB prefix /share/sw\-env
file.  This makes some assignments which are useful everywhere, and will
then usually include the file
.B .sw\-env
in the current directory.
.PP
The format of the
.B sw\-env
files is documented separately in
.BR sw\-env (5).
.
.\"--------------------------------------------------------------------------
.
.SH "LOCAL QUIRKS"
.
This section describes how non-vendor software works at EBI.  Chances
are that other sites will work differently.  This description is here as
an example setup for \*(sw.
.PP
All the non-vendor software gets put in one big shared filesystem, and
is exported from our main fileserver.  The filesystem is mounted on all
clients as
.BR /sw/common .
Architecture-neutral files are then
placed in the conventional subdirectories off
.B /sw/common
(e.g., 
.BR /sw/common/share,
or 
.BR /sw/common/info ).
Architecture specific files are stored in subdirectories off
.BR /sw/common/arch .
For example, Linux binaries go in
.BR /sw/common/arch/i386-linux/bin ,
and Solaris libraries in
.BR /sw/common/arch/sparc-solaris/lib .
Additionally, each architecture-specific subtree has a symbolic link
back up to
.B /sw/common
for each of the architecture-neutral subdirectories.
.PP
There is a symbolic link on every client, from
.B /sw/arch
to
.BI /sw/common/arch/ arch\fR,
where
.I arch
is the architecture of that client.  Thus, every client has two
.I views
of the software repository: the `common' view where every host sees
exactly the same mapping between filenames and files, and the `arch'
view where every host sees the same mapping between filenames and
programs which do the same job.
.PP
And that's just about it.
.
.\"--------------------------------------------------------------------------
.
.SH "ENVIRONMENT"
.
The following environment variables are of interest to \*(sw:
.TP
.B SW
Contains a space-separated list of default command-line options.  These
are read before, and overridden by, the actual arguments given on the
command-line.
.TP
.B SW_MAKE
The name of the command to use to run a `make'.  This is resolved on the
local host once, rather than one for each build host, which is probably
a misfeature.  To do something more clever, point
.B SW_MAKE
at a shell script which then picks out the right architecture-specific
.RB ` make '
program from the remote environment.
.TP
.B SW_RSH
The name of the remote-shell program to use.  By default, something
similar to
.B rsh
is chosen.  I recommend using the excellent
.B ssh
program instead.
.
.\"--------------------------------------------------------------------------
.
.SH "FILES"
.
The following files are of interest to \*(sw:
.TP
.IB prefix /sw\-index
The main index file, containing the list of which packages have been
installed for which architectures.  See
.BR sw-info (5)
for file format details.
.TP
.IB prefix /share/archtab
The architecture-to-host mapping file.  See
.BR archtab (5)
for file format details.
.TP
.IB prefix /share/sw\-env
Contains global environment variable settings.  See
.BR sw-env (5)
for file format details.
.TP
.IB prefix /share/sw\-precommit
Optional script used to approve commit requests.  See the
.B commit
command above for calling details.
.BR sw-env (5)
for file format details.
.TP
.IB package /.sw\-info
Contains the persistent information about a particular package's build
status.  See
.BR sw-info (5)
for file format details.
.TP
.IB package /.sw\-env
Contains package-specific environment variable settings.  See
.BR sw-env (5)
for file format details.
.TP
.IB package / arch /.build\-log
Contains all the build output for a particular architecture.  Usually
not very interesting, but might be handy one day.
.
.\"--------------------------------------------------------------------------
.
.SH "BUGS"
.
There are no bugs in
.BR sw ,
merely unexpected behaviour modes.  Silly you for thinking otherwise.
.
.SH "SEE ALSO"
.BR sw-cgi (1),
.BR sw-share (1),
.BR sw-tidy (1),
.BR archtab (5),
.BR sw-env (5),
.BR sw-info (5)
.
.SH "AUTHOR"
.
The \*(sw program, and this manual, are \*(mw productions, in association
with the European Bioinformatics Institute.  They were written by Mark
Wooding <mdw@nsict.org>.  Go and ask him if you have problems.
.
.\"----- That's all, folks --------------------------------------------------