X-Git-Url: https://git.distorted.org.uk/~mdw/sw-tools/blobdiff_plain/95e672af19ea22b86981b5e0f4eefb5efed98484..be07bee0ba62d2cdd3d9b4c86e9362c711456f19:/sw.1 diff --git a/sw.1 b/sw.1 index e15f990..78cc17d 100644 --- a/sw.1 +++ b/sw.1 @@ -1,11 +1,12 @@ .\" -*-nroff-*- .\" -.\" $Id: sw.1,v 1.4 1999/06/24 15:52:12 mdw Exp $ +.\" $Id: sw.1,v 1.5 1999/07/16 12:45:37 mdw Exp $ .\" .\" Manual page for `sw' .\" .\" (c) 1999 EBI .\" +. .\"----- Licensing notice --------------------------------------------------- .\" .\" This file is part of sw-tools. @@ -23,10 +24,13 @@ .\" 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.5 1999/07/16 12:45:37 mdw +.\" Internal formatting improvements. +.\" .\" Revision 1.4 1999/06/24 15:52:12 mdw .\" Add documentation for the `sw-precommit' script. .\" @@ -39,9 +43,9 @@ .\" 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 @@ -54,31 +58,35 @@ .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 --- -.\" +. +.\"----- 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 @@ -103,9 +111,11 @@ sw \- tool for convenient software installation \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 @@ -120,9 +130,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. -.\" -.\" +. +.\"-------------------------------------------------------------------------- +. .SH "SUMMARY OF BUILDING PACKAGES" +. First, the .B Autoconf case: @@ -152,9 +164,11 @@ 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 ' @@ -342,9 +356,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. -.\" -.\" +. +.\"-------------------------------------------------------------------------- +. .SH "REFERENCE INTRODUCTION" +. That was a gentle introduction. This section contains the complete reference to .BR sw : @@ -380,9 +396,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. -.\" -.\" +. +.\"-------------------------------------------------------------------------- +. .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 @@ -392,9 +410,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. -.\" -.\" +. +.\"-------------------------------------------------------------------------- +. .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 @@ -510,9 +530,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. -.\" -.\" +. +.\"-------------------------------------------------------------------------- +. .SH TERMINOLOGY +. The descriptions below make use of some technical terms: .TP .B "architecture restriction" @@ -575,9 +597,13 @@ command. The 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 '. @@ -587,7 +613,7 @@ yet successfully built, unless overridden by the 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. @@ -631,7 +657,7 @@ 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 @@ -648,14 +674,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. -.\" +. .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 @@ -673,20 +699,20 @@ invalid. 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 @@ -695,12 +721,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. -.\" +. .SS reset Clears the .I "successfully built" status of all architectures. -.\" +. .SS rsh \fIhost\fR|\fIarch \fR[\fIcommand \fR[\fIargument\fR...]] Runs .I command @@ -711,23 +737,23 @@ The 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 @@ -741,7 +767,7 @@ the special name .RB ` \- ' signifying the current host. (This last option may not sound useful, but it's handy for testing.) -.\" +. .SS run \fIcommand \fR[\fIargument\fR...] Runs a command on all build architectures. .PP @@ -751,12 +777,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: -.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 @@ -766,7 +792,7 @@ the files, as described in the section .B "Remote environment" below. -.HP 3. +.hP 3. Executes the program named .I command passing it the given @@ -792,7 +818,7 @@ and further build commands will not affect it unless the 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 @@ -821,7 +847,7 @@ user's name is used as the maintainer. 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 @@ -834,9 +860,11 @@ 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. -.\" -.\" +. +.\"-------------------------------------------------------------------------- +. .SH "OUTPUT STYLES" +. Output from a build command is presented in one of a number of named .IR "output styles" . The style name @@ -875,24 +903,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. -.\" -.\" +. +.\"-------------------------------------------------------------------------- +. .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 @@ -904,9 +934,11 @@ The format of the .B sw\-env files is documented separately in .BR sw\-env (5). -.\" -.\" +. +.\"-------------------------------------------------------------------------- +. .SH LOCAL QUIRKS +. This section describes how non-vendor software works at EBI. Chances are that other sites will work differently. This description is here as an example setup for \*(sw. @@ -947,9 +979,11 @@ 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 .BR sw : .TP @@ -974,8 +1008,11 @@ similar to is chosen. I recommend using the excellent .B ssh program instead. -.\" +. +.\"-------------------------------------------------------------------------- +. .SH FILES +. The following files are of interest to .BR sw : .TP @@ -1016,14 +1053,19 @@ 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. -.\" +. +.\"-------------------------------------------------------------------------- +. .SH BUGS +. There are no bugs in .BR sw , merely unexpected behaviour modes. Silly you for thinking otherwise. +. .SH AUTHOR +. The \*(sw program, and this manual, are \*(mw productions, in association with the European Bioinformatics Institute. They were written by Mark Wooding . Go and ask him if you have problems. -.\" +. .\"----- That's all, folks --------------------------------------------------