Internal formatting improvements.
[sw-tools] / sw.1
1 .\" -*-nroff-*-
2 .\"
3 .\" $Id: sw.1,v 1.5 1999/07/16 12:45:37 mdw Exp $
4 .\"
5 .\" Manual page for `sw'
6 .\"
7 .\" (c) 1999 EBI
8 .\"
9 .
10 .\"----- Licensing notice ---------------------------------------------------
11 .\"
12 .\" This file is part of sw-tools.
13 .\"
14 .\" sw-tools is free software; you can redistribute it and/or modify
15 .\" it under the terms of the GNU General Public License as published by
16 .\" the Free Software Foundation; either version 2 of the License, or
17 .\" (at your option) any later version.
18 .\"
19 .\" sw-tools is distributed in the hope that it will be useful,
20 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
21 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
22 .\" GNU General Public License for more details.
23 .\"
24 .\" You should have received a copy of the GNU General Public License
25 .\" along with sw-tools; if not, write to the Free Software Foundation,
26 .\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
27 .
28 .\"----- Revision history ---------------------------------------------------
29 .\"
30 .\" $Log: sw.1,v $
31 .\" Revision 1.5 1999/07/16 12:45:37 mdw
32 .\" Internal formatting improvements.
33 .\"
34 .\" Revision 1.4 1999/06/24 15:52:12 mdw
35 .\" Add documentation for the `sw-precommit' script.
36 .\"
37 .\" Revision 1.3 1999/06/18 18:58:25 mdw
38 .\" Various tidyings.
39 .\"
40 .\" Revision 1.2 1999/06/04 13:56:09 mdw
41 .\" Changes, extensions, polishings, spelling fixes...
42 .\"
43 .\" Revision 1.1.1.1 1999/06/02 16:53:33 mdw
44 .\" Initial import.
45 .\"
46 .
47 .\"----- Style hacking ------------------------------------------------------
48 .
49 .de VS \" Start a sort-of verbatim block
50 .sp 1
51 .in +5n
52 .nf
53 .ft B
54 ..
55 .de VE \" Stop a sort-of verbatim block
56 .ft R
57 .fi
58 .in -5n
59 .sp 1
60 ..
61 .de hP \" Start an indented paragraph with a bold right-aligned label
62 .IP
63 \fB\h'-\w'\\$1\ 'u'\\$1\ \fP\c
64 ..
65 .
66 .ie \n(.g \{\
67 . fam P
68 . ds mw \fR[\f(BImdw\fR]
69 .\}
70 .el .ds mw \fR[\fBmdw\fR]
71 .ie t .ds o \(bu
72 .el .ds o o
73 .ds sw \fBsw\fP
74 .
75 .\"----- Main manual text ---------------------------------------------------
76 .
77 .TH sw 1 "25 May 1999" "EBI tools"
78 .PD 1
79 .
80 .\"--------------------------------------------------------------------------
81 .
82 .SH NAME
83 .
84 sw \- tool for convenient software installation
85 .
86 .\"--------------------------------------------------------------------------
87 .
88 .SH SYNOPSIS
89 .
90 .nf
91 \fBsw \-\-help
92 \fBsw \-\-help-full
93 \fBsw \-\-version
94 \fBsw \-\-archname
95 \fBsw \-\-remote \fIcommand
96
97 \fBsw all\-arch
98 \fBsw arch
99 \fBsw commit
100 \fBsw \fR[\fB\-fbi\fR] [\fB\-a \fIarch\fB,\fIarch\fR...] [\fB\-o \fIstyle\fR] \fBconfigure \fR[\fIconfigure-arg\fR...]
101 \fBsw host \fIarch
102 \fBsw \fR[\fB\-f\fR] [\fB\-a \fIarch\fB,\fIarch\fR...] \fBlinktree
103 \fBsw listarch
104 \fBsw \fR[\fB\-fbi\fR] [\fB\-a \fIarch\fB,\fIarch\fR...] [\fB\-o \fIstyle\fR] \fBmake \fR[\fImake-arg\fR...]
105 \fBsw only\-arch \fIarch \fR[\fIarch\fR...]
106 \fBsw reset
107 \fBsw rsh \fIhost\fR|\fIarch \fR[\fIcommand \fR[\fIargument\fR...]]
108 \fBsw \fR[\fB\-fbi\fR] [\fB\-a \fIarch\fB,\fIarch\fR...] [\fB\-o \fIstyle\fR] \fBrun \fIcommand \fR[\fIargument\fR...]
109 \fBsw setup \fIpackage version \fR[\fImaintainer\fR]
110 \fBsw \fR[\fB\-f\fR] [\fB\-a \fIarch\fB,\fIarch\fR...] \fBsnaplink \fIfile \fR[\fIfile\fR...]
111 \fBsw status
112 .ft R
113 .fi
114 .
115 .\"--------------------------------------------------------------------------
116 .
117 .SH "INTRODUCTION"
118 .
119 The \*(sw tool attempts to take a lot of the work out of building and
120 installing source packages across multiple architectures. This section
121 will describe how to use \*(sw's features to best advantage in a number
122 of common situations.
123 .PP
124 To keep things concrete, I'll describe how things are done at the EBI,
125 although there's nothing EBI-specific about the \*(sw program itself.
126 For details about how we handle software at EBI, see the
127 .B Local quirks
128 section below.
129 .PP
130 By the way, this is quite a large manual. I recommend that you print a
131 copy onto paper and peruse it in a leisurely fashion, rather than
132 squinting at a monitor.
133 .
134 .\"--------------------------------------------------------------------------
135 .
136 .SH "SUMMARY OF BUILDING PACKAGES"
137 .
138 First, the
139 .B Autoconf
140 case:
141 .VS
142 .BI "sw setup " "package version"
143 .B "sw only \c"
144 .IR "arch " [ arch ...]
145 .ft B
146 sw configure
147 sw make
148 sw \-i make install
149 sw commit
150 .VE
151 Secondly, the
152 .RB non- Autoconf
153 case:
154 .VS
155 .BI "sw setup " "package version"
156 .B "sw only \c"
157 .IR "arch " [ arch ...]
158 .B "sw linktree"
159 .BI "sw snaplink \c"
160 .IR "file " [ file ...]
161 .I [edit the appropriate files]
162 .ft B
163 sw make
164 sw \-i make install
165 sw commit
166 .VE
167 .
168 .\"--------------------------------------------------------------------------
169 .
170 .SH "8 STEPS TO INSTALLING A PACKAGE"
171 .
172 The following steps will guide you through your first (and maybe second)
173 package installations. In the description, I'll use
174 .RI ` package '
175 to refer to the package's name, and
176 .RI ` version '
177 to refer to its version number.
178 .PP
179 Not all the important features and options are described in this part of
180 the manual. View it more as a taster for the sorts of things \*(sw can
181 do, and a suggestion
182 .SS "1. Download the source distribution"
183 Download the package's source distribution. This will normally be in an
184 archive called something like
185 .IB package - version .tar.gz\c
186 \&. At EBI, we put source archive files in
187 .BR /sw/common/tr .
188 .SS "2. Unpack the source tree"
189 Unpack the source tree into the standard source directory. Each source
190 tree should have its own directory. Most well-packaged source
191 distributions unpack themselves into a neat directory, but less
192 fastidious programmers make archives which scatter files all over the
193 current directory.
194 .PP
195 At EBI, we put the source trees in
196 .BR /sw/common/src ,
197 so unpacking a well-formed source distribution looks like:
198 .VS
199 cd /sw/common/src
200 .BI "gzip \-dc ../tr/" package \- version ".tar.gz | tar xfv \-"
201 .VE
202 Ill-formed source distributions involve making the directory for the
203 package first, changing into it, and then unpacking into the current
204 directory:
205 .VS
206 cd /sw/common/src
207 .BI "mkdir " package \- version
208 .BI "cd " package \- version
209 .BI "gzip \-dc ../../tr/" package - version ".tar.gz | tar xfv \-"
210 .VE
211 When you've finished unpacking, make sure that your current directory is
212 the top level directory of the source tree you unpacked.
213 .SS "3. Tell \\*(sw what you're up to"
214 Now you need to tell \*(sw what you're working on. It will keep track of
215 this and other bits of information in a little file and refer to it
216 every now and then. It will also whinge at you and refuse to cooperate
217 if it can't find its little file, so it's as well to oblige.
218 .PP
219 To tell \*(sw to create this little file and initialize it with sensible
220 values, you just need to say
221 .VS
222 .BI "sw setup " "package version"
223 .VE
224 What could be easier?
225 .SS "4. Restrict the build to particular architectures"
226 Some packages don't work on all architectures, either because the author
227 wasn't sufficiently good at writing portable software, or because the
228 program's doing inherently nonportable things.
229 .PP
230 If that's the case, then you need to tell \*(sw to only build on the
231 architectures that really work. Do this with the
232 .RB ` "sw only" '
233 command. For example, if your package only works on Linux and Solaris,
234 say:
235 .VS
236 sw only i386-linux sparc-solaris
237 .VE
238 You can get a list of the architecture names that \*(sw understands by
239 typing
240 .VS
241 sw listarch
242 .VE
243 With a little bit of luck, these names ought to be self-explanatory.
244 .PP
245 If your package is properly portable and works everywhere then you don't
246 need to do anything for this step. Skip on to the next one.
247 .SS "5. Configure the package"
248 Now it gets complicated. If the package you're building uses
249 .B Autoconf
250 to configure itself for its current environment then you're in luck.
251 You can tell an
252 .B Autoconf
253 package because there's a script called
254 .B configure
255 in the top source directory, and a file called
256 .BR Makefile.in .
257 If it
258 .I does
259 use
260 .B Autoconf
261 then run
262 .VS
263 sw configure
264 .VE
265 to configure the package on all the platforms it's meant to be built
266 for. When you've done that, move onto the next step.
267 .PP
268 If the package
269 .I doesn't
270 use
271 .B Autoconf
272 then all is not lost (although it may be worthwhile complaining at the
273 package's author or maintainers). You need to make a collection of
274 .IR "link trees" ,
275 one for each architecture. These link trees are little replicas of the
276 main source tree but with symbolic links instead of the real source
277 files. To make the link trees, run
278 .VS
279 sw linktree
280 .VE
281 Now, that's not actually quite what you wanted. It's made a link for
282 .I every
283 file in the source tree. Unfortunately, there are some files you'll
284 (probably) have to modify for each architecture in order to configure
285 the package to build properly. You can turn links in the link trees
286 into real independently editable files by
287 .I snapping
288 the links. Say for example that
289 .B Makefile
290 and
291 .B config.h
292 need to be modified for each architecture. Running the command
293 .VS
294 sw snaplink Makefile config.h
295 .VE
296 is sufficient to do the right thing.
297 .PP
298 Now you must edit the snapped files to configure the package. Make sure
299 that the install directories are correctly set. At EBI, all the
300 software should be configured so that architecture neutral files end up
301 under
302 .B /sw/common
303 and architecture-specific files end up under
304 .BI /sw/common/arch/ arch\c
305 \&.
306 .SS "6. Build the package"
307 Now you've laid the groundwork, everything ought to be easy. Making the
308 program ought to involve simply typing
309 .VS
310 sw make
311 .VE
312 and waiting for a while. If you had the
313 .B curses
314 library available when \*(sw was built, then your terminal will split
315 itself into little independently scrolling windows showing you the
316 progress for each architecture. If you're not privileged enough to have
317 .B curses
318 then you get the output appropriately tagged with architecture names,
319 which is unfortunately fairly hard to read.
320 .SS "7. Install the package"
321 Most source packages (and almost certainly all
322 .B Autoconf
323 ones) have a
324 .B make
325 target
326 .RB ` install '
327 which installs the program correctly. You can run this from \*(sw by
328 saying
329 .VS
330 sw \-i make install
331 .VE
332 The little
333 .RB ` \-i '
334 option there tells \*(sw that this is the
335 .IR "install step" .
336 When an architecture completes this step correctly, it's marked as being
337 properly installed, and \*(sw doesn't bother thinking about it again.
338 .PP
339 If you
340 .I don't
341 have an
342 .RB ` install '
343 makefile target, then you have to install things manually. That's not
344 much fun, so moan at the package's author. When you've finished
345 fiddling with installation, run
346 .VS
347 sw -i run true
348 .VE
349 just to tell \*(sw that you've installed everything OK. (This is a bit
350 of a kludge.)
351 .SS "8. Update the index"
352 Now that everything's built and installed, there's just one more command
353 to type:
354 .VS
355 sw commit
356 .VE
357 This makes \*(sw update its main index of installed packages, telling it
358 which architectures packages are installed on, and who did it.
359 .
360 .\"--------------------------------------------------------------------------
361 .
362 .SH "REFERENCE INTRODUCTION"
363 .
364 That was a gentle introduction. This section contains the complete
365 reference to
366 .BR sw :
367 far more detail that you probably want. If that's really the case, try
368 running
369 .VS
370 sw \-\-help\-full
371 .VE
372 to read the available help text. There's quite a lot of it, and it
373 ought to keep you occupied for a while.
374 .PP
375 The basic \*(sw command line looks a bit like:
376 .sp 1
377 .RS 5
378 .B sw
379 .RI [ options ]
380 .RI [ command
381 .RI [ argument ...]]
382 .RE
383 .sp 1
384 If you just say
385 .VS
386 sw
387 .VE
388 at the shell prompt, \*(sw gives you an extremely terse usage summary
389 and quits. You have to tell it to do
390 .IR something .
391 Most of the time you do this by giving \*(sw a
392 .IR command ,
393 like
394 .RB ` setup '
395 or
396 .RB ` make '
397 so that it knows what to do. There are some strange command line
398 options which cause \*(sw to do more exotic things, though.
399 .
400 .\"--------------------------------------------------------------------------
401 .
402 .SH "IMPLEMENTATION ODDITIES"
403 .
404 The \*(sw program that users use is really a small architecture-neutral
405 shell script, which works out the current architecture and executes the
406 appropriate architecture-specific main program. It's done this way so
407 that \*(sw knows that it can use the shell script to start itself up on
408 a remote host with a different architecture, something which it does
409 quite a lot. The only feature provided by the front-end shell script is
410 the
411 .B \-\-archname
412 command line option, which shouldn't be used by anyone except \*(sw's build procedure anyway.
413 .
414 .\"--------------------------------------------------------------------------
415 .
416 .SH "COMMAND LINE OPTION REFERENCE"
417 .
418 Any \*(sw command line options can be put in the
419 .B SW
420 environment variable. The \*(sw program will read space-separated
421 options from this variable before it reads the command line itself.
422 .PP
423 The \*(sw program usually understands two different names for each
424 option: a traditional Unix single-character name, and a long GNU-style
425 name. The short options behave in the normal Unix way: you can join
426 them together into single words with a
427 .RB ` \- '
428 at the front, for example. The long names are always preceded by a
429 double dash. You can abbreviate long names as much as you like, as long
430 as the resulting abbreviation is unambiguous. In the descriptions
431 below, both the short and long names of the options are shown, but for
432 reasons of brevity required arguments are only shown for the long form.
433 .PP
434 There are conceptually two types of \*(sw command line options: those
435 which, usually for reasons of consistency with other programs, cause
436 \*(sw to do something immediately; and those which store some settings
437 for particular commands. The latter type are generally more useful.
438 It's worth bearing in mind, though, that the options are only used by a
439 few commands. The command reference describes exactly which commands
440 use which options.
441 .PP
442 The complete list of command line options understood by the current
443 version of \*(sw is as follows:
444 .TP
445 .B "\-h, \-\-help"
446 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.
447 .TP
448 .B "\-H, \-\-help\-full"
449 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
450 text generated by this option. I recommend you pipe it through a pager
451 so that you can actually read it.
452 .TP
453 .B "\-v, \-\-version"
454 Writes \*(sw's version number to standard output and exits successfully. This is handy
455 when trying to decide whether your version of \*(sw has a particular feature, for example.
456 .TP
457 .B "\-u, \-\-usage"
458 Writes a usage message so terse as to be nearly useless to standard
459 output and exits successfully. This is different from just running
460 .RB ` sw '
461 because although both print the same useless message, running \*(sw without any arguments is considered an error, so the message is sent to
462 standard error and \*(sw will exit unsuccessfully.
463 .TP
464 .BI "\-a, \-\-arch " arch , arch\fR...
465 For commands which affect multiple architectures: only affect the
466 architectures specified. The architecture names may be separated by
467 commas, spaces or both, although clearly commas are most convenient on
468 the command line. Architecture names may be abbreviated as long as the
469 abbreviation is not ambiguous.
470 .IP
471 This option overrides any other decisions that \*(sw might make about which architectures to process based on the
472 .B only\-arch
473 list and the list of correctly built architectures for the current
474 package.
475 .TP
476 .B "\-f, \-\-force"
477 For commands which affect multiple architectures: affect even
478 architectures that have been successfully built. This has no effect if
479 there's a
480 .RB ` \-a '
481 option in force.
482 .TP
483 .B "\-i, \-\-install"
484 For build commands: this is the final install step, so label architectures
485 which successfully complete it as having been completely built. It's
486 normal to specify this option on the
487 .RB ` "make install" '
488 build command.
489 .TP
490 .BI "\-o, \-\-output " style
491 For build commands: select a style for the build output to be displayed
492 in. See the section
493 .B "Build commands"
494 for more details on output styles.
495 .TP
496 .B "\-b, \-\-beep"
497 For build commands: make a beep noise when the build finishes. This
498 provides a handy reminder if you're getting on with something else while
499 waiting for a long build.
500 .PP
501 The remaining options aren't really intended for users. They're helpful
502 for \*(sw's own purposes, though, and described here for completeness' sake. They
503 don't have standard Unix short name equivalents, because they're not
504 usually useful for users.
505 .TP
506 .B "\-\-archname"
507 Writes the \*(sw architecture name of the current host to standard output. This is used
508 by \*(sw's configuration script to determine the current architecture name. This
509 option is actually handled by a small shell script rather than by being
510 passed on to the main program. You shouldn't use this option yourself:
511 use the
512 .RB ` arch '
513 command instead. Because this option is handled by the shell script,
514 and the script isn't very clever, you can't abbreviate
515 .B \-\-archname
516 on the command line, and it doesn't conflict with the similarly named
517 but completely different
518 .B \-\-arch
519 option, which you can still abbreviate all the way down to just
520 .RB ` \-\-a '.
521 .TP
522 .BI "\-\-me " name
523 Sets \*(sw's idea of its program name to
524 .IR name .
525 This is intended for use by \*(sw's front-end shell script, but isn't
526 actually needed at the moment. I can't see why you'd want to play with
527 this option, but it shouldn't do any harm.
528 .TP
529 .BI "\-\-remote " remote-command
530 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
531 using a bizarre binary packet protocol. If you really must know more
532 about this, see the source code: it's quite well documented, really.
533 .
534 .\"--------------------------------------------------------------------------
535 .
536 .SH TERMINOLOGY
537 .
538 The descriptions below make use of some technical terms:
539 .TP
540 .B "architecture restriction"
541 A state created by the
542 .B only\-arch
543 command, restricting the
544 .I "default build architectures"
545 to those listed as arguments to the command. An architecture
546 restriction may be cleared by
547 .B all\-arch
548 command.
549 .TP
550 .B "build architectures"
551 The architectures which a
552 .I "build command"
553 will process. If the
554 .RB ` \-a '
555 option is specified on the command line, then its argument specifies the
556 build architectures for this command; otherwise, the
557 .I "default build architectures"
558 are used.
559 .TP
560 .B "build command"
561 A command which executes a process on multiple hosts simultaneously and
562 reports the results. The processes executed usually perform some part
563 of the building of a package. Currently, the build commands are
564 .B run
565 and its derivatives
566 .B configure
567 and
568 .BR make .
569 .TP
570 .B "default build architectures"
571 The architectures which, in the absence of a
572 .RB ` \-a '
573 command line option, are affected by a
574 .IR "build command" .
575 To determine the default build architectures, \*(sw reads the list of all architectures from the
576 .B archtab
577 file, and filters it: if the
578 .RB ` \-f '
579 command line option is
580 .I not
581 specified, then architectures marked as
582 .I "successfully built"
583 are removed from the list; if there is an
584 .I "architecture restriction"
585 in force, then the list is further filtered according to the
586 restriction.
587 .TP
588 .B "successfully built"
589 A package is considered to be successfully built on a given architecture
590 if a build command given the
591 .RB ` \-i '
592 command-line option succeeds on a host of that architecture. The list
593 of successfully built architectures can be cleared by the
594 .B reset
595 command. The
596 .RB ` \-f '
597 option causes \*(sw to ignore whether architectures have been successfully built when
598 determining the
599 .IR "default build architectures" .
600 .
601 .\"--------------------------------------------------------------------------
602 .
603 .SH "COMMAND REFERENCE"
604 .
605 This section describes all of the available \*(sw commands, in alphabetical order.
606 .
607 .SS all\-arch
608 Clears an architecture restriction set by
609 .RB ` only\-arch '.
610 Subsequent build commands will run across all known architectures not
611 yet successfully built, unless overridden by the
612 .RB ` \-a '
613 command-line option, or a later
614 .RB ` only\-arch '
615 command.
616 .
617 .SS arch
618 Writes the name of the local host's architecture to standard output.
619 The architecture name is built into \*(sw at compile time.
620 .SS commit
621 Writes information from the
622 .B .sw\-info
623 file to the installed packages index file
624 .IB prefix /sw-index\fR.
625 .PP
626 \*(sw performs some checks before committing information to the index
627 file. Firstly, all the expected architectures must be successfully
628 built. Secondly, the script
629 .IB prefix /share/sw-precommit\fR
630 is run, if it exists. This script must exit successfully if the commit
631 is to proceed. The script can be configured to enforce local policy
632 requirements on installed software.
633 .PP
634 The
635 .B sw-precommit
636 script is passed a single argument, which is the package name to be
637 committed. Other useful information is passed in the environment:
638 .TP
639 .B SW_PACKAGE
640 The package name (again).
641 .TP
642 .B SW_VERSION
643 The package version number.
644 .TP
645 .B SW_MAINTAINER
646 The package's maintainer.
647 .TP
648 .B SW_DATE
649 The last date on whicy the package was modified.
650 .TP
651 .B SW_ARCHLIST
652 The list of architectures on which the package has been built (separated
653 by spaces or commas).
654 .TP
655 .B SW_PREFIX
656 The installation prefix with which \*(sw was configured.
657 .PP
658 The script should report any errors it finds to its standard error
659 stream.
660 .
661 .SS configure \fR[\fIconfigure-arg\fR...]
662 Equivalent to the command
663 .VS
664 .BI "run ../configure \-\-prefix=" prefix " " configure-arg\fR...
665 .VE
666 where
667 .I prefix
668 is the installation prefix with which \*(sw itself was configured. If you want to specify a different prefix, pass
669 your own
670 .B \-\-prefix
671 argument.
672 .PP
673 It is expected that administrators will set up a file
674 .IB prefix /share/config.site
675 which sets up other Autoconf parameters once the prefix has been
676 chosen. See the Autoconf manual for more information.
677 .
678 .SS host \fIarch\fR
679 Writes to standard output the name of a host with requested architecture
680 .IR arch .
681 The hostname is read from the
682 .B archtab
683 file.
684 .
685 .SS linktree
686 Builds symbolic link trees. For each of the build architectures, a
687 directory with the architecture's name is created containing a symbolic
688 link corresponding to each file in the main source tree. Thus, a `make'
689 in the link tree will fetch the source files correctly, but place the
690 objects in the link tree rather than the main source tree, so that
691 object files from different architectures don't interfere with each
692 other.
693 .PP
694 If the link trees already exist, then rerunning
695 .B linktree
696 will update the links. This might be useful if the links somehow become
697 invalid.
698 .PP
699 To turn some of the links in the link trees into real files, use the
700 .B snaplink
701 command.
702 .
703 .SS listarch
704 Writes a list of all known architecture names to standard output. The
705 list is obtained by reading the
706 .B archtab
707 file.
708 .
709 .SS make \fR[\fImake-arg\fR...]
710 Equivalent to
711 .VS
712 .BI "run make " make-arg\fR...
713 .VE
714 in all respects.
715 .
716 .SS only\-arch \fIarch arch\fR...
717 Imposes an architecture restriction. Until cancelled by a later
718 .B only\-arch
719 or
720 .B all\-arch
721 command, the default build architectures will be limited to the
722 architectures listed on the command line. Architecture names may be
723 abbreviated as long as the abbreviation is not ambiguous.
724 .
725 .SS reset
726 Clears the
727 .I "successfully built"
728 status of all architectures.
729 .
730 .SS rsh \fIhost\fR|\fIarch \fR[\fIcommand \fR[\fIargument\fR...]]
731 Runs
732 .I command
733 on a remote host, passing it the list of
734 .IR argument s.
735 The
736 .B "sw rsh"
737 command is unlike the standard
738 .B rsh
739 program and its replacements:
740 .hP \*o
741 The
742 .I command
743 and
744 .IR argument s
745 are not subjected to further shell expansion on the remote host.
746 .hP \*o
747 The command is run with the remote current directory the same as the
748 local current directory, rather than the remote user's home directory.
749 .hP \*o
750 The command is passed an environment constructed from the local
751 environment, the default remote environment, and
752 .B sw\-env
753 files, as described in the section
754 .B "Remote environment"
755 below.
756 .hP \*o
757 The remote command is run with standard input attached to
758 .BR /dev/null :
759 there is no way of running an interactive remote command through
760 .BR sw.
761 .PP
762 The host on which to run the remote command may be specified as one of:
763 a standard host name (or IP address), an architecture name (which may
764 .I not
765 be abbreviated) signifying a host of the appropriate architecture, or
766 the special name
767 .RB ` \- '
768 signifying the current host. (This last option may not sound useful,
769 but it's handy for testing.)
770 .
771 .SS run \fIcommand \fR[\fIargument\fR...]
772 Runs a command on all build architectures.
773 .PP
774 For each build architecture
775 .IR arch ,
776 \*(sw finds a host with the appropriate architecture, by choosing either
777 the local host or reading the hostname from the
778 .B archtab
779 file. It then performs the following actions on that host:
780 .hP 1.
781 Sets the current directory to be the subdirectory named
782 .I arch
783 of the directory from which the command was issued. This directory is
784 created if it doesn't already exist.
785 .hP 2.
786 Sets up an environment constructed from the environment prevailing when
787 the command was issued, the default environment set up by
788 .B rsh
789 (or whatever equivalent remote execution program was actually used), and
790 the
791 .B sw\-env
792 files, as described in the section
793 .B "Remote environment"
794 below.
795 .hP 3.
796 Executes the program named
797 .I command
798 passing it the given
799 .IR argument s.
800 .PP
801 Output from the command is both appended to the file
802 .IB arch/.build-log
803 and output in some
804 .IR "output style" ,
805 as specified by the
806 .RB ` \-o '
807 command-line option. See the section
808 .B "Output styles"
809 below for more details.
810 .PP
811 If the
812 .RB ` \-i '
813 option was given on the command line, each architecture on which the
814 command succeeds (i.e., reports a zero exit code) is marked as
815 .IR "successfully built" ,
816 and further build commands will not affect it unless the
817 .RB ` \-f '
818 command line option is passed, until a
819 .B reset
820 command is performed.
821 .
822 .SS setup \fIpackage version \fR[\fImaintainer\fR]
823 Sets up various pieces of information required by \*(sw. The
824 information here will be added into the main index file by a
825 .B commit
826 command. The information is maintained in a file named
827 .B .sw\-info
828 in the current directory.
829 .PP
830 The
831 .I package
832 should be the basic name of the package, with versioning information
833 stripped off, e.g.,
834 .RB ` emacs '
835 or
836 .RB ` perl ',
837 not
838 .RB ` emacs\-19.34 '.
839 The
840 .I version
841 should be the version number of the package. The
842 .I maintainer
843 should be the name of the person principally responsible for maintaining
844 the package's local installation. If this isn't specified, the calling
845 user's name is used as the maintainer.
846 .PP
847 The
848 .B setup
849 command must be run before any build command.
850 .
851 .SS snaplink \fIfile \fR[\fIfile\fR...]
852 Creates architecture-specific versions of a file. Every
853 .I file
854 named on the command line is copied to
855 .IB arch / file
856 for every build architecture
857 .IR arch ,
858 overwriting any existing file or symbolic link of that name. If
859 .I file
860 contains leading directories then destination directories are created as
861 necessary for the output files. Note that the `snap' operation doesn't
862 actually need to follow creation of link trees.
863 .
864 .\"--------------------------------------------------------------------------
865 .
866 .SH "OUTPUT STYLES"
867 .
868 Output from a build command is presented in one of a number of named
869 .IR "output styles" .
870 The style name
871 .RB ` plain '
872 is always defined: it simply prefixes each line of output with the
873 name of the architecture which generated the line, which isn't actually
874 particularly easy to read. Other output styles may have been configured
875 into \*(sw when it was compiled.
876 .PP
877 The set of output styles supported by \*(sw varies according to how it
878 was configured. In any particular \*(sw program, you might have some of
879 the following:
880 .TP
881 .B plain
882 Simply prefixes each output line with the name of the architecture it
883 came from. This is quite hard to read, but it doesn't require any
884 special operating system support or clever terminal.
885 .TP
886 .B curses
887 Splits the terminal into independently scrolling areas, one for each
888 architecture, with a status line for each. Waits for a keypress when
889 all architectures are finished building.
890 .PP
891 The
892 .RB ` plain '
893 style is used when the selected style doesn't work (for example, you
894 don't have a sufficiently capable terminal for curses output).
895 .PP
896 Output style names can be abbreviated as long as the abbreviation is
897 unambiguous. You can find the list of available output styles by
898 executing the command
899 .VS
900 sw \-o help run
901 .VE
902 (which is a little counter-intuitive, I know).
903 .PP
904 The author has plans to implement an X-based output style, but hasn't
905 got around to it yet.
906 .
907 .\"--------------------------------------------------------------------------
908 .
909 .SH "REMOTE ENVIRONMENT"
910 .
911 The environment for a remote command (executed either through the
912 .B rsh
913 command, or a build command) is set up as follows:
914 .hP \*o
915 The complete environment passed to \*(sw is used as a basis.
916 .hP \*o
917 Any environment variables defined by the remote execution program
918 (usually
919 .BR rsh )
920 override corresponding variables in the basis environment.
921 .hP \*o
922 The
923 .B SW_ARCH
924 variable is set to the name of the remote host's architecture.
925 .hP \*o
926 Variable assignments are read from the global
927 .IB prefix /share/sw\-env
928 file. This makes some assignments which are useful everywhere, and will
929 then usually include the file
930 .B .sw\-env
931 in the current directory.
932 .PP
933 The format of the
934 .B sw\-env
935 files is documented separately in
936 .BR sw\-env (5).
937 .
938 .\"--------------------------------------------------------------------------
939 .
940 .SH LOCAL QUIRKS
941 .
942 This section describes how non-vendor software works at EBI. Chances
943 are that other sites will work differently. This description is here as
944 an example setup for \*(sw.
945 .PP
946 All the non-vendor software gets put in one big shared filesystem, and
947 is exported from our main fileserver. The filesystem is mounted on all
948 clients as
949 .BR /sw/common .
950 Architecture-neutral files are then
951 placed in the conventional subdirectories off
952 .B /sw/common
953 (e.g.,
954 .BR /sw/common/share,
955 or
956 .BR /sw/common/info ).
957 Architecture specific files are stored in subdirectories off
958 .BR /sw/common/arch .
959 For example, Linux binaries go in
960 .BR /sw/common/arch/i386-linux/bin ,
961 and Solaris libraries in
962 .BR /sw/common/arch/sparc-solaris/lib .
963 Additionally, each architecture-specific subtree has a symbolic link
964 back up to
965 .B /sw/common
966 for each of the architecture-neutral subdirectories.
967 .PP
968 There is a symbolic link on every client, from
969 .B /sw/arch
970 to
971 .BI /sw/common/arch/ arch\fR,
972 where
973 .I arch
974 is the architecture of that client. Thus, every client has two
975 .I views
976 of the software repository: the `common' view where every host sees
977 exactly the same mapping between filenames and files, and the `arch'
978 view where every host sees the same mapping between filenames and
979 programs which do the same job.
980 .PP
981 And that's just about it.
982 .
983 .\"--------------------------------------------------------------------------
984 .
985 .SH ENVIRONMENT
986 .
987 The following environment variables are of interest to
988 .BR sw :
989 .TP
990 .B SW
991 Contains a space-separated list of default command-line options. These
992 are read before, and overridden by, the actual arguments given on the
993 command-line.
994 .TP
995 .B SW_MAKE
996 The name of the command to use to run a `make'. This is resolved on the
997 local host once, rather than one for each build host, which is probably
998 a misfeature. To do something more clever, point
999 .B SW_MAKE
1000 at a shell script which then picks out the right architecture-specific
1001 .RB ` make '
1002 program from the remote environment.
1003 .TP
1004 .B SW_RSH
1005 The name of the remote-shell program to use. By default, something
1006 similar to
1007 .B rsh
1008 is chosen. I recommend using the excellent
1009 .B ssh
1010 program instead.
1011 .
1012 .\"--------------------------------------------------------------------------
1013 .
1014 .SH FILES
1015 .
1016 The following files are of interest to
1017 .BR sw :
1018 .TP
1019 .IB prefix /sw\-index
1020 The main index file, containing the list of which packages have been
1021 installed for which architectures. See
1022 .BR sw-info (5)
1023 for file format details.
1024 .TP
1025 .IB prefix /share/archtab
1026 The architecture-to-host mapping file. See
1027 .BR archtab (5)
1028 for file format details.
1029 .TP
1030 .IB prefix /share/sw\-env
1031 Contains global environment variable settings. See
1032 .BR sw-env (5)
1033 for file format details.
1034 .TP
1035 .IB prefix /share/sw\-precommit
1036 Optional script used to approve commit requests. See the
1037 .B commit
1038 command above for calling details.
1039 .BR sw-env (5)
1040 for file format details.
1041 .TP
1042 .IB package /.sw\-info
1043 Contains the persistent information about a particular package's build
1044 status. See
1045 .BR sw-info (5)
1046 for file format details.
1047 .TP
1048 .IB package /.sw\-env
1049 Contains package-specific environment variable settings. See
1050 .BR sw-env (5)
1051 for file format details.
1052 .TP
1053 .IB package / arch /.build\-log
1054 Contains all the build output for a particular architecture. Usually
1055 not very interesting, but might be handy one day.
1056 .
1057 .\"--------------------------------------------------------------------------
1058 .
1059 .SH BUGS
1060 .
1061 There are no bugs in
1062 .BR sw ,
1063 merely unexpected behaviour modes. Silly you for thinking otherwise.
1064 .
1065 .SH AUTHOR
1066 .
1067 The \*(sw program, and this manual, are \*(mw productions, in association
1068 with the European Bioinformatics Institute. They were written by Mark
1069 Wooding <mdw@nsict.org>. Go and ask him if you have problems.
1070 .
1071 .\"----- That's all, folks --------------------------------------------------