+.\" -*-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 --------------------------------------------------