Get rid of stowaway packages with GNU Stow

The installation instructions in most free software reviews aren’t enough. If you decide a package sucks, how do you get rid of it? If a package rocks, how do you upgrade it? GNU Stow, a package manager for packages you compile and install yourself, provides an easy answer to both questions.

Many GNU/Linux distribution developers use Stow, so you’ll find it in the default package repositories of every major GNU/Linux distribution. Stow’s only dependency is Perl. If you use a distribution that includes neither Stow nor Perl, you can use Stow’s simple bootstrapping instructions to install both.

Installing a package with Stow requires you to slightly modify the make install step of package installation (modifications in bold):

sudo make install prefix=/usr/local/stow/pkgnamecd /usr/local/stowsudo stow pkgname

Running make install creates the directory you specify with the prefix= variable and installs all of the package’s files there. Changing to the /usr/local/stow/ directory tells Stow to install packages into /usr/local/; Stow always installs packages into the directory above the current directory. Running stow pkgname creates symbolic links in /usr/local/ for each file beneath the package directory, and each symbolic link retains its original path minus stow/pkgname/. So, for example, if you used Stow to install vim, then type vim into most shells and application launchers, the kernel would run /usr/local/stow/vim-7.0/bin/vim.

Stow without AutoConf

Most free software packages for Unix-style operating systems use GNU AutoConf to build themselves. All AutoConf packages accept the prefix= variable to their make install command. Some packages don’t use AutoConf and may not support the prefix= variable. To install these packages with Stow, you need to edit the package’s Makefile or installation script yourself.

Start by finding the installation step through the package’s installation instructions (usually a README or INSTALL file), then modify this step to install the package’s files beneath /usr/local/stow/. If the installation instructions say to use the command make, open the Makefile file, look for a variable holding a directory name (normally /usr/local), and set this variable to /usr/local/stow/package_name-release_number/. If the installation process uses a custom script in the source directory (for example, ./install), edit the script and change the variable holding the directory name.

If the package doesn’t have an installer, you will have to create directories in /usr/local/stow/package_name-release_number/ and copy the package’s files into those directories yourself.

Some rare packages use special installers like CONS and SCons, but they and most installers work like make by reading instructions from a control file in the top level of the package source directory. To get these packages to work with Stow, try reading the installer’s manual page, finding the program’s control file, opening it in a text editor, and changing the variable holding the directory name.

Conflicts

All package managers, including Stow, are vulnerable to file name conflicts. Suppose you try to install Vim while New vi (Nvi) is already installed in /usr/local/. Both Vim and Nvi want to own the file /usr/local/bin/ex. Stow prints the following error:

stow: CONFLICT: /usr/local/stow/vim-7.0/bin/ex vs. /usr/local/bin/ex

You’re lucky: if you hadn’t been using Stow, Vim would have replaced Nvi’s ex executable without asking you.

The simplest way to resolve such a conflict is to remove one of the involved packages. Alternatively, you may be able to keep both packages by selectively renaming files. But renaming files is a tricky business. Some programs depend on names to find other files or even to run themselves correctly. In this case, for instance, renaming ex will break it; Vim’s ex expects to be called ex in order to start in ex mode.

You should be able to keep both packages by recompiling one of the packages with different file names. Running ./configure --help in Vim’s source directory, for instance, we find the following three options:

--with-vim-name=NAME    what to call the Vim executable
--with-ex-name=NAME     what to call the Ex executable
--with-view-name=NAME   what to call the View executable

Re-running ./configure with these options, changing each of the NAMEs to non-default values, re-running make, and re-running make install (with prefix=) will resolve the conflict.

Removing and upgrading packages

Removing a package with Stow requires two commands. As with installing a package, you start by changing to the /usr/local/stow/ directory. Then you run stow -D dirname on the directory holding the package you want to remove.

Stow looks in /usr/local/ for any symbolic links pointing to /usr/local/stow/dirname/ and removes them. Stow never removes or alters files in /usr/local/stow/ and its subdirectories; the files will still be there and taking up disk space. You can reinstall them if you want, or you can permanently delete them with rm.

In addition to letting you install and remove packages, Stow also lets you upgrade them by removing the old package and installing the new one. If you’re not happy with the upgrade, you can reverse the process to uninstall the replacement and reinstall the original.

And what if you try Stow, and decide that it sucks? Remove it using your distribution’s package manager, or remove it using stow -D stow. Removing Stow won’t break your existing stowed packages; they’ll continue to work.