In order to install software that meets specific requirements, administrators often compile programs from source code. But this flexibility can come at a high price as programs derived from source code can be difficult to administer once they’ve been installed. The flexibility you gain by using the source code to install software can be lost when you attempt to maintain that software. For example, you may have trouble testing and reconfiguring software packages on a regular basis and you may find that a new application has problems sharing resources with other programs on the system. Plus, you may also run into trouble if you are developing your own applications and want the ability to install and remove the new program and its associated files easily.

There is, of course, a tool that can help you work around these roadblocks. In this Daily Feature, I’ll take a look at Stow, an easy-to-use program that helps administrators better manage software installations.

What is Stow?
Stow is a Perl script for administering the installation of any software packages that are installed in the /usr/local/ directory tree. Stow may also be used to perform multiple installations of the same package. When Stow is used, a source code package is compiled into its own directory under /usr/local/stow. Stow then creates symbolic links to the installed package to make it appear as though the software is installed in its default location. Administrators can then make any changes to the installed program within its own directory tree and simply update the symbolic links to reflect any changes they made.

Where to get Stow
The home page for the Stow project lives on the GNU official site, and the latest version of Stow can be downloaded from the GNU ftp site.

Since Stow itself is a Perl script, Perl must be installed on your system. Chances are, this is a nonissue since nearly all the major Linux distributions install Perl by default. If your system doesn’t have Perl installed, make sure you download version 5.005 or later. (Version 5.6.1 is the latest as of this writing.)

Once Stow is downloaded, the next step is to untar the package with the command:
tar -zxvf stow-1.3.3.tar.gz

The default installation for Stow is /usr/local/bin. To install Stow and its associated files into a separate directory, you’ll need to cd into the directory created when Stow is unpacked and run the following commands as root:
make install prefix=/usr/local/stow

The Stow executable command will now be created in /usr/local/stow/bin. The Stow man pages and the Stow info files will be created in /usr/local/stow/man and /usr/local/stow/info.

Now that Stow is installed, you need to know some of the terminology associated with the program. Table A lists the most common Stow terms.

Table A
Package A package refers to the files and directories that make up an application.
Stow directory This is the root of a directory tree that contains stowed programs in separate subdirectories.
Target directory This is the root of a directory tree in which one or more programs appear to be installed.

When /usr/local/ is used as a target directory, the stowed directory appears to be installed in /usr/local/.

Installation image The installation image refers to the location or locations of files required by a package, relative to the target directory. For example, the installation image for Stow includes the /usr/local/stow/bin directory, containing the stow executable, a man directory, and an info directory.
Package directory This is the root of the directory tree containing an installation image. Each package directory must reside in a Stow directory. For example, the package directory /usr/local/stow/prozilla/ must be part of the usr/local/stow directory tree.

Using Stow
Stow installs a package by creating symbolic links in the target directory that point back to the package installed under the /usr/local/stow/ directory (the package directory). Stow will attempt to install any package using the least amount of symbolic links possible. If it can, Stow can create one symbolic link that points to the complete directory tree for the package directory instead of creating a symbolic link for every file and directory in the package directory. The process of creating this single symbolic link is known as tree folding.

Tree folding
To examine how tree folding works, let’s assume that no programs have been installed into /usr/local/ and the only subdirectory is /usr/local/stow. Now assume that you want to install Perl, which will use an installation image similar to the following:

When Stow sees this installation image, it will create one symbolic link in /usr/local/bin, and that symbolic link will point back to /usr/local/stow/perl/bin. In this example of tree folding, an entire directory tree, /usr/local/stow/perl/, has been folded into one symbolic link. Stow will also create symbolic links to other subdirectories of /usr/stow/perl, including /usr/local/info pointing to /usr/local/perl/info, and any other subdirectories of /usr/local/stow/perl/, including /usr/local/stow/perl/man, /usr/local/stow/perl/info, and so on.

Tree splitting
A symbolic link representing a folded tree will often have to be removed when another program needs to share files contained in the installation image. The process of removing these symbolic links is called tree splitting. When tree splitting is performed, Stow:

  • Removes the original symbolic link from the target directory.
  • Creates a directory tree to replace the symbolic link.
  • Creates symbolic links in the new directory. These symbolic links point to the new program and to the program that used the original symbolic links that Stow just removed.

In the previous example of tree folding, Perl was installed into an empty /usr/local directory tree. Now, if you need to install another program that also needs to use /usr/local/bin for its own executable commands, Stow must make these executables appear as if they are installed in /usr/local/bin. Unfortunately, /usr/local/bin is actually just a symbolic link to /usr/local/stow/perl. To make this second installation work, Stow will:

  • Remove the symbolic link /usr/local/bin.
  • Create the directory /usr/local/bin.
  • Create symbolic links to executables in /usr/local/stow/bin and /usr/local/stow/<new-program>/bin.

When Stow splits a tree open, it makes sure that any symbolic links to be removed point to a valid package under /usr/local/stow/. To be safe, Stow will not delete files it does not own. (Stow owns all files in the target directory that point to a package under /usr/local/stow.) If links to a valid stowed package are removed, Stow can re-create these links at any time.

Installing source code to the target directory
The purpose of using Stow is to make your system think an application is installed into a default directory when it is actually installed into a directory in the /usr/local/stow tree. To see how this works, let’s look at a sample installation of Prozilla with Stow. The steps of this installation are as follows:

  1. Create the target directory for Prozilla with the command mkdir /usr/local/stow/prozilla.
  2. Enter the directory containing the Prozilla source code with the command cd /src/prozilla.
  3. Run the Prozilla configure with no options with the command ./configure.
  4. Create the proz executable with the command make.
  5. Install Prozilla to the /usr/local/stow/prozilla/ directory with the command: make install prefix /usr/local/stow/prozilla.

At this point, Prozilla has been installed into the /usr/local/stow/prozilla directory; however, if the following command is run:
which proz

then the proz command will not be found. This is because Prozilla has not been stowed yet. To stow Prozilla, first enter the /usr/local/stow directory with the command:
cd /usr/local/stow

Then, stow Prozilla with the command
stow prozilla

The stow command will create symbolic links to /usr/local/stow/prozilla in /usr/local/bin. At this point, the proz command will execute as if Prozilla has been installed in /usr/local/.

Configure with prefix
When software is installed from source code, the normal method for changing the installation directory is to use the –prefix option with the ./configure command. For example, the following command:
./configure –prefix /usr/local/prozilla

will change the default directory for Prozilla from /usr/local/ to /usr/local/prozilla. Users often use this command to install an application to the /usr/local/stow/<program-name>/ directory. When this method is used, the program may still be run from the stowed directory, but this will create two problems. First, the program will not run from its target directory. Second, when the prefix is set to the stowed directory, the program will look for any shared resources required in the Stow directory tree. However, the stowed target directory contains only files that belong to the program itself, so any shared resources will be unavailable.

To make the program appear to be installed in the /usr/local/ tree but actually divert the installation into the stowed directory tree, the prefix option is used with this make install command:
make install prefix=/usr/local/stow/<program-name>

Removing stowed packages
When a stowed package is removed, Stow actually removes the package from the target directory but leaves the stowed directory intact. During the deletion process, Stow recursively scans through the target directory tree and removes any symbolic links pointing back to the package. The deletion process will also delete any directory that contains only symbolic links to the package being deleted. The command used to remove a package is:
stow -D <package-name>

The delete option is useful when changes are made to the configuration of a package and you want the target to reflect these changes. For example, if changes are made to Prozilla and you want the target directory to reflect these changes, use the following steps:

  1. Run the command stow -D prozilla.
  2. Make any necessary changes to the Prozilla configuration.
  3. Run the command stow prozilla.

The target directory will now contain symbolic links pointing to the updated Prozilla configuration.

Remove and then stow

Always remove a package prior to making any changes to the package directory. Then, stow the application again. This will help you avoid using broken symbolic links.

Stow is a great utility that Linux administrators should take advantage of on a regular basis. Easy to install and use, Stow makes the installation of programs from source code a more manageable process. Consider using Stow the next time you install a complex program or any program you want to test before placing it in a production environment. By employing Stow in this way, you can avoid critical installation errors that could cripple a server or desktop computer.