INSTALL.md

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