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 Both approaches are described in detail below.  However if you are
  36 building from the git repository rather than an official release,
  37 you first need to perform some extra steps:
  38
  39 Preparatory steps required only when building from git
  40 ------------------------------------------------------
  41
  42 `configure` and `Makefile` are included in official releases of Stow,
  43 but they are deliberately omitted from the git repository because they
  44 are autogenerated.  Therefore if you are installing directly from git,
  45 you first need to generate them as follows.
  46
  47 First `cd` to the directory containing the source code (and this
  48 file), and then run:
  49
  50     autoreconf -iv
  51
  52 If this runs successfully then you are ready to continue with one of
  53 the two installation methods below.
  54
  55 Basic Installation via `Module::Build`
  56 --------------------------------------
  57
  58 The steps in building Stow are:
  59
  60 1.  `cd` to the directory containing the source code (and this file).
  61
  62 2.  If you are building from an official GNU release tarball, type
  63     `./configure && make` to configure stow for your system.  If you
  64     are building from a CPAN tarball, this step can be skipped.
  65
  66     If `make` warns that the Perl module installation directory is
  67     not in `@INC`, then you should run:
  68
  69         eval `perl -V:siteprefix`
  70         ./configure --prefix=$siteprefix && make
  71
  72     to avoid a superfluous `use lib` line in your stow executable.
  73
  74 3.  Type `perl Build.PL`.
  75
  76 4.  Type `./Build install` to install the various files.  As noted
  77     above, this installs fewer files than the Autotools installation.
  78
  79 Basic Installation via Autotools
  80 --------------------------------
  81
  82 The steps in building Stow are:
  83
  84 1.  `cd` to the directory containing the source code (and this file).
  85
  86 2.  Type `./configure` to configure stow for your system.  This step
  87     will attempt to locate your copy of perl and set its location in
  88     `Makefile.in`.  You can use the normal arguments to change the
  89     default installation paths (see below); additionally you can use
  90     the
  91
  92         --with-pmdir=/path/to/perl/modules
  93
  94     option to manually choose where the Perl modules get installed.
  95     However, if you don't, the `configure` script will go to great
  96     lengths to try to choose a sensible default.
  97
  98 3.  Type `make install` to install the various files.  If the chosen
  99     installation directory for Perl modules is not included in Perl's
 100     built-in `@INC` search path, the Makefile rules will automatically
 101     insert a
 102
 103         use lib "...";
 104
 105     line into the generated stow script to ensure that it can always
 106     locate the Perl modules without needing to manually set `PERL5LIB`.
 107
 108 4.  You can remove the generated files from the source code directory
 109     by typing `make clean`.  To also remove the files that `configure`
 110     created (so you can compile the package for a different computer),
 111     type `make distclean`.  There is also a `make maintainer-clean`
 112     target, but that is intended mainly for stow's developers.  If you
 113     use it, you may have to get all sorts of other programs in order
 114     to regenerate files that came with the distribution.
 115
 116 Installation Names
 117 ------------------
 118
 119 By default, `make install` will install the package's files in
 120 `/usr/local/bin` and `/usr/local/info`.  You can specify an
 121 installation prefix other than `/usr/local` by giving `configure` the
 122 option `--prefix=PATH`.
 123
 124 If the package supports it, you can cause programs to be installed
 125 with an extra prefix or suffix on their names by giving `configure`
 126 the option `--program-prefix=PREFIX` or `--program-suffix=SUFFIX`.
 127
 128 Since `stow` is concerned with separating a package's installation
 129 tree from its run-time tree, you might want to install `stow` into a
 130 directory such as `/usr/local/stow/stow` but have it run out of
 131 `/usr/local`.  Do this by giving the run-time prefix (e.g.,
 132 /usr/local) to configure as described above; then run `make`; then run
 133 `make install prefix=/usr/local/stow/stow`.  For more information on
 134 this technique, see the Stow manual.
 135
 136 The configuration system
 137 ------------------------
 138
 139 The `configure` shell script attempts to guess correct values for
 140 various system-dependent variables used during compilation.  It uses
 141 those values to create a `Makefile` and to create the `stow` script
 142 itself, using Makefile.in and stow.in as templates.  Finally, it
 143 creates a shell script `config.status` that you can run in the future
 144 to recreate the current configuration, a file `config.cache` that
 145 saves the results of its tests to speed up reconfiguring, and a file
 146 `config.log` containing other output.
 147
 148 The file `configure.ac` is used to create `configure` by a program
 149 called `autoconf`.  You only need `configure.ac` if you want to change
 150 it or regenerate `configure` using a newer version of `autoconf`.
 151
 152 The file `Makefile.am` is used to create `Makefile.in` by a program
 153 called `automake`.  You only need `Makefile.am` if you want to change
 154 it or regenerate `Makefile.in` using a newer version of `automake`.
 155
 156 Sharing Defaults
 157 ----------------
 158
 159 If you want to set default values for `configure` scripts to share,
 160 you can create a site shell script called `config.site` that gives
 161 default values for variables like `CC`, `cache_file`, and `prefix`.
 162 `configure` looks for `PREFIX/share/config.site` if it exists, then
 163 `PREFIX/etc/config.site` if it exists.  Or, you can set the
 164 `CONFIG_SITE` environment variable to the location of the site script.
 165 A warning: not all `configure` scripts look for a site script.
 166
 167 Operation Controls
 168 ------------------
 169
 170 `configure` recognizes the following options to control how it
 171 operates.
 172
 173 `--cache-file=FILE`
 174      Use and save the results of the tests in FILE instead of
 175      `./config.cache`.  Set FILE to `/dev/null` to disable caching, for
 176      debugging `configure`.
 177
 178 `--help`
 179      Print a summary of the options to `configure`, and exit.
 180
 181 `--quiet`
 182 `--silent`
 183 `-q`
 184      Do not print messages saying which checks are being made.
 185
 186 `--srcdir=DIR`
 187      Look for the package's source code in directory DIR.  Usually
 188      `configure` can determine that directory automatically.
 189
 190 `--version`
 191      Print the version of Autoconf used to generate the `configure`
 192      script, and exit.
 193
 194 `configure` also accepts some other, not widely useful, options.
 195