stow.8

   1 .TH STOW 8 "28 March 1998"
   2 .SH NAME
   3 stow \- software package installation manager
   4 .SH SYNOPSIS
   5 .B stow
   6 .RI [ options ]
   7 .IR package ...
   8 .SH DESCRIPTION
   9 This manual page describes GNU Stow 1.3.3, a program for managing the
  10 installation of software packages. This is not the definitive
  11 documentation for stow; for that, see the info manual.
  12 .PP
  13 Stow is a tool for managing the installation of multiple software
  14 packages in the same run-time directory tree. One historical difficulty
  15 of this task has been the need to administer, upgrade, install, and
  16 remove files in independent packages without confusing them with other
  17 files sharing the same filesystem space. For instance, it is common to
  18 install Perl and Emacs in
  19 .IR /usr/local .
  20 When one does so, one winds up
  21 (as of Perl 4.036 and Emacs 19.22)
  22 with the following files in
  23 .IR /usr/local/man/man1 :
  24 .IR a2p.1 ;
  25 .IR ctags.1 ;
  26 .IR emacs.1 ;
  27 .IR etags.1 ;
  28 .IR h2ph.1 ;
  29 .IR perl.1 ;
  30 and
  31 .IR s2p.1 .
  32 Now
  33 suppose it's time to uninstall Perl. Which man pages get removed?
  34 Obviously
  35 .I perl.1
  36 is one of them, but it should not be the
  37 administrator's responsibility to memorize the ownership of individual
  38 files by separate packages.
  39 .PP
  40 The approach used by Stow is to install each package into its own
  41 tree, then use symbolic links to make it appear as though the files are
  42 installed in the common tree. Administration can be performed in the
  43 package's private tree in isolation from clutter from other packages.
  44 Stow can then be used to update the symbolic links. The structure of
  45 each private tree should reflect the desired structure in the common
  46 tree; i.e. (in the typical case) there should be a
  47 .I bin
  48 directory
  49 containing executables, a
  50 .I man/man1
  51 directory containing section 1 man
  52 pages, and so on.
  53 .PP
  54 Stow was inspired by Carnegie Mellon's Depot program, but is
  55 substantially simpler and safer. Whereas Depot required database files
  56 to keep things in sync, Stow stores no extra state between runs, so
  57 there's no danger (as there was in Depot) of mangling directories when
  58 file hierarchies don't match the database. Also unlike Depot, Stow will
  59 never delete any files, directories, or links that appear in a Stow
  60 directory (e.g.,
  61 .IR /usr/local/stow/emacs ),
  62 so it's always possible to
  63 rebuild the target tree (e.g.,
  64 .IR /usr/local ).
  65 .SH TERMINOLOGY
  66 A ``package'' is a related collection of files and directories that
  67 you wish to administer as a unit--e.g., Perl or Emacs--and that needs
  68 to be installed in a particular directory structure--e.g., with
  69 .IR bin ,
  70 .IR lib ,
  71 and
  72 .I man
  73 subdirectories.
  74 .PP
  75 A ``target directory'' is the root of a tree in which one or more
  76 packages wish to
  77 .B appear
  78 to be installed. A common, but by no means
  79 the only such location is
  80 .IR /usr/local .
  81 The examples in this manual page
  82 will use
  83 .I /usr/local
  84 as the target directory.
  85 .PP
  86 A ``stow directory'' is the root of a tree containing separate
  87 packages in private subtrees. When Stow runs, it uses the current
  88 directory as the default stow directory. The examples in this manual
  89 page will use
  90 .I /usr/local/stow
  91 as the stow directory, so that individual
  92 packages will be, for example,
  93 .I /usr/local/stow/perl
  94 and
  95 .IR /usr/local/stow/emacs .
  96 .PP
  97 An ``installation image'' is the layout of files and directories
  98 required by a package, relative to the target directory. Thus, the
  99 installation image for Perl includes: a
 100 .I bin
 101 directory containing
 102 .I perl
 103 and
 104 .I a2p
 105 (among others); an
 106 .I info
 107 directory containing Texinfo
 108 documentation; a
 109 .I lib/perl
 110 directory containing Perl libraries; and a
 111 .I man/man1
 112 directory containing man pages.
 113 .PP
 114 A ``package directory'' is the root of a tree containing the
 115 installation image for a particular package. Each package directory
 116 must reside in a stow directory--e.g., the package directory
 117 .I /usr/local/stow/perl
 118 must reside in the stow directory
 119 .IR /usr/local/stow .
 120 The ``name'' of a package is the name of its
 121 directory within the stow directory--e.g.,
 122 .IR perl .
 123 .PP
 124 Thus, the Perl executable might reside in
 125 .IR /usr/local/stow/perl/bin/perl ,
 126 where
 127 .I /usr/local
 128 is the target
 129 directory,
 130 .I /usr/local/stow
 131 is the stow directory,
 132 .I /usr/local/stow/perl
 133 is the package directory, and
 134 .I bin/perl
 135 within
 136 is part of the installation image.
 137 .PP
 138 A ``symlink'' is a symbolic link. A symlink can be ``relative'' or
 139 ``absolute''. An absolute symlink names a full path; that is, one
 140 starting from
 141 .IR / .
 142 A relative symlink names a relative path; that is,
 143 one not starting from
 144 .IR / .
 145 The target of a relative symlink is
 146 computed starting from the symlink's own directory. Stow only creates
 147 relative symlinks.
 148 .SH OPTIONS
 149 The stow directory is assumed to be the current directory, and the
 150 target directory is assumed to be the parent of the current directory
 151 (so it is typical to execute
 152 .I stow
 153 from the directory
 154 .IR /usr/local/stow ).
 155 Each
 156 .I package
 157 given on the command line is the name of a package in the stow
 158 directory (e.g.,
 159 .IR perl ).
 160 By default, they are installed into the
 161 target directory (but they can be deleted instead using `-D').
 162 .TP
 163 .I -n
 164 .TP
 165 .I --no
 166 Do not perform any operations that modify the filesystem; merely
 167 show what would happen. Since no actual operations are performed,
 168 .I stow -n
 169 could report conflicts when none would actually take
 170 place (see ``Conflicts'' in the info manual);
 171 but it won't fail to report conflicts
 172 that
 173 .B would
 174 take place.
 175 .TP
 176 .I -c
 177 .TP
 178 .I --conflicts
 179 Do not exit immediately when a conflict is encountered. This
 180 option implies `-n', and is used to search for all conflicts that
 181 might arise from an actual Stow operation. As with `-n', however,
 182 false conflicts might be reported (see ``Conflicts'' in the info manual).
 183 .TP
 184 .I "-d DIR"
 185 .TP
 186 .I --dir=DIR
 187 Set the stow directory to DIR instead of the current directory.
 188 This also has the effect of making the default target directory be
 189 the parent of DIR.
 190 .TP
 191 .I "-t DIR"
 192 .TP
 193 .I --target=DIR
 194 Set the target directory to DIR instead of the parent of the stow
 195 directory.
 196 .TP
 197 .I -v
 198 .TP
 199 .I --verbose[=N]
 200 Send verbose output to standard error describing what Stow is
 201 doing. Verbosity levels are 0, 1, 2, and 3; 0 is the default.
 202 Using `-v' or `--verbose' increases the verbosity by one; using
 203 `--verbose=N' sets it to N.
 204 .TP
 205 .I -D
 206 .TP
 207 .I --delete
 208 Delete packages from the target directory rather than installing
 209 them.
 210 .TP
 211 .I -R
 212 .TP
 213 .I --restow
 214 Restow packages (first unstow, then stow again). This is useful
 215 for pruning obsolete symlinks from the target tree after updating
 216 the software in a package.
 217 .TP
 218 .I -V
 219 .TP
 220 .I --version
 221 Show Stow version number, and exit.
 222 .TP
 223 .I -h
 224 .TP
 225 .I --help
 226 Show Stow command syntax, and exit.
 227 .SH "INSTALLING PACKAGES"
 228 The default action of Stow is to install a package. This means
 229 creating symlinks in the target tree that point into the package tree.
 230 Stow attempts to do this with as few symlinks as possible; in other
 231 words, if Stow can create a single symlink that points to an entire
 232 subtree within the package tree, it will choose to do that rather than
 233 create a directory in the target tree and populate it with symlinks.
 234 .PP
 235 For example, suppose that no packages have yet been installed in
 236 .IR /usr/local ;
 237 it's completely empty (except for the
 238 .I stow
 239 subdirectory, of course). Now suppose the Perl package is installed.
 240 Recall that it includes the following directories in its installation
 241 image:
 242 .IR bin ;
 243 .IR info ;
 244 .IR lib/perl ;
 245 .IR man/man1 .
 246 Rather than creating
 247 the directory
 248 .I /usr/local/bin
 249 and populating it with symlinks to
 250 .I ../stow/perl/bin/perl
 251 and
 252 .I ../stow/perl/bin/a2p
 253 (and so on), Stow
 254 will create a single symlink,
 255 .IR /usr/local/bin ,
 256 which points to
 257 .IR stow/perl/bin .
 258 In this way, it still works to refer to
 259 .I /usr/local/bin/perl
 260 and
 261 .IR /usr/local/bin/a2p ,
 262 and fewer symlinks have
 263 been created. This is called ``tree folding'', since an entire subtree
 264 is ``folded'' into a single symlink.
 265 .PP
 266 To complete this example, Stow will also create the symlink
 267 .I /usr/local/info
 268 pointing to
 269 .IR stow/perl/info ;
 270 the symlink
 271 .I /usr/local/lib
 272 pointing to
 273 .IR stow/perl/lib ;
 274 and the symlink
 275 .I /usr/local/man
 276 pointing to
 277 .IR stow/perl/man .
 278 .PP
 279 Now suppose that instead of installing the Perl package into an empty
 280 target tree, the target tree is not empty to begin with. Instead, it
 281 contains several files and directories installed under a different
 282 system-administration philosophy. In particular,
 283 .I /usr/local/bin
 284 already exists and is a directory, as are
 285 .I /usr/local/lib
 286 and
 287 .IR /usr/local/man/man1 .
 288 In this case, Stow will descend into
 289 .I /usr/local/bin
 290 and create symlinks to
 291 .I ../stow/perl/bin/perl
 292 and
 293 .I ../stow/perl/bin/a2p
 294 (etc.), and it will descend into
 295 .I /usr/local/lib
 296 and create the tree-folding symlink
 297 .I perl
 298 pointing to
 299 .IR ../stow/perl/lib/perl ,
 300 and so on. As a rule, Stow only descends as
 301 far as necessary into the target tree when it can create a tree-folding
 302 symlink.
 303 .PP
 304 The time often comes when a tree-folding symlink has to be undone
 305 because another package uses one or more of the folded subdirectories in
 306 its installation image. This operation is called ``splitting open'' a
 307 folded tree. It involves removing the original symlink from the target
 308 tree, creating a true directory in its place, and then populating the
 309 new directory with symlinks to the newly-installed package
 310 .B and
 311 to the
 312 old package that used the old symlink. For example, suppose that after
 313 installing Perl into an empty
 314 .IR /usr/local ,
 315 we wish to install Emacs.
 316 Emacs's installation image includes a
 317 .I bin
 318 directory containing the
 319 .I emacs
 320 and
 321 .I etags
 322 executables, among others. Stow must make these
 323 files appear to be installed in
 324 .IR /usr/local/bin ,
 325 but presently
 326 .I /usr/local/bin
 327 is a symlink to
 328 .IR stow/perl/bin .
 329 Stow therefore takes
 330 the following steps: the symlink
 331 .I /usr/local/bin
 332 is deleted; the
 333 directory
 334 .I /usr/local/bin
 335 is created; links are made from
 336 .I /usr/local/bin
 337 to
 338 .I ../stow/emacs/bin/emacs
 339 and
 340 .IR ../stow/emacs/bin/etags ;
 341 and links are made from
 342 .I /usr/local/bin
 343 to
 344 .I ../stow/perl/bin/perl
 345 and
 346 .IR ../stow/perl/bin/a2p .
 347 .PP
 348 When splitting open a folded tree, Stow makes sure that the symlink
 349 it is about to remove points inside a valid package in the current stow
 350 directory.
 351 .BR "Stow will never delete anything that it doesn't own" .
 352 Stow ``owns'' everything living in the target tree that points into a
 353 package in the stow directory. Anything Stow owns, it can recompute if
 354 lost. Note that by this definition, Stow doesn't ``own'' anything
 355 .B in
 356 the stow directory or in any of the packages.
 357 .PP
 358 If Stow needs to create a directory or a symlink in the target tree
 359 and it cannot because that name is already in use and is not owned by
 360 Stow, then a conflict has arisen. See ``Conflicts'' in the info manual.
 361 .SH "DELETING PACKAGES"
 362 When the `-D' option is given, the action of Stow is to delete a
 363 package from the target tree. Note that Stow will not delete anything
 364 it doesn't ``own''. Deleting a package does
 365 .B not
 366 mean removing it from
 367 the stow directory or discarding the package tree.
 368 .PP
 369 To delete a package, Stow recursively scans the target tree,
 370 skipping over the stow directory (since that is usually a subdirectory
 371 of the target tree) and any other stow directories it encounters (see
 372 ``Multiple stow directories'' in the info manual). Any symlink it finds that points into
 373 the package being deleted is removed. Any directory that contained
 374 only symlinks to the package being deleted is removed. Any directory
 375 that, after removing symlinks and empty subdirectories, contains only
 376 symlinks to a single other package, is considered to be a previously
 377 ``folded'' tree that was ``split open.'' Stow will re-fold the tree by
 378 removing the symlinks to the surviving package, removing the directory,
 379 then linking the directory back to the surviving package.
 380 .SH "SEE ALSO"
 381 The info manual ``Stow 1.3.3:
 382 Managing the installation of software packages''
 383 by Bob Glickstein, Zanshin Software, Inc.
 384 .SH BUGS
 385 Please report bugs in Stow using the Debian bug tracking system.
 386 .PP
 387 Currently known bugs include:
 388 .IP *
 389 The empty-directory problem. If package FOO includes an empty
 390 directory--say, FOO/BAR--then:
 391 .IP
 392 1.
 393 if no other package has a BAR subdirectory, everything's fine.
 394 .IP
 395 2.
 396 if another stowed package, QUUX, has a BAR subdirectory, then
 397 when stowing, TARGETDIR/BAR will be ``split open'' and the
 398 contents of QUUX/BAR will be individually stowed. So far, so
 399 good. But when unstowing QUUX, TARGETDIR/BAR will be
 400 removed, even though FOO/BAR needs it to remain. A
 401 workaround for this problem is to create a file in FOO/BAR as
 402 a placeholder. If you name that file
 403 .IR .placeholder ,
 404 it will
 405 be easy to find and remove such files when this bug is fixed.
 406 .IP *
 407 When using multiple stow directories (see ``Multiple stow
 408 directories'' in the info manual), Stow fails to ``split open'' tree-folding symlinks
 409 (see ``Installing packages'' in the info manual) that point into a stow directory
 410 which is not the one in use by the current Stow command. Before
 411 failing, it should search the target of the link to see whether
 412 any element of the path contains a
 413 .I .stow
 414 file. If it finds one,
 415 it can ``learn'' about the cooperating stow directory to
 416 short-circuit the
 417 .I .stow
 418 search the next time it encounters a
 419 tree-folding symlink.
 420 .SH AUTHOR
 421 This man page was constructed by Charles Briscoe-Smith from
 422 parts of Stow's info manual. That manual contained the following
 423 notice, which, as it says, applied to this manual page, too. The text
 424 of the section entitled ``GNU General Public License'' can be found in
 425 the file
 426 .I /usr/share/common-licenses/GPL
 427 on any Debian GNU/Linux system. If you don't have access to a Debian
 428 system, or the GPL is not there, write to the Free Software Foundation,
 429 Inc., 59 Temple Place, Suite 330, Boston, MA, 02111-1307, USA.
 430 .IP
 431 Software and documentation Copyright (C) 1993, 1994, 1995, 1996 by
 432 Bob Glickstein <bobg+stow@zanshin.com>.
 433 .IP
 434 Permission is granted to make and distribute verbatim copies of this
 435 manual provided the copyright notice and this permission notice are
 436 preserved on all copies.
 437 .IP
 438 Permission is granted to copy and distribute modified versions of
 439 this manual under the conditions for verbatim copying, provided also
 440 that the section entitled ``GNU General Public License'' is included with
 441 the modified manual, and provided that the entire resulting derived
 442 work is distributed under the terms of a permission notice identical to
 443 this one.
 444 .IP
 445 Permission is granted to copy and distribute translations of this
 446 manual into another language, under the above conditions for modified
 447 versions, except that this permission notice may be stated in a
 448 translation approved by the Free Software Foundation.