                                relocinstall 0.3

Release information:
    pkg:  relocinstall version 0.3
    url:  http://www.rkeene.org/devel/relocinstall-0.3.tar.gz
   date:  Sun Oct 30 14:58:47 CDT 2011
contact:  relocinstall@rkeene.org
--------------------------------------------------------------------------

1. INTRODUCTION
---------------
"relocinstall" is a tool to aid in creating an installation program for
packages.  It also allows these packages to be "relocatable" (i.e.,
the user can decide where to install the package) without modifications
to the program itself.

This is done by finding all occurances of the build-time installation path
and creating a script (at package creation time) to replace them with
arbitrary values at package installation time.

This method is generally successful, but has some notable flaws:
	1. It will not detect and update encrypted, compressed, or otherwise
	   obsfucated instances of the build-time installation path;
	2. The build-time installation path must be as long as the maximum
	   length of the path that the user is installing to; and
	3. The build-time installation path must be unique in all files in the
	   packaged software.

Additionally, there are currently some limitations in the software itself:
	1. If the build-time installation path is duplicated in a single
	   delimited instance it will not be changed in both places (this is
	   most often a problem with "PATH")

A C compiler is required at some point to compile "rewrite-path.c" into
"rewrite-path".  This source code is built-in to "create-installer" and
it will be built automatically if "rewrite-path" is not found in your path
and a working C compiling environment is available.

2. USAGE
--------
The first thing that must be done is the "create-installer" script created
from its components.  A Makefile is supplied to perform this.  Simply running:
	$ make

should be enough to create the "create-installer" script.

Then, you should build and install your software to a temporary location with
a long and unique prefix.  If the software is using GNU autoconf, this may be
done by something similar to this ("temp-path" is included with this package):
	$ RELOCINSTALL_PREFIX="$(/path/to/temp-path)"
	$ ./configure --prefix="${RELOCINSTALL_PREFIX}"
	$ make
	$ make install

Next, the "create-installer" script should be invoked with the parameters of
the installed software.  "create-installer" takes atleast 4 arguments:
	a. Root
		i. This is the root of the installation tree,
		   "${RELOCINSTALL_PREFIX}" in the above example.
	b. Output
		i. This is the name of the script to create as the installer.
	c. Package Name
		i. This is the name of the package, to identify to the user.
	d. Package Version
		i. This is the version of the package, to identify to the user.
	e. (optional) Metadata Directory
		i. This directory contains metadata to install into the
		   package, such as:
			(1) Post-Install Scripts
				If present, this is run in bash after the
				files are moved into place.  The working
				directory is the root of the installed tree
			(2) Pre-Install Scripts
				If present, this is run in bash before the
				files are moved into place.  The working
				directory is the root of the to-be-installed
				tree.
			(3) Rewrite Path Scripts:
				If present, this takes precence over the
				automatically generated one.

Example usage, building on the previous example would be:
	$ create-installer "${RELOCINSTALL_PREFIX}" \
	  "mypkg-1.0-linux-amd64-installer.sh" \
	  MyPKG \
	  1.0
