.\" -*-nroff-*-
.\"
-.\" $Id: sw.1,v 1.4 1999/06/24 15:52:12 mdw Exp $
+.\" $Id$
.\"
.\" Manual page for `sw'
.\"
.\" (c) 1999 EBI
.\"
+.
.\"----- Licensing notice ---------------------------------------------------
.\"
.\" This file is part of sw-tools.
.\" 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.4 1999/06/24 15:52:12 mdw
-.\" Add documentation for the `sw-precommit' script.
-.\"
-.\" Revision 1.3 1999/06/18 18:58:25 mdw
-.\" Various tidyings.
-.\"
-.\" 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
.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
..
-.\"
-.\" --- Style hacking ---
-.\"
+.
.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
-.\"
-.\" --- Main manual text ---
-.\"
-.TH sw 1 "25 May 1999" "EBI tools"
+.
+.\"----- Main manual text ---------------------------------------------------
+.
+.TH sw 1 "25 May 1999" sw-tools
.PD 1
-.\"
-.SH NAME
+.
+.\"--------------------------------------------------------------------------
+.
+.SH "NAME"
+.
sw \- tool for convenient software installation
-.\"
-.SH SYNOPSIS
+.
+.\"--------------------------------------------------------------------------
+.
+.SH "SYNOPSIS"
+.
.nf
\fBsw \-\-help
\fBsw \-\-help-full
\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 \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 \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
-.\"
-.\"
+.
+.\"--------------------------------------------------------------------------
+.
.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
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:
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 '
.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 :
.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
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
.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
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"
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 '.
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.
The package's maintainer.
.TP
.B SW_DATE
-The last date on whicy the package was modified.
+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
.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
.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
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
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
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.
-.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.
-.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.
-.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
.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
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.
-.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
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
+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
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
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
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
.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
+.hP \*o
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.
-.HP \*o
+.hP \*o
The
.B SW_ARCH
variable is set to the name of the remote host's architecture.
-.HP \*o
+.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
.B sw\-env
files is documented separately in
.BR sw\-env (5).
-.\"
-.\"
-.SH LOCAL QUIRKS
+.
+.\"--------------------------------------------------------------------------
+.
+.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.
programs which do the same job.
.PP
And that's just about it.
-.\"
-.\"
-.SH ENVIRONMENT
-The following environment variables are of interest to
-.BR sw :
+.
+.\"--------------------------------------------------------------------------
+.
+.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
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
.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.
-.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.
-.\"
+.
.\"----- That's all, folks --------------------------------------------------
~mdw / sw-tools / blobdiff