spill.8

.\" -*- nroff -*-
.\" Copyright 2003, 2004, 2005, 2006 Richard P. Curnow
.\" This file may be copied under the terms of version 2 of the GNU Public
.\" License.

.TH SPILL 8 "2006"
.SH NAME
spill \- segregated package install logical linker
.SH SYNOPSIS
.SS Installation
.B spill
[
.B \-f
]
[
.B \-n
]
[
.B \-q
]
[
.B \-x
]
[
.B \-r
]
[
.B -o
]
[
.B \-l
.I <file>
|
.I --conflict-file=<file>
]
.I tool_install_path
[
.I link_install_path
]
[
.I ignore_path...
]

.SS Removal
.B spill
.B -d
[
.B \-q
]
.I tool_install_path
[
.I link_install_path
]

.B spill
.B -D
[
.B \-q
]
.I package_name
[
.I link_install_path
]

.SS Usage summary
.B spill
.B -h

.SS Display version
.B spill
.B -V

.SH DESCRIPTION
.B spill
is a tool which creates symbolic links under a
.I destination
directory which point to the corresponding locations under a
.I source
directory.
.sp
The original use of
.B 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.
.sp
The tool can also be used to remove a set of links to a package installed
elsewhere.

.SH ARGUMENTS
.TP
.B tool_install_path
.br
This is the head of the directory tree at which the package is installed.
.sp
If an absolute path is given, absolute symbolic links will be created.
.sp
If a relative path is given, relative symbolic links will be created.  Note,
the path should be relative to the current directory,
.B not
to the destination (link_install_path) directory.
.sp
.B 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
.B 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.

.TP
.B link_install_path
.br
This is the head of the directory tree where the links should be placed.  If
omitted, it defaults to the current directory.

.TP
.B ignore_path...
.br
This is a space separated list of paths to ignore in the linking process.  Each
path is relative to
.B tool_install_path
.sp
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.)
.sp
To ignore the conflicting info/dir file,
.B spill
would be invoked like this:
.sp
    spill /apps/foo/1.0 /usr/local info/dir
.sp
Note, if one of the ignored relative paths is a directory, everything under
that directory is ignored too.

.TP
.BR \-f ,
.B \-\-force
.br
Normally,
.B 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
.B -f
option allows this checking to be overridden.

.TP
.BR \-n ,
.B \-\-dry_run
.br
This option does a 'dry-run', i.e. reports on any potential install conflicts
then stops without actually creating any links.

.TP
.BR \-q ,
.B \-\-quiet
.br
This option means 'quiet'.  Only errors will be reported.  Normally, successful
link creations are reported too.

.TP
.BR \-r ,
.B \-\-retain
.br
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.

.TP
.BR \-x ,
.B \-\-expand
.br
This option means 'expand'.  Suppose a single package called wibble has already
been linked under /usr/local using
.B spill.
The directory /usr/local/man would
probably be linked to something like /apps/wibble/1.0/man.  Now, suppose
.B spill
is called to install package foobar under /usr/local, and this package has a
manpage also.
.B 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.
.B spill
can perform such expansions automatically if the
.B -x
switch is specified.  This option is not the default, though, because it will
modify the filesystem even if
.B -n
is specified.

.TP
.BR \-o ,
.B \-\-override
.br
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
.B -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.

.TP
.BI "\-l " conflict_filename
.br
.ns
.TP
.BI "--conflict-list=" filename
.br
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
.I ignore-path
argument on another
.B spill
run.

.TP
.B \-d
.br
.ns
.TP
.B \-\-delete-tree
.br
Delete an installation, given the path to the installed tree and the path to the area where
the symlinks are.

Note that
.B \-d
.B does
.B 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.


.TP
.B \-D
.br
.ns
.TP
.B \-\-delete-pkg
.br
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
.I .spill
subdirectory of the link area to know what needs to be deleted.

Note that
.B \-D
.B does
.B 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.



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

.br
tar xzvf foobar-1.1.tar.gz
.br
cd foobar-1.1
.br
./configure --prefix=/apps/foobar/1.1
.br
make
.br
make install
.br
spill /apps/foobar/1.1 /usr/local

.SH OTHER POSSIBILITIES

.sp
To be written

.SH SIMILAR PROGRAMS
Some programs which carry out a similar function to
.B spill
are : stow, depot, graft, relink
.sp
(Apologies to other programs of this nature that I've missed out.)

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