The sp-install program

sp-install /package/admin/foo-2.0 [...]
sp-install foo-2.0.tar [...]
sp-install http://example.org/foo/foo-2.0.tar [...]

sp-install installs one or more packages. Each argument names a a package directory, a tarball (possibly compressed with gzip or bzip2) or a URL. By default, sp-install will:

• download the tarball, if a URL is given;
• unpack the tarball in /package, if a URL or tarball was given, or run sp-unpack on the package directory name otherwise;
• remove the package's compile/ subdirectory, if it exists, to ensure a clean build;
• run the package/compile script to build the package;
• run the package/own script if it exists, so the package can set any special ownership or setuid/setgid bits that it needs;
• run the package/check script if it exists, to check that the package is working correctly;
• remove the compile/ subdirectory again;
• use sp-version to set the current-version symlink;
• use sp-links (with $SP_REPLACE_LINKS set to "n" by default if the package name is under "host/") to install symlinks in /command and /usr/local/bin, pointing to the files in the package's command/ subdirectory, if it exists; and
• run the package/run script if it exists, to make the package's services available to the system.

You can alter this behavior by setting these environment variables:

• $SP_ROOT: unpack the tarball in $SP_ROOT/package (if the given path is a regular file) and install the command symlinks in $SP_ROOT/command and $SP_ROOT/usr/local/bin. This is useful mainly for non-root users.
• $SP_HOOK: this specifies a program to be run at various points during the installation. It is invoked with its first argument indicating what point it is being invoked from, and with these environment variables indicating the package being installed: $SP_PATH, $SP_DIR, $SP_PATH_ROOT, $SP_CATEGORY, $SP_BASE, and $SP_VERSION. If the hook program exits with status 99, the rest of the installation of that package is skipped. $SP_HOOK is run with these arguments during installation: BEFORE_UNPACK, AFTER_UNPACK, AFTER_CONFIGURE, AFTER_INSTALL (only if $SP_TRUST_INSTALL is y; see below), AFTER_COMPILE, AFTER_OWN, AFTER_CHECK, AFTER_CLEAN, AFTER_VERSION, AFTER_LINKS, and AFTER_RUN.
• $SP_STOP_AFTER=unpack: stop after unpacking the tarball, before configuring. SP_STOP_AFTER is deprecated in favor of SP_HOOK.
• $SP_ROOT also causes sp-install to automatically adjust the compile-time configuration to use the augmented path for this package and dependencies, in cases where sp-install recognizes how to express that.
• $SP_CLEAN=n: don't remove the compile/ subdirectory before installing.
• $SP_TRUST_INSTALL=y: after unpacking the tarball, simply run package/install instead of doing the individual steps explicitly. This overrides all the following variables.
• $SP_COMPILE_USER: unpack the tarball and run package/compile as this user; this is useful only for root and requires one of the admin/daemontools package, s6, Perl, Python, or Guile. sp-install will also edit the compile-time configuration to compile as this user, in cases where sp-install recognizes how to express that.
• $SP_DO_OWN=n: don't run package/own. This is the default when running as non-root.
• $SP_KEEP_COMPILE=y: don't remove the compile/ subdirectory after building the package.
• $SP_STOP_AFTER=build: stop after building the package, before updating the current-version symlink. This is useful when you want to test the package before marking it as the current version.
• $SP_SKIP_TEST=y: don't run package/check.
• $SP_IGNORE_TEST_FAIL: if set to "y", sp-install will continue with installation even if the package/check script fails. If set to "skip" and package/check fails, sp-install will not complete the installation of this package, but it will continue with the installation of other packages given on the command line and exit 0.
• $SP_STOP_AFTER=version: stop after updating the current-version symlink, before creating command symlinks. This is useful if some of the command names may conflict with other commands on your system.
• $SP_COMPAT=n: don't create command symlinks in $SP_ROOT/usr/local/bin.
• $SP_STOP_AFTER=links: stop after creating command symlinks, before running package/run. This is useful if you want to manually control integrating the package with your system.

If you specify a tarball, not a directory, then sp-install will store temporary files in $TMPDIR (defaulting to /tmp).

A note on security: if you run sp-install as root with $SP_TRUST_INSTALL=n (the default), $SP_STOP_AFTER=links or the equivalent with $SP_HOOK (not the default) and $SP_COMPILE_USER=somebody (not the default), then sp-install will not run any code from the package as root, except for package/own and package/check; those are the only parts of the package you need to trust, plus sptools itself. Ideally, there should be some sort of automatic signature verification, but I'm not sure how it should work.

Here's a useful $SP_HOOK example. If you manually add a package/url_src file to a package that doesn't supply one of its own, to enable sp-install's automatic downloading for upgrades, then this hook will copy that package/url_src file into the new version.

A note to package authors: please do not make your package's build system aware of $SP_ROOT or other sptools-related configuration. Instead, let your package be reconfigured by editing files in conf-compile/. (For an example, take a look at how runwhen depends on skalibs; runwhen's package/INSTALL and conf-compile/defaults/depend_skalibs files explain how it works.) sp-install will edit your configuration files to tell your package where various things are. This way, the configuration information that was used to build the package will be recorded in the filesystem for later reference, and there will be no risk of accidentally applying $SP_ROOT multiple times to the same configuration path.