usage: Print metavariables in SHOUTY letters.

[sw-tools] / sw.1

diff --git a/sw.1 b/sw.1
index e231e43..510f0c5 100644 (file)
--- a/sw.1
+++ b/sw.1
@@ -1,11 +1,12 @@
 .\" -*-nroff-*-
 .\"
 .\" -*-nroff-*-
 .\"

-.\" $Id: sw.1,v 1.2 1999/06/04 13:56:09 mdw Exp $
+.\" $Id$

 .\"
 .\" Manual page for `sw'
 .\"
 .\" (c) 1999 EBI
 .\"
 .\"
 .\" Manual page for `sw'
 .\"
 .\" (c) 1999 EBI
 .\"

+.

 .\"----- Licensing notice ---------------------------------------------------
 .\"
 .\" This file is part of sw-tools.
 .\"----- Licensing notice ---------------------------------------------------
 .\"
 .\" This file is part of sw-tools.


@@ -23,19 +24,9 @@
 .\" 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.
 .\" 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.

-.\"
-.\"----- Revision history ---------------------------------------------------
-.\"
-.\" $Log: sw.1,v $
-.\" Revision 1.2  1999/06/04 13:56:09  mdw
-.\" Changes, extensions, polishings, spelling fixes...
-.\"
-.\" Revision 1.1.1.1  1999/06/02 16:53:33  mdw
-.\" Initial import.
-.\"
-.\"
-.\" --- Useful macro definitions ---
-.\"
+.
+.\"----- Style hacking ------------------------------------------------------
+.

 .de VS \" Start a sort-of verbatim block
 .sp 1
 .in +5n
 .de VS \" Start a sort-of verbatim block
 .sp 1
 .in +5n


@@ -48,31 +39,35 @@
 .in -5n
 .sp 1
 ..
 .in -5n
 .sp 1
 ..

-.de HP \" Start an indented paragraph with a bold right-aligned label
+.de hP \" Start an indented paragraph with a bold right-aligned label

 .IP
 \fB\h'-\w'\\$1\ 'u'\\$1\ \fP\c
 ..
 .IP
 \fB\h'-\w'\\$1\ 'u'\\$1\ \fP\c
 ..

-.\"
-.\" --- Style hacking ---
-.\"
+.

 .ie \n(.g \{\
 .ie \n(.g \{\

-.      fam P
-.      ds mw \fR[\f(BImdw\fR]
+. fam P
+. ds mw \fR[\f(BImdw\fR]

 .\}
 .\}

-.el    .ds mw \fR[\fBmdw\fR]
-.ie t   .ds o \(bu
-.el     .ds o o
+.el .ds mw \fR[\fBmdw\fR]
+.ie t .ds o \(bu
+.el .ds o o

 .ds sw \fBsw\fP
 .ds sw \fBsw\fP

-.\"
-.\" --- Main manual text ---
-.\"
-.TH sw 1 "25 May 1999" "EBI tools"
+.
+.\"----- Main manual text ---------------------------------------------------
+.
+.TH sw 1 "25 May 1999" sw-tools

 .PD 1
 .PD 1

-.\"
-.SH NAME
+.
+.\"--------------------------------------------------------------------------
+.
+.SH "NAME"
+.

 sw \- tool for convenient software installation
 sw \- tool for convenient software installation

-.\"
-.SH SYNOPSIS
+.
+.\"--------------------------------------------------------------------------
+.
+.SH "SYNOPSIS"
+.

 .nf
 \fBsw \-\-help
 \fBsw \-\-help-full
 .nf
 \fBsw \-\-help
 \fBsw \-\-help-full


@@ -83,23 +78,25 @@ sw \- tool for convenient software installation
 \fBsw all\-arch
 \fBsw arch
 \fBsw commit
 \fBsw all\-arch
 \fBsw arch
 \fBsw commit

-\fBsw \fR[\fB\-fbi\fR] [\fB\-a \fIarch\fB,\fIarch\fR...] [\fB\-o \fIstyle\fR] \fBconfigure \fR[\fIconfigure-arg\fR...]
+\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 host \fIarch
 \fBsw \fR[\fB\-f\fR] [\fB\-a \fIarch\fB,\fIarch\fR...] \fBlinktree
 \fBsw listarch

-\fBsw \fR[\fB\-fbi\fR] [\fB\-a \fIarch\fB,\fIarch\fR...] [\fB\-o \fIstyle\fR] \fBmake \fR[\fImake-arg\fR...]
+\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 only\-arch \fIarch \fR[\fIarch\fR...]
 \fBsw reset
 \fBsw rsh \fIhost\fR|\fIarch \fR[\fIcommand \fR[\fIargument\fR...]]

-\fBsw \fR[\fB\-fbi\fR] [\fB\-a \fIarch\fB,\fIarch\fR...] [\fB\-o \fIstyle\fR] \fBrun \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
 \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"
 .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
 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


@@ -114,9 +111,11 @@ section below.
 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.
 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"
 .SH "SUMMARY OF BUILDING PACKAGES"

+.

 First, the
 .B Autoconf
 case:
 First, the
 .B Autoconf
 case:


@@ -146,9 +145,11 @@ sw make
 sw \-i make install
 sw commit
 .VE
 sw \-i make install
 sw commit
 .VE

-.\"
-.\"
+.
+.\"--------------------------------------------------------------------------
+.

 .SH "8 STEPS TO INSTALLING A PACKAGE"
 .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 '
 The following steps will guide you through your first (and maybe second)
 package installations.  In the description, I'll use
 .RI ` package '


@@ -336,9 +337,11 @@ 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.
 .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"
 .SH "REFERENCE INTRODUCTION"

+.

 That was a gentle introduction.  This section contains the complete
 reference to
 .BR sw :
 That was a gentle introduction.  This section contains the complete
 reference to
 .BR sw :


@@ -374,9 +377,11 @@ 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.
 .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"
 .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
 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


@@ -386,9 +391,11 @@ 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.
 the
 .B \-\-archname
 command line option, which shouldn't be used by anyone except \*(sw's build procedure anyway.

-.\"
-.\"
+.
+.\"--------------------------------------------------------------------------
+.

 .SH "COMMAND LINE OPTION REFERENCE"
 .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
 Any \*(sw command line options can be put in the
 .B SW
 environment variable.  The \*(sw program will read space-separated


@@ -470,7 +477,29 @@ for more details on output styles.
 .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
 .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.
+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
 .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


@@ -504,9 +533,11 @@ this option, but it shouldn't do any harm.
 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.
 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
+.
+.\"--------------------------------------------------------------------------
+.
+.SH "TERMINOLOGY"
+.

 The descriptions below make use of some technical terms:
 .TP
 .B "architecture restriction"
 The descriptions below make use of some technical terms:
 .TP
 .B "architecture restriction"


@@ -569,9 +600,13 @@ command.  The
 option causes \*(sw to ignore whether architectures have been successfully built when
 determining the
 .IR "default build architectures" .
 option causes \*(sw to ignore whether architectures have been successfully built when
 determining the
 .IR "default build architectures" .

+.
+.\"--------------------------------------------------------------------------
+.

 .SH "COMMAND REFERENCE"
 .SH "COMMAND REFERENCE"

+.

 This section describes all of the available \*(sw commands, in alphabetical order.
 This section describes all of the available \*(sw commands, in alphabetical order.

-.\"
+.

 .SS all\-arch
 Clears an architecture restriction set by
 .RB ` only\-arch '.
 .SS all\-arch
 Clears an architecture restriction set by
 .RB ` only\-arch '.


@@ -581,7 +616,7 @@ yet successfully built, unless overridden by the
 command-line option, or a later
 .RB ` only\-arch '
 command.
 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 arch
 Writes the name of the local host's architecture to standard output.
 The architecture name is built into \*(sw at compile time.


@@ -591,8 +626,41 @@ Writes information from the
 file to the installed packages index file
 .IB prefix /sw-index\fR.
 .PP
 file to the installed packages index file
 .IB prefix /sw-index\fR.
 .PP

-All expected architectures must be built before a commit will work.
-.\"
+\*(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
 .SS configure \fR[\fIconfigure-arg\fR...]
 Equivalent to the command
 .VS


@@ -609,14 +677,14 @@ 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.
 .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 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
 .SS linktree
 Builds symbolic link trees.  For each of the build architectures, a
 directory with the architecture's name is created containing a symbolic


@@ -634,20 +702,20 @@ invalid.
 To turn some of the links in the link trees into real files, use the
 .B snaplink
 command.
 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 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 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
 .SS only\-arch \fIarch arch\fR...
 Imposes an architecture restriction.  Until cancelled by a later
 .B only\-arch


@@ -656,12 +724,12 @@ or
 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.
 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 reset
 Clears the
 .I "successfully built"
 status of all architectures.

-.\"
+.

 .SS rsh \fIhost\fR|\fIarch \fR[\fIcommand \fR[\fIargument\fR...]]
 Runs
 .I command
 .SS rsh \fIhost\fR|\fIarch \fR[\fIcommand \fR[\fIargument\fR...]]
 Runs
 .I command


@@ -672,23 +740,23 @@ The
 command is unlike the standard
 .B rsh
 program and its replacements:
 command is unlike the standard
 .B rsh
 program and its replacements:

-.HP \*o
+.hP \*o

 The
 .I command
 and
 .IR argument s
 are not subjected to further shell expansion on the remote host.
 The
 .I command
 and
 .IR argument s
 are not subjected to further shell expansion on the remote host.

-.HP \*o
+.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.
 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
+.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.
 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
+.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
 The remote command is run with standard input attached to
 .BR /dev/null :
 there is no way of running an interactive remote command through


@@ -702,7 +770,7 @@ the special name
 .RB ` \- '
 signifying the current host.  (This last option may not sound useful,
 but it's handy for testing.)
 .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
 .SS run \fIcommand \fR[\fIargument\fR...]
 Runs a command on all build architectures.
 .PP


@@ -712,12 +780,12 @@ For each build architecture
 the local host or reading the hostname from the
 .B archtab
 file.  It then performs the following actions on that host:
 the local host or reading the hostname from the
 .B archtab
 file.  It then performs the following actions on that host:

-.HP 1.
+.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.
 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.
+.hP 2.

 Sets up an environment constructed from the environment prevailing when
 the command was issued, the default environment set up by
 .B rsh
 Sets up an environment constructed from the environment prevailing when
 the command was issued, the default environment set up by
 .B rsh


@@ -727,12 +795,22 @@ the
 files, as described in the section
 .B "Remote environment"
 below.
 files, as described in the section
 .B "Remote environment"
 below.

-.HP 3.
+.hP 3.

 Executes the program named
 .I command
 passing it the given
 .IR argument s.
 .PP
 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
 Output from the command is both appended to the file
 .IB arch/.build-log
 and output in some


@@ -753,7 +831,7 @@ and further build commands will not affect it unless the
 command line option is passed, until a
 .B reset
 command is performed.
 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
 .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


@@ -782,7 +860,7 @@ user's name is used as the maintainer.
 The
 .B setup
 command must be run before any build command.
 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
 .SS snaplink \fIfile \fR[\fIfile\fR...]
 Creates architecture-specific versions of a file.  Every
 .I file


@@ -795,9 +873,51 @@ overwriting any existing file or symbolic link of that name.  If
 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.
 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"
 .SH "OUTPUT STYLES"

+.

 Output from a build command is presented in one of a number of named
 .IR "output styles" .
 The style name
 Output from a build command is presented in one of a number of named
 .IR "output styles" .
 The style name


@@ -836,20 +956,26 @@ sw \-o help run
 .PP
 The author has plans to implement an X-based output style, but hasn't
 got around to it yet.
 .PP
 The author has plans to implement an X-based output style, but hasn't
 got around to it yet.

-.\"
-.\"
+.
+.\"--------------------------------------------------------------------------
+.

 .SH "REMOTE ENVIRONMENT"
 .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:
 The environment for a remote command (executed either through the
 .B rsh
 command, or a build command) is set up as follows:

-.HP \*o
+.hP \*o

 The complete environment passed to \*(sw is used as a basis.
 The complete environment passed to \*(sw is used as a basis.

-.HP \*o
+.hP \*o

 Any environment variables defined by the remote execution program
 (usually
 .BR rsh )
 override corresponding variables in the basis environment.
 Any environment variables defined by the remote execution program
 (usually
 .BR rsh )
 override corresponding variables in the basis environment.

-.HP \*o
+.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
 Variable assignments are read from the global 
 .IB prefix /share/sw\-env
 file.  This makes some assignments which are useful everywhere, and will


@@ -861,11 +987,57 @@ The format of the
 .B sw\-env
 files is documented separately in
 .BR sw\-env (5).
 .B sw\-env
 files is documented separately in
 .BR sw\-env (5).

-.\"
-.\"
-.SH ENVIRONMENT
-The following environment variables are of interest to
-.BR sw :
+.
+.\"--------------------------------------------------------------------------
+.
+.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
 .TP
 .B SW
 Contains a space-separated list of default command-line options.  These


@@ -888,10 +1060,12 @@ similar to
 is chosen.  I recommend using the excellent
 .B ssh
 program instead.
 is chosen.  I recommend using the excellent
 .B ssh
 program instead.

-.\"
-.SH FILES
-The following files are of interest to
-.BR sw :
+.
+.\"--------------------------------------------------------------------------
+.
+.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
 .TP
 .IB prefix /sw\-index
 The main index file, containing the list of which packages have been


@@ -909,6 +1083,13 @@ Contains global environment variable settings.  See
 .BR sw-env (5)
 for file format details.
 .TP
 .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
 .IB package /.sw\-info
 Contains the persistent information about a particular package's build
 status.  See


@@ -923,14 +1104,27 @@ for file format details.
 .IB package / arch /.build\-log
 Contains all the build output for a particular architecture.  Usually
 not very interesting, but might be handy one day.
 .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
+.
+.\"--------------------------------------------------------------------------
+.
+.SH "BUGS"
+.

 There are no bugs in
 .BR sw ,
 merely unexpected behaviour modes.  Silly you for thinking otherwise.
 There are no bugs in
 .BR sw ,
 merely unexpected behaviour modes.  Silly you for thinking otherwise.

-.SH AUTHOR
+.
+.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.
 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 --------------------------------------------------
 .\"----- That's all, folks --------------------------------------------------