(stow.info)Installing Packages

---

Next: Deleting Packages Prev: Ignore Lists Up: Top

---

Enter node , (file) or (file)node

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

5.1 Tree folding
================

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.  However, this behaviour can be changed via the `--no-folding'
option; Note: Invoking Stow.

5.2 Tree unfolding
==================

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" or
"unfolding" 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'.

5.3 Ownership
=============

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: symlinks that point into a package in the stow directory, or
directories that only contain symlinks that stow "owns".   Note that by
this definition, Stow doesn't "own" anything _in_ the stow directory or
in any of the packages.

5.4 Conflicts during installation
=================================

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.