.\" -*-nroff-*-
.\"
.\" $Id: sw.1,v 1.1 1999/06/02 16:53:33 mdw Exp $
.\"
.\" 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.
.\"
.\"----- Revision history ---------------------------------------------------
.\"
.\" $Log: sw.1,v $
.\" Revision 1.1  1999/06/02 16:53:33  mdw
.\" Initial revision
.\"
.\"
.\" --- Useful macro definitions ---
.\"
.de VS
.sp 1
.in +5n
.nf
.ft B
..
.de VE
.ft R
.fi
.in -5n
.sp 1
..
.\"
.\" --- Style hacking for `groff' ---
.\"
.ie \n(.g \{\
.	fam P
.	de MW
\fR[\f(BImdw\fR]
..
.\}
.el \{\
.	de MW
\fR[\fBmdw\fR]
..
.\}
.\"
.\" --- Main manual text ---
.\"
.TH sw 1 "25 May 1999" "EBI 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 \fR[\fB\-fbi\fR] [\fB\-a \fIarch\fB,\fIarch\fR...] [\fB\-o \fIstyle\fR] \fBconfigure \fR[\fIconfgure-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 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 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
.B 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
.BR 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
.B 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
.B 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
.B 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
.B 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
.B 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
.B 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
.B 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
.B sw
by saying
.VS
sw \-i make install
.VE
The little
.RB ` \-i '
option there tells
.B sw
that this is the
.IR "install step" .
When an architecture completes this step correctly, it's marked as being
properly installed, and
.B 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
.B 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
.B 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
.B 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,
.B 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
.B 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
.B sw
to do more exotic things, though.
.\"
.\"
.SH "IMPLEMENTATION ODDITIES"
The
.B 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
.B 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
.BR sw 's
build procedure anyway.
.\"
.\"
.SH "COMMAND LINE OPTION REFERENCE"
Any
.B sw
command line options can be put in the
.B SW
environment variable.  The
.B sw
program will read space-separated options from this variable before it
reads the command line itself.
.PP
The
.B 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
.B sw
command line options: those which, usually for reasons of consistency
with other programs, cause
.B 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
.B sw
is as follows:
.TP
.B "\-h, \-\-help"
Writes a fairly brief summary of
.BR sw 's
command line options and a usage line for each of
.BR sw 's
commands to standard output, and exits successfully.
.TP
.B "\-H, \-\-help\-full"
Writes a summary of
.BR sw 's
command line options and a full paragraph of description for each of
.BR 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
.BR sw 's
version number to standard output and exits successfully.  This is handy
when trying to decide whether your version of
.B 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
.B sw
without any arguments is considered an error, so the message is sent to
standard error and
.B 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.  This option overrides any other decisions that
.B 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.
.PP
The remaining options aren't really intended for users.  They're helpful
for
.BR 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
.B sw
architecture name of the current host to standard output.  This is used
by
.BR 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
.BR sw 's
idea of its program name to
.IR name .
This is intended for use by
.BR 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
.B sw
when running commands on remote hosts.  Don't use this yourself: it puts
.B 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 "COMMAND REFERENCE"
.SS 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,
.B 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
.B sw
to ignore whether architectures have been successfully built when
determining the
.IR "default build architectures" .
.bp
This section describes all of the available
.B sw
commands, in alphabetical order.
.\"
.SS all-arch
.PP
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
.B sw
at compile time.
.\"
.SS configure \fR[\fIconfigure-arg\fR...]
.\"
.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 linkfree
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...]
.\"
.SS only-arch \fIarch arch\fR...
.\"
.SS rsh \fIhost\fR|\fIarch \fR[\fIcommand \fR[\fIargument\fR...]]
.\"
.SS run \fIcommand \fR[\fIargument\fR...]
.\"
.SS setup \fIpackage version \fR[\fImaintainer\fR]
.\"
.SS snaplink \fIfile \fR[\fIfile\fR...]
Creates archtitecture-specific versions of a file.  For each build
architecture
.I arch
and file 
.IR file ,
.B sw
creates a copy
.IB arch / file\c
, replacing
.\"
.SS status
foo
.\"
.\"
.\"
.\"
.\"
.\"
.\"
.\"
.\"
.\"
.\"
.\"
.bp
.\"
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
.B sw
when it was compiled.
.PP
The set of output styles supported by
.B sw
varies according to how it was configured.  In any particular
.B 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 always available.  It's 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.
.PP
The author has plans to implement an X-based output style, but hasn't
got around to it yet.
.\"
.\"
.\"
.\"
.\"
.\"
.\"
.\"
.\"
.\"
.\"
.\"
.\"
.\"
.SH ENVIRONMENT
The following environment variables are of interest to
.BR 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_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
.BR 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 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 AUTHOR
The
.B sw
program, and this manual, are
.MW
productions, in association
with the European Bioinformatics Instutute.  They were written by Mark
Wooding <mdw@nsict.org>.  Go and ask him if you have problems.
.\"
.\"----- That's all, folks --------------------------------------------------