A package is a related collection of files and directories that you wish to administer as a unit — e.g., Perl or Emacs — and that needs to be installed in a particular directory structure — e.g., with bin, lib, and man subdirectories.
A target directory is the root of a tree in which one or more
packages wish to appear to be installed. /usr/local is a
common choice for this, but by no means the only such location. Another
common choice is ~ (i.e. the user’s $HOME directory) in
the case where Stow is being used to manage the user’s configuration
(“dotfiles”) and other files in their $HOME. The examples in
this manual will use /usr/local as the target directory.
A stow directory is the root of a tree containing separate packages in private subtrees. When Stow runs, it uses the current directory as the default stow directory. The examples in this manual will use /usr/local/stow as the stow directory, so that individual packages will be, for example, /usr/local/stow/perl and /usr/local/stow/emacs.
An installation image is the layout of files and directories required by a package, relative to the target directory. Thus, the installation image for Perl includes: a bin directory containing perl and a2p (among others); an info directory containing Texinfo documentation; a lib/perl directory containing Perl libraries; and a man/man1 directory containing man pages.
Note: This is a pre-installation image which exists even before Stow has installed any symlinks into the target directory which point to it.
A package directory is the root of a tree containing the installation image for a particular package. Each package directory must reside in a stow directory — e.g., the package directory /usr/local/stow/perl must reside in the stow directory /usr/local/stow. The name of a package is the name of its directory within the stow directory — e.g., perl.
Thus, the Perl executable might reside in /usr/local/stow/perl/bin/perl, where /usr/local is the target directory, /usr/local/stow is the stow directory, /usr/local/stow/perl is the package directory, and bin/perl within is part of the installation image.
A symlink is a symbolic link, i.e. an entry on the filesystem whose path is sometimes called the symlink source, which points to another location on the filesystem called the symlink destination. There is no guarantee that the destination actually exists.
In general, symlinks can be relative or absolute. A symlink is absolute when the destination names a full path; that is, one starting from /. A symlink is relative when the destination names a relative path; that is, one not starting from /. The destination of a relative symlink is computed starting from the symlink’s own directory, i.e. the directory containing the symlink source.
Note: Stow only creates symlinks within the target directory which point to locations outside the target directory and inside the stow directory.
Consequently, we avoid referring to symlink destinations as symlink targets, since this would result in the word “target” having two different meanings:
- the target directory, i.e. the directory into which Stow targets installation, where symlinks are managed by Stow, and
- the destinations of those symlinks.
If we did not avoid the second meaning of “target”, then it would lead to confusing language, such as describing Stow as installing symlinks into the target directory which point to targets outside the target directory.
Similarly, the word “source” can have two different meanings in this context:
- the installation image, or some of its contents, and
- the location of symlinks (the “source” of the link, vs. its destination).
Therefore it should also be avoided, or at least care taken to ensure that the meaning is not ambiguous.