Prerequisites ============= Stow is a collection of Perl scripts and modules. You must have Perl 5.6.1 or later in order for it to run. The test suite also requires the Test::More and Test::Output modules which can be obtained from CPAN. They are also available as packages in some of the GNU/Linux distributions. Installation methods ==================== Stow can either be installed via the standard GNU Autotools procedure (./configure, make install) or since 2.1.0, via CPAN-style via Module::Build. Advantages of the Autotools approach: - It's arguably more flexible. - It will install the documentation in Info, HTML, man, and PDF formats. Advantages of the Module::Build approach: - It's more in keeping with the standard way to distribute CPAN modules. - It performs dependency checking to ensure you have the necessary Perl modules installed. Basic Installation via Module::Build ==================================== The steps in building Stow are: 1. `cd' to the directory containing the source code (and this file). 2. If you are building from an official GNU release tarball, type `./configure && make' to configure stow for your system. If you are building from a CPAN tarball, this step can be skipped. If `make' warns that the Perl module installation directory is not in @INC, then you should run: eval `perl -V:siteprefix` ./configure --prefix=$siteprefix && make to avoid a superfluous "use lib" line in your stow executable. 3. Type `perl Build.PL'. 4. Type `./Build install' to install the various files. As noted above, this installs fewer files than the Autotools installation. Basic Installation via Autotools ================================ The steps in building Stow are: 1. `cd' to the directory containing the source code (and this file). 2. Type `./configure' to configure stow for your system. This step will attempt to locate your copy of perl and set its location in `Makefile.in'. You can use the normal arguments to change the default installation paths (see below); additionally you can use the --with-pmdir=/path/to/perl/modules option to manually choose where the Perl modules get installed. However, if you don't, the configure script will go to great lengths to try to choose a sensible default. 3. Type `make install' to install the various files. If the chosen installation directory for Perl modules is not included in Perl's built-in @INC search path, the Makefile rules will automatically insert a use lib "..."; line into the generated stow script to ensure that it can always locate the Perl modules without needing to manually set PERL5LIB. 4. You can remove the generated files from the source code directory by typing `make clean'. To also remove the files that `configure' created (so you can compile the package for a different computer), type `make distclean'. There is also a `make maintainer-clean' target, but that is intended mainly for stow's developers. If you use it, you may have to get all sorts of other programs in order to regenerate files that came with the distribution. Installation Names ================== By default, `make install' will install the package's files in `/usr/local/bin' and `/usr/local/info'. You can specify an installation prefix other than `/usr/local' by giving `configure' the option `--prefix=PATH'. If the package supports it, you can cause programs to be installed with an extra prefix or suffix on their names by giving `configure' the option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'. Since `stow' is concerned with separating a package's installation tree from its run-time tree, you might want to install `stow' into a directory such as `/usr/local/stow/stow' but have it run out of `/usr/local'. Do this by giving the run-time prefix (e.g., /usr/local) to configure as described above; then run `make'; then run `make install prefix=/usr/local/stow/stow'. For more information on this technique, see the Stow manual. The configuration system ======================== The `configure' shell script attempts to guess correct values for various system-dependent variables used during compilation. It uses those values to create a `Makefile' and to create the `stow' script itself, using Makefile.in and stow.in as templates. Finally, it creates a shell script `config.status' that you can run in the future to recreate the current configuration, a file `config.cache' that saves the results of its tests to speed up reconfiguring, and a file `config.log' containing other output. The file `configure.ac' is used to create `configure' by a program called `autoconf'. You only need `configure.ac' if you want to change it or regenerate `configure' using a newer version of `autoconf'. The file `Makefile.am' is used to create `Makefile.in' by a program called `automake'. You only need `Makefile.am' if you want to change it or regenerate `Makefile.in' using a newer version of `automake'. Sharing Defaults ================ If you want to set default values for `configure' scripts to share, you can create a site shell script called `config.site' that gives default values for variables like `CC', `cache_file', and `prefix'. `configure' looks for `PREFIX/share/config.site' if it exists, then `PREFIX/etc/config.site' if it exists. Or, you can set the `CONFIG_SITE' environment variable to the location of the site script. A warning: not all `configure' scripts look for a site script. Operation Controls ================== `configure' recognizes the following options to control how it operates. `--cache-file=FILE' Use and save the results of the tests in FILE instead of `./config.cache'. Set FILE to `/dev/null' to disable caching, for debugging `configure'. `--help' Print a summary of the options to `configure', and exit. `--quiet' `--silent' `-q' Do not print messages saying which checks are being made. `--srcdir=DIR' Look for the package's source code in directory DIR. Usually `configure' can determine that directory automatically. `--version' Print the version of Autoconf used to generate the `configure' script, and exit. `configure' also accepts some other, not widely useful, options.