X-Git-Url: https://git.distorted.org.uk/~mdw/sw-tools/blobdiff_plain/91f523553ada4ecc6307b105ba27674d6845bb84..HEAD:/sw.1 diff --git a/sw.1 b/sw.1 index e231e43..510f0c5 100644 --- a/sw.1 +++ b/sw.1 @@ -1,11 +1,12 @@ .\" -*-nroff-*- .\" -.\" $Id: sw.1,v 1.2 1999/06/04 13:56:09 mdw Exp $ +.\" $Id$ .\" .\" Manual page for `sw' .\" .\" (c) 1999 EBI .\" +. .\"----- 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. -.\" -.\"----- 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 @@ -48,31 +39,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 --- -.\" -.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 @@ -83,23 +78,25 @@ sw \- tool for convenient software installation \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 @@ -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. -.\" -.\" +. +.\"-------------------------------------------------------------------------- +. .SH "SUMMARY OF BUILDING PACKAGES" +. First, the .B Autoconf case: @@ -146,9 +145,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 ' @@ -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. -.\" -.\" +. +.\"-------------------------------------------------------------------------- +. .SH "REFERENCE INTRODUCTION" +. 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. -.\" -.\" +. +.\"-------------------------------------------------------------------------- +. .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 @@ -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. -.\" -.\" +. +.\"-------------------------------------------------------------------------- +. .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 @@ -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 -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 @@ -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. -.\" -.\" -.SH TERMINOLOGY +. +.\"-------------------------------------------------------------------------- +. +.SH "TERMINOLOGY" +. 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" . +. +.\"-------------------------------------------------------------------------- +. .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 '. @@ -581,7 +616,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. @@ -591,8 +626,41 @@ Writes information from the 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 @@ -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. -.\" +. .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 @@ -634,20 +702,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 @@ -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. -.\" +. .SS reset Clears the .I "successfully built" status of all architectures. -.\" +. .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: -.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 @@ -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.) -.\" +. .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: -.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 @@ -727,12 +795,22 @@ 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 .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 @@ -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. -.\" +. .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. -.\" +. .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. -.\" -.\" +. +.\"-------------------------------------------------------------------------- +. +.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 @@ -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. -.\" -.\" +. +.\"-------------------------------------------------------------------------- +. .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 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). -.\" -.\" -.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 @@ -888,10 +1060,12 @@ similar to 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 @@ -909,6 +1083,13 @@ Contains global environment variable settings. See .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 @@ -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. -.\" -.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 . Go and ask him if you have problems. -.\" +. .\"----- That's all, folks --------------------------------------------------