GNU Info

Info Node: (stow.info)Installing packages

(stow.info)Installing packages


Next: Deleting packages Prev: Invoking Stow Up: Top
Enter node , (file) or (file)node

Installing packages
*******************

   The default action of Stow is to install a package.  This means
creating symlinks in the target tree that point into the package tree.
Stow attempts to do this with as few symlinks as possible; in other
words, if Stow can create a single symlink that points to an entire
subtree within the package tree, it will choose to do that rather than
create a directory in the target tree and populate it with symlinks.

   For example, suppose that no packages have yet been installed in
`/usr/local'; it's completely empty (except for the `stow'
subdirectory, of course).  Now suppose the Perl package is installed.
Recall that it includes the following directories in its installation
image:  `bin'; `info'; `lib/perl'; `man/man1'.  Rather than creating
the directory `/usr/local/bin' and populating it with symlinks to
`../stow/perl/bin/perl' and `../stow/perl/bin/a2p' (and so on), Stow
will create a single symlink, `/usr/local/bin', which points to
`stow/perl/bin'.  In this way, it still works to refer to
`/usr/local/bin/perl' and `/usr/local/bin/a2p', and fewer symlinks have
been created.  This is called "tree folding", since an entire subtree
is "folded" into a single symlink.

   To complete this example, Stow will also create the symlink
`/usr/local/info' pointing to `stow/perl/info'; the symlink
`/usr/local/lib' pointing to `stow/perl/lib'; and the symlink
`/usr/local/man' pointing to `stow/perl/man'.

   Now suppose that instead of installing the Perl package into an empty
target tree, the target tree is not empty to begin with.  Instead, it
contains several files and directories installed under a different
system-administration philosophy.  In particular, `/usr/local/bin'
already exists and is a directory, as are `/usr/local/lib' and
`/usr/local/man/man1'.  In this case, Stow will descend into
`/usr/local/bin' and create symlinks to `../stow/perl/bin/perl' and
`../stow/perl/bin/a2p' (etc.), and it will descend into
`/usr/local/lib' and create the tree-folding symlink `perl' pointing to
`../stow/perl/lib/perl', and so on.  As a rule, Stow only descends as
far as necessary into the target tree when it can create a tree-folding
symlink.

   The time often comes when a tree-folding symlink has to be undone
because another package uses one or more of the folded subdirectories in
its installation image.  This operation is called "splitting open" a
folded tree.  It involves removing the original symlink from the target
tree, creating a true directory in its place, and then populating the
new directory with symlinks to the newly-installed package _and_ to the
old package that used the old symlink.  For example, suppose that after
installing Perl into an empty `/usr/local', we wish to install Emacs.
Emacs's installation image includes a `bin' directory containing the
`emacs' and `etags' executables, among others.  Stow must make these
files appear to be installed in `/usr/local/bin', but presently
`/usr/local/bin' is a symlink to `stow/perl/bin'.  Stow therefore takes
the following steps:  the symlink `/usr/local/bin' is deleted; the
directory `/usr/local/bin' is created; links are made from
`/usr/local/bin' to `../stow/emacs/bin/emacs' and
`../stow/emacs/bin/etags'; and links are made from `/usr/local/bin' to
`../stow/perl/bin/perl' and `../stow/perl/bin/a2p'.

   When splitting open a folded tree, Stow makes sure that the symlink
it is about to remove points inside a valid package in the current stow
directory.  _Stow will never delete anything that it doesn't own_.
Stow "owns" everything living in the target tree that points into a
package in the stow directory.  Anything Stow owns, it can recompute if
lost.  Note that by this definition, Stow doesn't "own" anything _in_
the stow directory or in any of the packages.

   If Stow needs to create a directory or a symlink in the target tree
and it cannot because that name is already in use and is not owned by
Stow, then a conflict has arisen.  Note: Conflicts.


automatically generated by info2www version 1.2.2.9