Whole document tree

4. 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. See section 6.3 Conflicts.