spill man page

spill — segregated package install logical linker

Synopsis

Installation

spill [ -f ] [ -n ] [ -q ] [ -x ] [ -r ] [ -o ] [ -l <file> | --conflict-file=<file> ] tool_install_path [ link_install_path ] [ ignore_path... ]

Removal

spill -d [ -q ] tool_install_path [ link_install_path ]

spill -D [ -q ] package_name [ link_install_path ]

Usage summary

spill -h

Display version

spill -V

Description

spill is a tool which creates symbolic links under a destination directory which point to the corresponding locations under a source directory.

The original use of spill is to support building programs from source with separate installation prefixes, so that individual programs (and versions of the same program) can be kept apart, yet by creating links to the installations under /usr/local, it is convenient to access the programs without PATH, LD_LIBRARY_PATH, MANPATH etc having to get out-of-hand.

The tool can also be used to remove a set of links to a package installed elsewhere.

Arguments

tool_install_path
This is the head of the directory tree at which the package is installed.

If an absolute path is given, absolute symbolic links will be created.

If a relative path is given, relative symbolic links will be created. Note, the path should be relative to the current directory, not to the destination (link_install_path) directory.

spill assumes that the final two directory components of tool_install_path are the package name, and the package version, in that order. For example, suppose binary installations are placed under /apps. Version 1.1 of a package called foobar would be installed under /apps/foobar/1.1. So there would be directories like /apps/foobar/1.1/bin, /apps/foobar/1.1/man/man1 etc. This approach allows spill to auto-detect when an existing package is being upgraded by a newer version, and not complain about links being replaced in such circumstances.
link_install_path
This is the head of the directory tree where the links should be placed. If omitted, it defaults to the current directory.
ignore_path...
This is a space separated list of paths to ignore in the linking process. Each path is relative to tool_install_path

A frequent problem when using spill is the dir file in the info subdirectory. The make install process typically creates one of these files in every tool installation, and these conflict when spill tries to create links. (In the world the designers of info envisaged, everything installs to a common directory tree and there is a single info/dir file that gathers the topics for all of the tools.)

To ignore the conflicting info/dir file, spill would be invoked like this:

spill /apps/foo/1.0 /usr/local info/dir

Note, if one of the ignored relative paths is a directory, everything under that directory is ignored too.
-f,
--force
Normally, spill will check that tool_install_path and link_install_path each have at least one of the following subdirectories : bin, lib or sbin. This provides a sanity check against user errors in specifying the directories on the command line. The -f option allows this checking to be overridden.
-n,
--dry_run
This option does a 'dry-run', i.e. reports on any potential install conflicts then stops without actually creating any links.
-q,
--quiet
This option means 'quiet'. Only errors will be reported. Normally, successful link creations are reported too.
-r,

--retain
This option causes links to an older version of the package to be retained if they are not replaced by an equivalent in the newer version of the package.

The default is to remove all links to the currently installed version, before installing the new version. This avoids the (usually) unwanted references to older versions.

-x,
--expand
This option means 'expand'. Suppose a single package called wibble has already been linked under /usr/local using spill. The directory /usr/local/man would probably be linked to something like /apps/wibble/1.0/man. Now, suppose spill is called to install package foobar under /usr/local, and this package has a manpage also. spill wouldn't be able to link /usr/local/man to /apps/foobar/1.1/man, because that would break access to wibble's manpage. In this case, a "NEEDEXPN" error will be reported during the pre-installation check. This means that the symbolic links to directories need to be "expanded", i.e. replaced by directories containing links to the contents of the directory that they used to be linked to. spill can perform such expansions automatically if the -x switch is specified. This option is not the default, though, because it will modify the filesystem even if -n is specified.
-o,
--override
This option means 'override'. If the destination tree contains links that conflict with those spill wants to create to link in the new package, normally spill will report the conflicts and give up. If -o is specified, the existing links will be removed and the links pointing to the new package will take their place. This is useful if the file in the existing package and that in the new package provide basically the same data, but the one in the new package is more up to date than the existing one.
-l conflict_filename
--conflict-list=filename
When there are conflicts between the tool you are trying to install and the existing installation, this option allows the list of conflicting links to be written to a file. This can be expanded as the ignore-path argument on another spill run.
-d
--delete-tree

Delete an installation, given the path to the installed tree and the path to the area where the symlinks are.

Note that -d does not actually delete the installed software. It only removes the symlinks that point to it. However, it is useful in the case where you intend to remove the installed software in a separate step, and avoids the symlink area being left with stale symlinks.

-D
--delete-pkg

Delete an installation, given the name of the package and the path to the area where the symlinks are. This relies on the information stored in the .spill subdirectory of the link area to know what needs to be deleted.

Note that -D does not actually delete the installed software. It only removes the symlinks that point to it. However, it is useful in the case where you intend to remove the installed software in a separate step, and avoids the symlink area being left with stale symlinks.

Example

Suppose you want to build and install a package called foobar, version 1.1. The steps you might take would be

tar xzvf foobar-1.1.tar.gz
cd foobar-1.1

make
make install
spill /apps/foobar/1.1 /usr/local

Other Possibilities

To be written

Similar Programs

Some programs which carry out a similar function to spill are : stow, depot, graft, relink

(Apologies to other programs of this nature that I've missed out.)

Author

This version of spill was written by Richard Curnow <rc@rc0.org.uk>

Info

2006