3 .\" $Id: sw.1,v 1.2 1999/06/04 13:56:09 mdw Exp $
5 .\" Manual page for `sw'
9 .\"----- Licensing notice ---------------------------------------------------
11 .\" This file is part of sw-tools.
13 .\" sw-tools is free software; you can redistribute it and/or modify
14 .\" it under the terms of the GNU General Public License as published by
15 .\" the Free Software Foundation; either version 2 of the License, or
16 .\" (at your option) any later version.
18 .\" sw-tools is distributed in the hope that it will be useful,
19 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
20 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 .\" GNU General Public License for more details.
23 .\" You should have received a copy of the GNU General Public License
24 .\" along with sw-tools; if not, write to the Free Software Foundation,
25 .\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
27 .\"----- Revision history ---------------------------------------------------
30 .\" Revision 1.2 1999/06/04 13:56:09 mdw
31 .\" Changes, extensions, polishings, spelling fixes...
33 .\" Revision 1.1.1.1 1999/06/02 16:53:33 mdw
37 .\" --- Useful macro definitions ---
39 .de VS \" Start a sort-of verbatim block
45 .de VE \" Stop a sort-of verbatim block
51 .de HP \" Start an indented paragraph with a bold right-aligned label
53 \fB\h'-\w'\\$1\ 'u'\\$1\ \fP\c
56 .\" --- Style hacking ---
60 . ds mw \fR[\f(BImdw\fR]
62 .el .ds mw \fR[\fBmdw\fR]
67 .\" --- Main manual text ---
69 .TH sw 1 "25 May 1999" "EBI tools"
73 sw \- tool for convenient software installation
81 \fBsw \-\-remote \fIcommand
86 \fBsw \fR[\fB\-fbi\fR] [\fB\-a \fIarch\fB,\fIarch\fR...] [\fB\-o \fIstyle\fR] \fBconfigure \fR[\fIconfigure-arg\fR...]
88 \fBsw \fR[\fB\-f\fR] [\fB\-a \fIarch\fB,\fIarch\fR...] \fBlinktree
90 \fBsw \fR[\fB\-fbi\fR] [\fB\-a \fIarch\fB,\fIarch\fR...] [\fB\-o \fIstyle\fR] \fBmake \fR[\fImake-arg\fR...]
91 \fBsw only\-arch \fIarch \fR[\fIarch\fR...]
93 \fBsw rsh \fIhost\fR|\fIarch \fR[\fIcommand \fR[\fIargument\fR...]]
94 \fBsw \fR[\fB\-fbi\fR] [\fB\-a \fIarch\fB,\fIarch\fR...] [\fB\-o \fIstyle\fR] \fBrun \fIcommand \fR[\fIargument\fR...]
95 \fBsw setup \fIpackage version \fR[\fImaintainer\fR]
96 \fBsw \fR[\fB\-f\fR] [\fB\-a \fIarch\fB,\fIarch\fR...] \fBsnaplink \fIfile \fR[\fIfile\fR...]
103 The \*(sw tool attempts to take a lot of the work out of building and
104 installing source packages across multiple architectures. This section
105 will describe how to use \*(sw's features to best advantage in a number
106 of common situations.
108 To keep things concrete, I'll describe how things are done at the EBI,
109 although there's nothing EBI-specific about the \*(sw program itself.
110 For details about how we handle software at EBI, see the
114 By the way, this is quite a large manual. I recommend that you print a
115 copy onto paper and peruse it in a leisurely fashion, rather than
116 squinting at a monitor.
119 .SH "SUMMARY OF BUILDING PACKAGES"
124 .BI "sw setup " "package version"
126 .IR "arch " [ arch ...]
137 .BI "sw setup " "package version"
139 .IR "arch " [ arch ...]
142 .IR "file " [ file ...]
143 .I [edit the appropriate files]
151 .SH "8 STEPS TO INSTALLING A PACKAGE"
152 The following steps will guide you through your first (and maybe second)
153 package installations. In the description, I'll use
155 to refer to the package's name, and
157 to refer to its version number.
159 Not all the important features and options are described in this part of
160 the manual. View it more as a taster for the sorts of things \*(sw can
162 .SS "1. Download the source distribution"
163 Download the package's source distribution. This will normally be in an
164 archive called something like
165 .IB package - version .tar.gz\c
166 \&. At EBI, we put source archive files in
168 .SS "2. Unpack the source tree"
169 Unpack the source tree into the standard source directory. Each source
170 tree should have its own directory. Most well-packaged source
171 distributions unpack themselves into a neat directory, but less
172 fastidious programmers make archives which scatter files all over the
175 At EBI, we put the source trees in
177 so unpacking a well-formed source distribution looks like:
180 .BI "gzip \-dc ../tr/" package \- version ".tar.gz | tar xfv \-"
182 Ill-formed source distributions involve making the directory for the
183 package first, changing into it, and then unpacking into the current
187 .BI "mkdir " package \- version
188 .BI "cd " package \- version
189 .BI "gzip \-dc ../../tr/" package - version ".tar.gz | tar xfv \-"
191 When you've finished unpacking, make sure that your current directory is
192 the top level directory of the source tree you unpacked.
193 .SS "3. Tell \\*(sw what you're up to"
194 Now you need to tell \*(sw what you're working on. It will keep track of
195 this and other bits of information in a little file and refer to it
196 every now and then. It will also whinge at you and refuse to cooperate
197 if it can't find its little file, so it's as well to oblige.
199 To tell \*(sw to create this little file and initialize it with sensible
200 values, you just need to say
202 .BI "sw setup " "package version"
204 What could be easier?
205 .SS "4. Restrict the build to particular architectures"
206 Some packages don't work on all architectures, either because the author
207 wasn't sufficiently good at writing portable software, or because the
208 program's doing inherently nonportable things.
210 If that's the case, then you need to tell \*(sw to only build on the
211 architectures that really work. Do this with the
213 command. For example, if your package only works on Linux and Solaris,
216 sw only i386-linux sparc-solaris
218 You can get a list of the architecture names that \*(sw understands by
223 With a little bit of luck, these names ought to be self-explanatory.
225 If your package is properly portable and works everywhere then you don't
226 need to do anything for this step. Skip on to the next one.
227 .SS "5. Configure the package"
228 Now it gets complicated. If the package you're building uses
230 to configure itself for its current environment then you're in luck.
233 package because there's a script called
235 in the top source directory, and a file called
245 to configure the package on all the platforms it's meant to be built
246 for. When you've done that, move onto the next step.
252 then all is not lost (although it may be worthwhile complaining at the
253 package's author or maintainers). You need to make a collection of
255 one for each architecture. These link trees are little replicas of the
256 main source tree but with symbolic links instead of the real source
257 files. To make the link trees, run
261 Now, that's not actually quite what you wanted. It's made a link for
263 file in the source tree. Unfortunately, there are some files you'll
264 (probably) have to modify for each architecture in order to configure
265 the package to build properly. You can turn links in the link trees
266 into real independently editable files by
268 the links. Say for example that
272 need to be modified for each architecture. Running the command
274 sw snaplink Makefile config.h
276 is sufficient to do the right thing.
278 Now you must edit the snapped files to configure the package. Make sure
279 that the install directories are correctly set. At EBI, all the
280 software should be configured so that architecture neutral files end up
283 and architecture-specific files end up under
284 .BI /sw/common/arch/ arch\c
286 .SS "6. Build the package"
287 Now you've laid the groundwork, everything ought to be easy. Making the
288 program ought to involve simply typing
292 and waiting for a while. If you had the
294 library available when \*(sw was built, then your terminal will split
295 itself into little independently scrolling windows showing you the
296 progress for each architecture. If you're not privileged enough to have
298 then you get the output appropriately tagged with architecture names,
299 which is unfortunately fairly hard to read.
300 .SS "7. Install the package"
301 Most source packages (and almost certainly all
307 which installs the program correctly. You can run this from \*(sw by
314 option there tells \*(sw that this is the
316 When an architecture completes this step correctly, it's marked as being
317 properly installed, and \*(sw doesn't bother thinking about it again.
323 makefile target, then you have to install things manually. That's not
324 much fun, so moan at the package's author. When you've finished
325 fiddling with installation, run
329 just to tell \*(sw that you've installed everything OK. (This is a bit
331 .SS "8. Update the index"
332 Now that everything's built and installed, there's just one more command
337 This makes \*(sw update its main index of installed packages, telling it
338 which architectures packages are installed on, and who did it.
341 .SH "REFERENCE INTRODUCTION"
342 That was a gentle introduction. This section contains the complete
345 far more detail that you probably want. If that's really the case, try
350 to read the available help text. There's quite a lot of it, and it
351 ought to keep you occupied for a while.
353 The basic \*(sw command line looks a bit like:
366 at the shell prompt, \*(sw gives you an extremely terse usage summary
367 and quits. You have to tell it to do
369 Most of the time you do this by giving \*(sw a
375 so that it knows what to do. There are some strange command line
376 options which cause \*(sw to do more exotic things, though.
379 .SH "IMPLEMENTATION ODDITIES"
380 The \*(sw program that users use is really a small architecture-neutral
381 shell script, which works out the current architecture and executes the
382 appropriate architecture-specific main program. It's done this way so
383 that \*(sw knows that it can use the shell script to start itself up on
384 a remote host with a different architecture, something which it does
385 quite a lot. The only feature provided by the front-end shell script is
388 command line option, which shouldn't be used by anyone except \*(sw's build procedure anyway.
391 .SH "COMMAND LINE OPTION REFERENCE"
392 Any \*(sw command line options can be put in the
394 environment variable. The \*(sw program will read space-separated
395 options from this variable before it reads the command line itself.
397 The \*(sw program usually understands two different names for each
398 option: a traditional Unix single-character name, and a long GNU-style
399 name. The short options behave in the normal Unix way: you can join
400 them together into single words with a
402 at the front, for example. The long names are always preceded by a
403 double dash. You can abbreviate long names as much as you like, as long
404 as the resulting abbreviation is unambiguous. In the descriptions
405 below, both the short and long names of the options are shown, but for
406 reasons of brevity required arguments are only shown for the long form.
408 There are conceptually two types of \*(sw command line options: those
409 which, usually for reasons of consistency with other programs, cause
410 \*(sw to do something immediately; and those which store some settings
411 for particular commands. The latter type are generally more useful.
412 It's worth bearing in mind, though, that the options are only used by a
413 few commands. The command reference describes exactly which commands
416 The complete list of command line options understood by the current
417 version of \*(sw is as follows:
420 Writes a fairly brief summary of \*(sw's command line options and a usage line for each of \*(sw's commands to standard output, and exits successfully.
422 .B "\-H, \-\-help\-full"
423 Writes a summary of \*(sw's command line options and a full paragraph of description for each of \*(sw's commands to standard output, and exits successfully. There's a lot of
424 text generated by this option. I recommend you pipe it through a pager
425 so that you can actually read it.
427 .B "\-v, \-\-version"
428 Writes \*(sw's version number to standard output and exits successfully. This is handy
429 when trying to decide whether your version of \*(sw has a particular feature, for example.
432 Writes a usage message so terse as to be nearly useless to standard
433 output and exits successfully. This is different from just running
435 because although both print the same useless message, running \*(sw without any arguments is considered an error, so the message is sent to
436 standard error and \*(sw will exit unsuccessfully.
438 .BI "\-a, \-\-arch " arch , arch\fR...
439 For commands which affect multiple architectures: only affect the
440 architectures specified. The architecture names may be separated by
441 commas, spaces or both, although clearly commas are most convenient on
442 the command line. Architecture names may be abbreviated as long as the
443 abbreviation is not ambiguous.
445 This option overrides any other decisions that \*(sw might make about which architectures to process based on the
447 list and the list of correctly built architectures for the current
451 For commands which affect multiple architectures: affect even
452 architectures that have been successfully built. This has no effect if
457 .B "\-i, \-\-install"
458 For build commands: this is the final install step, so label architectures
459 which successfully complete it as having been completely built. It's
460 normal to specify this option on the
461 .RB ` "make install" '
464 .BI "\-o, \-\-output " style
465 For build commands: select a style for the build output to be displayed
468 for more details on output styles.
471 For build commands: make a beep noise when the build finishes. This
472 provides a handy reminder if you're getting on with something else while
473 waiting for a long build.
475 The remaining options aren't really intended for users. They're helpful
476 for \*(sw's own purposes, though, and described here for completeness' sake. They
477 don't have standard Unix short name equivalents, because they're not
478 usually useful for users.
481 Writes the \*(sw architecture name of the current host to standard output. This is used
482 by \*(sw's configuration script to determine the current architecture name. This
483 option is actually handled by a small shell script rather than by being
484 passed on to the main program. You shouldn't use this option yourself:
487 command instead. Because this option is handled by the shell script,
488 and the script isn't very clever, you can't abbreviate
490 on the command line, and it doesn't conflict with the similarly named
491 but completely different
493 option, which you can still abbreviate all the way down to just
497 Sets \*(sw's idea of its program name to
499 This is intended for use by \*(sw's front-end shell script, but isn't
500 actually needed at the moment. I can't see why you'd want to play with
501 this option, but it shouldn't do any harm.
503 .BI "\-\-remote " remote-command
504 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
505 using a bizarre binary packet protocol. If you really must know more
506 about this, see the source code: it's quite well documented, really.
510 The descriptions below make use of some technical terms:
512 .B "architecture restriction"
513 A state created by the
515 command, restricting the
516 .I "default build architectures"
517 to those listed as arguments to the command. An architecture
518 restriction may be cleared by
522 .B "build architectures"
523 The architectures which a
527 option is specified on the command line, then its argument specifies the
528 build architectures for this command; otherwise, the
529 .I "default build architectures"
533 A command which executes a process on multiple hosts simultaneously and
534 reports the results. The processes executed usually perform some part
535 of the building of a package. Currently, the build commands are
542 .B "default build architectures"
543 The architectures which, in the absence of a
545 command line option, are affected by a
546 .IR "build command" .
547 To determine the default build architectures, \*(sw reads the list of all architectures from the
549 file, and filters it: if the
551 command line option is
553 specified, then architectures marked as
554 .I "successfully built"
555 are removed from the list; if there is an
556 .I "architecture restriction"
557 in force, then the list is further filtered according to the
560 .B "successfully built"
561 A package is considered to be successfully built on a given architecture
562 if a build command given the
564 command-line option succeeds on a host of that architecture. The list
565 of successfully built architectures can be cleared by the
569 option causes \*(sw to ignore whether architectures have been successfully built when
571 .IR "default build architectures" .
572 .SH "COMMAND REFERENCE"
573 This section describes all of the available \*(sw commands, in alphabetical order.
576 Clears an architecture restriction set by
578 Subsequent build commands will run across all known architectures not
579 yet successfully built, unless overridden by the
581 command-line option, or a later
586 Writes the name of the local host's architecture to standard output.
587 The architecture name is built into \*(sw at compile time.
589 Writes information from the
591 file to the installed packages index file
592 .IB prefix /sw-index\fR.
594 All expected architectures must be built before a commit will work.
596 .SS configure \fR[\fIconfigure-arg\fR...]
597 Equivalent to the command
599 .BI "run ../configure \-\-prefix=" prefix " " configure-arg\fR...
603 is the installation prefix with which \*(sw itself was configured. If you want to specify a different prefix, pass
608 It is expected that administrators will set up a file
609 .IB prefix /share/config.site
610 which sets up other Autoconf parameters once the prefix has been
611 chosen. See the Autoconf manual for more information.
614 Writes to standard output the name of a host with requested architecture
616 The hostname is read from the
621 Builds symbolic link trees. For each of the build architectures, a
622 directory with the architecture's name is created containing a symbolic
623 link corresponding to each file in the main source tree. Thus, a `make'
624 in the link tree will fetch the source files correctly, but place the
625 objects in the link tree rather than the main source tree, so that
626 object files from different architectures don't interfere with each
629 If the link trees already exist, then rerunning
631 will update the links. This might be useful if the links somehow become
634 To turn some of the links in the link trees into real files, use the
639 Writes a list of all known architecture names to standard output. The
640 list is obtained by reading the
644 .SS make \fR[\fImake-arg\fR...]
647 .BI "run make " make-arg\fR...
651 .SS only\-arch \fIarch arch\fR...
652 Imposes an architecture restriction. Until cancelled by a later
656 command, the default build architectures will be limited to the
657 architectures listed on the command line. Architecture names may be
658 abbreviated as long as the abbreviation is not ambiguous.
662 .I "successfully built"
663 status of all architectures.
665 .SS rsh \fIhost\fR|\fIarch \fR[\fIcommand \fR[\fIargument\fR...]]
668 on a remote host, passing it the list of
672 command is unlike the standard
674 program and its replacements:
680 are not subjected to further shell expansion on the remote host.
682 The command is run with the remote current directory the same as the
683 local current directory, rather than the remote user's home directory.
685 The command is passed an environment constructed from the local
686 environment, the default remote environment, and
688 files, as described in the section
689 .B "Remote environment"
692 The remote command is run with standard input attached to
694 there is no way of running an interactive remote command through
697 The host on which to run the remote command may be specified as one of:
698 a standard host name (or IP address), an architecture name (which may
700 be abbreviated) signifying a host of the appropriate architecture, or
703 signifying the current host. (This last option may not sound useful,
704 but it's handy for testing.)
706 .SS run \fIcommand \fR[\fIargument\fR...]
707 Runs a command on all build architectures.
709 For each build architecture
711 \*(sw finds a host with the appropriate architecture, by choosing either
712 the local host or reading the hostname from the
714 file. It then performs the following actions on that host:
716 Sets the current directory to be the subdirectory named
718 of the directory from which the command was issued. This directory is
719 created if it doesn't already exist.
721 Sets up an environment constructed from the environment prevailing when
722 the command was issued, the default environment set up by
724 (or whatever equivalent remote execution program was actually used), and
727 files, as described in the section
728 .B "Remote environment"
731 Executes the program named
736 Output from the command is both appended to the file
742 command-line option. See the section
744 below for more details.
748 option was given on the command line, each architecture on which the
749 command succeeds (i.e., reports a zero exit code) is marked as
750 .IR "successfully built" ,
751 and further build commands will not affect it unless the
753 command line option is passed, until a
755 command is performed.
757 .SS setup \fIpackage version \fR[\fImaintainer\fR]
758 Sets up various pieces of information required by \*(sw. The
759 information here will be added into the main index file by a
761 command. The information is maintained in a file named
763 in the current directory.
767 should be the basic name of the package, with versioning information
773 .RB ` emacs\-19.34 '.
776 should be the version number of the package. The
778 should be the name of the person principally responsible for maintaining
779 the package's local installation. If this isn't specified, the calling
780 user's name is used as the maintainer.
784 command must be run before any build command.
786 .SS snaplink \fIfile \fR[\fIfile\fR...]
787 Creates architecture-specific versions of a file. Every
789 named on the command line is copied to
791 for every build architecture
793 overwriting any existing file or symbolic link of that name. If
795 contains leading directories then destination directories are created as
796 necessary for the output files. Note that the `snap' operation doesn't
797 actually need to follow creation of link trees.
801 Output from a build command is presented in one of a number of named
802 .IR "output styles" .
805 is always defined: it simply prefixes each line of output with the
806 name of the architecture which generated the line, which isn't actually
807 particularly easy to read. Other output styles may have been configured
808 into \*(sw when it was compiled.
810 The set of output styles supported by \*(sw varies according to how it
811 was configured. In any particular \*(sw program, you might have some of
815 Simply prefixes each output line with the name of the architecture it
816 came from. This is quite hard to read, but it doesn't require any
817 special operating system support or clever terminal.
820 Splits the terminal into independently scrolling areas, one for each
821 architecture, with a status line for each. Waits for a keypress when
822 all architectures are finished building.
826 style is used when the selected style doesn't work (for example, you
827 don't have a sufficiently capable terminal for curses output).
829 Output style names can be abbreviated as long as the abbreviation is
830 unambiguous. You can find the list of available output styles by
831 executing the command
835 (which is a little counter-intuitive, I know).
837 The author has plans to implement an X-based output style, but hasn't
838 got around to it yet.
841 .SH "REMOTE ENVIRONMENT"
842 The environment for a remote command (executed either through the
844 command, or a build command) is set up as follows:
846 The complete environment passed to \*(sw is used as a basis.
848 Any environment variables defined by the remote execution program
851 override corresponding variables in the basis environment.
853 Variable assignments are read from the global
854 .IB prefix /share/sw\-env
855 file. This makes some assignments which are useful everywhere, and will
856 then usually include the file
858 in the current directory.
862 files is documented separately in
867 The following environment variables are of interest to
871 Contains a space-separated list of default command-line options. These
872 are read before, and overridden by, the actual arguments given on the
876 The name of the command to use to run a `make'. This is resolved on the
877 local host once, rather than one for each build host, which is probably
878 a misfeature. To do something more clever, point
880 at a shell script which then picks out the right architecture-specific
882 program from the remote environment.
885 The name of the remote-shell program to use. By default, something
888 is chosen. I recommend using the excellent
893 The following files are of interest to
896 .IB prefix /sw\-index
897 The main index file, containing the list of which packages have been
898 installed for which architectures. See
900 for file format details.
902 .IB prefix /share/archtab
903 The architecture-to-host mapping file. See
905 for file format details.
907 .IB prefix /share/sw\-env
908 Contains global environment variable settings. See
910 for file format details.
912 .IB package /.sw\-info
913 Contains the persistent information about a particular package's build
916 for file format details.
918 .IB package /.sw\-env
919 Contains package-specific environment variable settings. See
921 for file format details.
923 .IB package / arch /.build\-log
924 Contains all the build output for a particular architecture. Usually
925 not very interesting, but might be handy one day.
930 merely unexpected behaviour modes. Silly you for thinking otherwise.
932 The \*(sw program, and this manual, are \*(mw productions, in association
933 with the European Bioinformatics Institute. They were written by Mark
934 Wooding <mdw@nsict.org>. Go and ask him if you have problems.
936 .\"----- That's all, folks --------------------------------------------------
~mdw / sw-tools / blob