Package: auto-destdir
License: MIT
Copyright: (C) 2009 Institute for Defense Analyses and David A. Wheeler
Author: David A. Wheeler

The auto-destdir tools automate a common installation step,
making it easier to install Unix/Linux software from source code.
Specifically, the tools redirect file installations so that the installed
files are placed inside the the $DESTDIR directory,
even if the provided makefile doesn't natively support $DESTDIR.

In most cases you can simply replace "make install" with
"make-redir DESTDIR=directory_name install".

Historically, source code install scripts for Unix/Linux are often run by
typing "make install".  This script would write directly
to privileged directories like "/usr/bin" to perform the installation.
However, most modern packaging systems (such as those for .rpm and .deb files)
require that files be written to some intermediate directory,
even though when run they will be in a different filesystem location.
This redirection is easy to do if the installation script supports the
"DESTDIR convention"; simply set DESTDIR to the intermediate directory's
value and run "make install".  Unfortunately, many source packages don't
support the DESTDIR convention.

The auto-destdir tools automatically adds DESTDIR support when
running an install script, even if it doesn't natively support it.
It does this by wrapping typical install commands (install, cp, ln, mkdir).
For more information, see the provided man pages and:
 http://www.dwheeler.com/essays/automating-destdir.html

The auto-destdir tools provide two user-level commmands,
"make-redir" and "run-redir".  See their manual pages (provided)
for more information on how to use these commands.

The auto-destdir tools are written using the bash shell language.
Thus, the programs are architecture-neutral, and are easily handled by
most build processes (since bash is typically already available).


QUICK START: CONFIGURE/BUILD/INSTALL
This program follows the standard GNU conventions for configuration,
compiling/building, and installing.  To install auto-destdir in /usr/local:
  ./configure
  make
  sudo make install
To install auto-destdir in /usr (standard system file location) instead of
/usr/local, replace ./configure with:
  ./configure --prefix=/usr
To *use* auto-destdir, e.g., to use auto-destdir's make-redir to
install some OTHER program in /tmp/mystuff:
  make-redir DESTDIR=/tmp/mystuff install
More details below.



CONFIGURING
To configure, run "./configure" with the usual GNU conventions.
Options include:
  --prefix=DIR: Prefix of directories where files will be installed.
  --bindir=DIR: directory where the user-selected programs will be installed.
  --scriptdir=DIR: directory where the wrapped scripts will be stored.

To install using the prefix /usr/local (the default):
  ./configure
Use "--prefix=DIR" to change the prefix, e.g., for prefix "/usr", use:
  ./configure --prefix=/usr
If you don't have root privileges, you can install the program to your
local user directory as follows (make sure $HOME/bin is in your PATH):
  ./configure --prefix="$HOME"


BUILDING
To build:
  make
There are no compiled programs, but this is still necessary to set up
the scripts as configured.  You must run "./configure" first.



TESTING (OPTIONAL)
You can run "make test" to run the built-in tests.



INSTALLING
First, make sure you can write to its destination (you may need to be root).
To install directly to its final place of use:
  make install
You can set DESTDIR if desired when installing, e.g.:
  make DESTDIR=/usr/tmp/x install

There is no separate "INSTALL" file that explains how to install
this program.  Please don't add one! There is already a program named
"install", so adding an "INSTALL" file will make it impossible to use a
filesystem that does not distinguish between uppercase and lowercase filenames.



BUGS/LIMITATIONS
The script directory cannot contain ":", because it is placed
inside the PATH variable which uses ":" as the directory name separator.

See the manual page for make-redir(1) for more on bugs and limitations.


MODIFYING
Don't modify "Makefile"; instead, modify "Makefile.in", and run
"./configure" before using it (./configure copies Makefile.in to Makefile).

If you add a wrapped command, modify "Makefile.in" to install it
(esp. the target do-install), modify
"bogus-shell" to strip its prefixes, and modify "make-redir.1" to document it.
If you add new front-ends or docs you'll need to modify uninstall as well.
Beware of wrapping commands that are used by the implementations themselves
(e.g., sed); you'll need to modify the wrapped commands in those cases.

After modifying something, add tests to "runtests", and run them
with "make test".

Before releasing a modified version, change its version number
in both the Makefile.in (VERSION=) and the *.spec file (Version:).

Please contribute improvements back, so all can use them and so you
don't have to keep maintaining them.

You can run the tools (for testing) easily, without installing them, by doing:
  # cd to the directory containing these scripts
  ./configure --scriptdir=`pwd`
  make
then you can call the wrapped commands like this:
  DESTDIR=/tmp/mystuff ./run-redir mkdir "/usr/bin/a b"
(run-redir sets the PATH, so the wrapped commands can find what they need).



DEPENDENCIES
To run at all, this requires:
bash
getopt

NOTE: You need an enhanced getopt(1) that can handle quoted text.
If yours doesn't, upgrade it.  We need that to handle spaces in filenames.

In addition, make-redir requires (when run):
make

To create a distribution and view documentation:
man
ps2pdf (e.g., the one in ghostscript)
tar

The tests require a working "stat" (e.g., from GNU coreutils) to properly
test "touch".  Just do "make test", it'll whine if you don't have it.

CREDITS

Thanks go to the U.S. DoD NII, for funding initial development,
and to both the U.S. DoD NII and IDA, for authorizing the public release
of auto-destdir.