Whole document tree

2. Terminology

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. A common, but by no means the only such location is `/usr/local'. 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.

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. A symlink can be relative or absolute. An absolute symlink names a full path; that is, one starting from `/'. A relative symlink names a relative path; that is, one not starting from `/'. The target of a relative symlink is computed starting from the symlink's own directory. Stow only creates relative symlinks.