| 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 -------------------------------------------------- |