3 .\" $Id: sw.1,v 1.1 1999/06/02 16:53:33 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.1 1999/06/02 16:53:33 mdw
34 .\" --- Useful macro definitions ---
49 .\" --- Style hacking for `groff' ---
63 .\" --- Main manual text ---
65 .TH sw 1 "25 May 1999" "EBI tools"
69 sw \- tool for convenient software installation
77 \fBsw --remote \fIcommand
81 \fBsw \fR[\fB\-fbi\fR] [\fB\-a \fIarch\fB,\fIarch\fR...] [\fB\-o \fIstyle\fR] \fBconfigure \fR[\fIconfgure-arg\fR...]
83 \fBsw \fR[\fB\-f\fR] [\fB\-a \fIarch\fB,\fIarch\fR...] \fBlinktree
85 \fBsw \fR[\fB\-fbi\fR] [\fB\-a \fIarch\fB,\fIarch\fR...] [\fB\-o \fIstyle\fR] \fBmake \fR[\fImake-arg\fR...]
86 \fBsw only-arch \fIarch \fR[\fIarch\fR...]
88 \fBsw rsh \fIhost\fR|\fIarch \fR[\fIcommand \fR[\fIargument\fR...]]
89 \fBsw \fR[\fB\-fbi\fR] [\fB\-a \fIarch\fB,\fIarch\fR...] [\fB\-o \fIstyle\fR] \fBrun \fIcommand \fR[\fIargument\fR...]
90 \fBsw setup \fIpackage version \fR[\fImaintainer\fR]
91 \fBsw \fR[\fB\-f\fR] [\fB\-a \fIarch\fB,\fIarch\fR...] \fBsnaplink \fIfile \fR[\fIfile\fR...]
100 tool attempts to take a lot of the work out of building and installing
101 source packages across multiple architectures. This section will
104 features to best advantage in a number of common situations.
106 To keep things concrete, I'll describe how things are done at the EBI,
107 although there's nothing EBI-specific about the
109 program itself. For details about how we handle software at EBI, see
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
162 can do, and a suggestion
163 .SS "1. Download the source distribution"
164 Download the package's source distribution. This will normally be in an
165 archive called something like
166 .IB package - version .tar.gz\c
167 \&. At EBI, we put source archive files in
169 .SS "2. Unpack the source tree"
170 Unpack the source tree into the standard source directory. Each source
171 tree should have its own directory. Most well-packaged source
172 distributions unpack themselves into a neat directory, but less
173 fastidious programmers make archives which scatter files all over the
176 At EBI, we put the source trees in
178 so unpacking a well-formed source distribution looks like:
181 .BI "gzip \-dc ../tr/" package \- version ".tar.gz | tar xfv \-"
183 Ill-formed source distributions involve making the directory for the
184 package first, changing into it, and then unpacking into the current
188 .BI "mkdir " package \- version
189 .BI "cd " package \- version
190 .BI "gzip \-dc ../../tr/" package - version ".tar.gz | tar xfv \-"
192 When you've finished unpacking, make sure that your current directory is
193 the top level directory of the source tree you unpacked.
194 .SS "3. Tell sw what you're up to"
197 what you're working on. It will keep track of this and other bits of
198 information in a little file and refer to it every now and then. It
199 will also whinge at you and refuse to cooperate if it can't find its
200 little file, so it's as well to oblige.
204 to create this little file and initialize it with sensible values, you
207 .BI "sw setup " "package version"
209 What could be easier?
210 .SS "4. Restrict the build to particular architectures"
211 Some packages don't work on all architectures, either because the author
212 wasn't sufficiently good at writing portable software, or because the
213 program's doing inherently nonportable things.
215 If that's the case, then
218 to only build on the architectures that really work. Do this with the
220 command. For example, if your package only works on Linux and Solaris,
223 sw only i386-linux sparc-solaris
225 You can get a list of the architecture names that
227 understands by typing
231 With a little bit of luck, these names ought to be self-explanatory.
233 If your package is properly portable and works everywhere then you don't
234 need to do anything for this step. Skip on to the next one.
235 .SS "5. Configure the package"
236 Now it gets complicated. If the package you're building uses
238 to configure itself for its current environment then you're in luck.
241 package because there's a script called
243 in the top source directory, and a file called
253 to configure the package on all the platforms it's meant to be built
254 for. When you've done that, move onto the next step.
260 then all is not lost (although it may be worthwhile complaining at the
261 package's author or maintainers). You need to make a collection of
263 one for each architecture. These link trees are little replicas of the
264 main source tree but with symbolic links instead of the real source
265 files. To make the link trees, run
269 Now, that's not actually quite what you wanted. It's made a link for
271 file in the source tree. Unfortunately, there are some files you'll
272 (probably) have to modify for each architecture in order to configure
273 the package to build properly. You can turn links in the link trees
274 into real independently editable files by
276 the links. Say for example that
280 need to be modified for each architecture. Running the command
282 sw snaplink Makefile config.h
284 is sufficient to do the right thing.
286 Now you must edit the snapped files to configure the package. Make sure
287 that the install directories are correctly set. At EBI, all the
288 software should be configured so that architecture neutral files end up
291 and architecture-specific files end up under
292 .BI /sw/common/arch/ arch\c
294 .SS "6. Build the package"
295 Now you've laid the groundwork, everything ought to be easy. Making the
296 program ought to involve simply typing
300 and waiting for a while. If you had the
302 library available when
304 was built, then your terminal will split itself into little
305 independently scrolling windows showing you the progress for each
306 architecture. If you're not privileged enough to have
308 then you get the output appropriately tagged with architecture names,
309 which is unfortunately fairly hard to read.
310 .SS "7. Install the package"
311 Most source packages (and almost certainly all
317 which installs the program correctly. You can run this from
329 When an architecture completes this step correctly, it's marked as being
330 properly installed, and
332 doesn't bother thinking about it again.
338 makefile target, then you have to install things manually. That's not
339 much fun, so moan at the package's author. When you've finished
340 fiddling with installation, run
346 that you've installed everything OK. (This is a bit of a kludge.)
347 .SS "8. Update the index"
348 Now that everything's built and installed, there's just one more command
355 update its main index of installed packages, telling it which
356 architectures packages are installed on, and who did it.
359 .SH "REFERENCE INTRODUCTION"
360 That was a gentle introduction. This section contains the complete
363 far more detail that you probably want. If that's really the case, try
368 to read the available help text. There's quite a lot of it, and it
369 ought to keep you occupied for a while.
373 command line looks a bit like:
388 gives you an extremely terse usage summary and quits. You have to tell
391 Most of the time you do this by giving
399 so that it knows what to do. There are some strange command line
402 to do more exotic things, though.
405 .SH "IMPLEMENTATION ODDITIES"
408 program that users use is really a small architecture-neutral shell
409 script, which works out the current architecture and executes the
410 appropriate architecture-specific main program. It's done this way so
413 knows that it can use the shell script to start itself up on a remote
414 host with a different architecture, something which it does quite a
415 lot. The only feature provided by the front-end shell script is the
417 command line option, which shouldn't be used by anyone except
419 build procedure anyway.
422 .SH "COMMAND LINE OPTION REFERENCE"
425 command line options can be put in the
427 environment variable. The
429 program will read space-separated options from this variable before it
430 reads the command line itself.
434 program usually understands two different names for each option: a
435 traditional Unix single-character name, and a long GNU-style name. The
436 short options behave in the normal Unix way: you can join them together
437 into single words with a
439 at the front, for example. The long names are always preceded by a
440 double dash. You can abbreviate long names as much as you like, as long
441 as the resulting abbreviation is unambiguous. In the descriptions
442 below, both the short and long names of the options are shown, but for
443 reasons of brevity required arguments are only shown for the long form.
445 There are conceptually two types of
447 command line options: those which, usually for reasons of consistency
448 with other programs, cause
450 to do something immediately; and those which store some settings for
451 particular commands. The latter type are generally more useful. It's
452 worth bearing in mind, though, that the options are only used by a few
453 commands. The command reference describes exactly which commands use
456 The complete list of command line options understood by the current
462 Writes a fairly brief summary of
464 command line options and a usage line for each of
466 commands to standard output, and exits successfully.
468 .B "\-H, \-\-help\-full"
471 command line options and a full paragraph of description for each of
473 commands to standard output, and exits successfully. There's a lot of
474 text generated by this option. I recommend you pipe it through a pager
475 so that you can actually read it.
477 .B "\-v, \-\-version"
480 version number to standard output and exits successfully. This is handy
481 when trying to decide whether your version of
483 has a particular feature, for example.
486 Writes a usage message so terse as to be nearly useless to standard
487 output and exits successfully. This is different from just running
489 because although both print the same useless message, running
491 without any arguments is considered an error, so the message is sent to
494 will exit unsuccessfully.
496 .BI "\-a, \-\-arch " arch , arch\fR...
497 For commands which affect multiple architectures: only affect the
498 architectures specified. The architecture names may be separated by
499 commas, spaces or both, although clearly commas are most convenient on
500 the command line. This option overrides any other decisions that
502 might make about which architectures to process based on the
504 list and the list of correctly built architectures for the current
508 For commands which affect multiple architectures: affect even
509 architectures that have been successfully built. This has no effect if
514 .B "\-i, \-\-install"
515 For build commands: this is the final install step, so label architectures
516 which successfully complete it as having been completely built. It's
517 normal to specify this option on the
518 .RB ` "make install" '
521 .BI "\-o, \-\-output " style
522 For build commands: select a style for the build output to be displayed
525 for more details on output styles.
528 For build commands: make a beep noise when the build finishes. This
529 provides a handy reminder if you're getting on with something else while
530 waiting for a long build.
532 The remaining options aren't really intended for users. They're helpful
535 own purposes, though, and described here for completeness' sake. They
536 don't have standard Unix short name equivalents, because they're not
537 usually useful for users.
542 architecture name of the current host to standard output. This is used
545 configuration script to determine the current architecture name. This
546 option is actually handled by a small shell script rather than by being
547 passed on to the main program. You shouldn't use this option yourself:
550 command instead. Because this option is handled by the shell script,
551 and the script isn't very clever, you can't abbreviate
553 on the command line, and it doesn't conflict with the similarly named
554 but completely different
556 option, which you can still abbreviate all the way down to just
562 idea of its program name to
564 This is intended for use by
566 front-end shell script, but isn't actually needed at the moment. I
567 can't see why you'd want to play with this option, but it shouldn't do
570 .BI "\-\-remote " remote-command
573 when running commands on remote hosts. Don't use this yourself: it puts
575 into a very unfriendly mode and requires that you communicate with it
576 using a bizarre binary packet protocol. If you really must know more
577 about this, see the source code: it's quite well documented, really.
580 .SH "COMMAND REFERENCE"
582 The descriptions below make use of some technical terms:
584 .B "architecture restriction"
585 A state created by the
587 command, restricting the
588 .I "default build architectures"
589 to those listed as arguments to the command. An architecture
590 restriction may be cleared by
594 .B "build architectures"
595 The architectures which a
599 option is specified on the command line, then its argument specifies the
600 build architectures for this command; otherwise, the
601 .I "default build architectures"
605 A command which executes a process on multiple hosts simultaneously and
606 reports the results. The processes executed usually perform some part
607 of the building of a package. Currently, the build commands are
614 .B "default build architectures"
615 The architectures which, in the absence of a
617 command line option, are affected by a
618 .IR "build command" .
619 To determine the default build architectures,
621 reads the list of all architectures from the
623 file, and filters it: if the
625 command line option is
627 specified, then architectures marked as
628 .I "successfully built"
629 are removed from the list; if there is an
630 .I "architecture restriction"
631 in force, then the list is further filtered according to the
634 .B "successfully built"
635 A package is considered to be successfully built on a given architecture
636 if a build command given the
638 command-line option succeeds on a host of that architecture. The list
639 of successfully built architectures can be cleared by the
645 to ignore whether architectures have been successfully built when
647 .IR "default build architectures" .
649 This section describes all of the available
651 commands, in alphabetical order.
655 Clears an architecture restriction set by
657 Subsequent build commands will run across all known architectures not
658 yet successfully built, unless overridden by the
660 command-line option, or a later
665 Writes the name of the local host's architecture to standard output.
666 The architecture name is built into
670 .SS configure \fR[\fIconfigure-arg\fR...]
673 Writes to standard output the name of a host with requested architecture
675 The hostname is read from the
680 Builds symbolic link trees. For each of the build architectures, a
681 directory with the architecture's name is created containing a symbolic
682 link corresponding to each file in the main source tree. Thus, a `make'
683 in the link tree will fetch the source files correctly, but place the
684 objects in the link tree rather than the main source tree, so that
685 object files from different architectures don't interfere with each
688 If the link trees already exist, then rerunning
690 will update the links. This might be useful if the links somehow become
693 To turn some of the links in the link trees into real files, use the
698 Writes a list of all known architecture names to standard output. The
699 list is obtained by reading the
703 .SS make \fR[\fImake-arg\fR...]
705 .SS only-arch \fIarch arch\fR...
707 .SS rsh \fIhost\fR|\fIarch \fR[\fIcommand \fR[\fIargument\fR...]]
709 .SS run \fIcommand \fR[\fIargument\fR...]
711 .SS setup \fIpackage version \fR[\fImaintainer\fR]
713 .SS snaplink \fIfile \fR[\fIfile\fR...]
714 Creates archtitecture-specific versions of a file. For each build
742 is always defined: it simply prefixes each line of output with the
743 name of the architecture which generated the line, which isn't actually
744 particularly easy to read. Other output styles may have been configured
747 when it was compiled.
749 The set of output styles supported by
751 varies according to how it was configured. In any particular
753 program, you might have some of the following:
756 Simply prefixes each output line with the name of the architecture it
757 came from. This is quite hard to read, but it doesn't require any
758 special operating system support or clever terminal.
761 Splits the terminal into independently scrolling areas, one for each
762 architecture, with a status line for each. Waits for a keypress when
763 all architectures are finished building.
767 style is always available. It's used when the selected style doesn't
768 work (for example, you don't have a sufficiently capable terminal for
771 Output style names can be abbreviated as long as the abbreviation is
774 The author has plans to implement an X-based output style, but hasn't
775 got around to it yet.
791 The following environment variables are of interest to
795 Contains a space-separated list of default command-line options. These
796 are read before, and overridden by, the actual arguments given on the
800 The name of the remote-shell program to use. By default, something
803 is chosen. I recommend using the excellent
808 The following files are of interest to
812 The main index file, containing the list of which packages have been
813 installed for which architectures. See
815 for file format details.
817 .IB prefix /share/archtab
818 The architecture-to-host mapping file. See
820 for file format details.
822 .IB prefix /share/sw-env
823 Contains global environment variable settings. See
825 for file format details.
827 .IB package /.sw-info
828 Contains the persistent information about a particular package's build
831 for file format details.
834 Contains package-specific environment variable settings. See
836 for file format details.
838 .IB package / arch /.build-log
839 Contains all the build output for a particular architecture. Usually
840 not very interesting, but might be handy one day.
845 merely unexpected behaviour modes. Silly you for thinking otherwise.
849 program, and this manual, are
851 productions, in association
852 with the European Bioinformatics Instutute. They were written by Mark
853 Wooding <mdw@nsict.org>. Go and ask him if you have problems.
855 .\"----- That's all, folks --------------------------------------------------
~mdw / sw-tools / blob