INSTALL

   1 Prerequisites
   2 =============
   3
   4 Stow is a collection of Perl scripts and modules.  You must have Perl
   5 5.6.1 or later in order for it to run.  The test suite also requires
   6 the Test::More and Test::Output modules which can be obtained from
   7 CPAN.  They are also available as packages in some of the GNU/Linux
   8 distributions.
   9
  10 Installation methods
  11 ====================
  12
  13 Stow can either be installed via the standard GNU Autotools procedure
  14 (./configure, make install) or since 2.1.0, via CPAN-style via
  15 Module::Build.
  16
  17 Advantages of the Autotools approach:
  18
  19   - It's arguably more flexible.
  20
  21   - It will install the documentation in Info, HTML, man, and PDF
  22     formats.
  23
  24 Advantages of the Module::Build approach:
  25
  26   - It's more in keeping with the standard way to distribute CPAN
  27     modules.
  28
  29   - It performs dependency checking to ensure you have the necessary
  30     Perl modules installed.
  31
  32 Basic Installation via Module::Build
  33 ====================================
  34
  35 The steps in building Stow are:
  36
  37 1.  `cd' to the directory containing the source code (and this file).
  38
  39 2.  If you are building from an official GNU release tarball, type
  40     `./configure && make' to configure stow for your system.  If you
  41     are building from a CPAN tarball, this step can be skipped.
  42
  43 3.  Type `perl Build.PL'.
  44
  45 4.  Type `./Build install' to install the various files.  As noted
  46     above, this installs fewer files than the Autotools installation.
  47
  48 Basic Installation via Autotools
  49 ================================
  50
  51 The steps in building Stow are:
  52
  53 1.  `cd' to the directory containing the source code (and this file).
  54
  55 2.  Type `./configure' to configure stow for your system.  This
  56     step will attempt to locate your copy of perl and set its location
  57     in `Makefile.in'.
  58
  59 3.  Type `make install' to install the various files.
  60
  61 4.  You can remove the generated files from the source code directory
  62     by typing `make clean'.  To also remove the files that `configure'
  63     created (so you can compile the package for a different computer),
  64     type `make distclean'.  There is also a `make maintainer-clean'
  65     target, but that is intended mainly for stow's developers.  If you
  66     use it, you may have to get all sorts of other programs in order
  67     to regenerate files that came with the distribution.
  68
  69 Installation Names
  70 ==================
  71
  72 By default, `make install' will install the package's files in
  73 `/usr/local/bin' and `/usr/local/info'.  You can specify an
  74 installation prefix other than `/usr/local' by giving `configure' the
  75 option `--prefix=PATH'.
  76
  77 If the package supports it, you can cause programs to be installed
  78 with an extra prefix or suffix on their names by giving `configure'
  79 the option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'.
  80
  81 Since `stow' is concerned with separating a package's installation
  82 tree from its run-time tree, you might want to install `stow' into a
  83 directory such as `/usr/local/stow/stow' but have it run out of
  84 `/usr/local'.  Do this by giving the run-time prefix (e.g.,
  85 /usr/local) to configure as described above; then run `make'; then run
  86 `make install prefix=/usr/local/stow/stow'.  For more information on
  87 this technique, see the Stow manual.
  88
  89 The configuration system
  90 ========================
  91
  92 The `configure' shell script attempts to guess correct values for
  93 various system-dependent variables used during compilation.  It uses
  94 those values to create a `Makefile' and to create the `stow' script
  95 itself, using Makefile.in and stow.in as templates.  Finally, it
  96 creates a shell script `config.status' that you can run in the future
  97 to recreate the current configuration, a file `config.cache' that
  98 saves the results of its tests to speed up reconfiguring, and a file
  99 `config.log' containing other output.
 100
 101 The file `configure.ac' is used to create `configure' by a program
 102 called `autoconf'.  You only need `configure.ac' if you want to change
 103 it or regenerate `configure' using a newer version of `autoconf'.
 104
 105 The file `Makefile.am' is used to create `Makefile.in' by a program
 106 called `automake'.  You only need `Makefile.am' if you want to change
 107 it or regenerate `Makefile.in' using a newer version of `automake'.
 108
 109 Sharing Defaults
 110 ================
 111
 112 If you want to set default values for `configure' scripts to share,
 113 you can create a site shell script called `config.site' that gives
 114 default values for variables like `CC', `cache_file', and `prefix'.
 115 `configure' looks for `PREFIX/share/config.site' if it exists, then
 116 `PREFIX/etc/config.site' if it exists.  Or, you can set the
 117 `CONFIG_SITE' environment variable to the location of the site script.
 118 A warning: not all `configure' scripts look for a site script.
 119
 120 Operation Controls
 121 ==================
 122
 123    `configure' recognizes the following options to control how it
 124 operates.
 125
 126 `--cache-file=FILE'
 127      Use and save the results of the tests in FILE instead of
 128      `./config.cache'.  Set FILE to `/dev/null' to disable caching, for
 129      debugging `configure'.
 130
 131 `--help'
 132      Print a summary of the options to `configure', and exit.
 133
 134 `--quiet'
 135 `--silent'
 136 `-q'
 137      Do not print messages saying which checks are being made.
 138
 139 `--srcdir=DIR'
 140      Look for the package's source code in directory DIR.  Usually
 141      `configure' can determine that directory automatically.
 142
 143 `--version'
 144      Print the version of Autoconf used to generate the `configure'
 145      script, and exit.
 146
 147 `configure' also accepts some other, not widely useful, options.
 148