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
 109 Installation Names
 110 ------------------
 111
 112 By default, `make install` will install the package's files in
 113 `/usr/local/bin` and `/usr/local/info`.  You can specify an
 114 installation prefix other than `/usr/local` by giving `configure` the
 115 option `--prefix=PATH`.
 116
 117 If the package supports it, you can cause programs to be installed
 118 with an extra prefix or suffix on their names by giving `configure`
 119 the option `--program-prefix=PREFIX` or `--program-suffix=SUFFIX`.
 120
 121 Since `stow` is concerned with separating a package's installation
 122 tree from its run-time tree, you might want to install `stow` into a
 123 directory such as `/usr/local/stow/stow` but have it run out of
 124 `/usr/local`.  Do this by giving the run-time prefix (e.g.,
 125 /usr/local) to configure as described above; then run `make`; then run
 126 `make install prefix=/usr/local/stow/stow`.  For more information on
 127 this technique, see the Stow manual.
 128
 129 The configuration system
 130 ------------------------
 131
 132 The `configure` shell script attempts to guess correct values for
 133 various system-dependent variables used during compilation.  It uses
 134 those values to create a `Makefile` and to create the `stow` script
 135 itself, using Makefile.in and stow.in as templates.  Finally, it
 136 creates a shell script `config.status` that you can run in the future
 137 to recreate the current configuration, a file `config.cache` that
 138 saves the results of its tests to speed up reconfiguring, and a file
 139 `config.log` containing other output.
 140
 141 The file `configure.ac` is used to create `configure` by a program
 142 called `autoconf`.  You only need `configure.ac` if you want to change
 143 it or regenerate `configure` using a newer version of `autoconf`.
 144
 145 The file `Makefile.am` is used to create `Makefile.in` by a program
 146 called `automake`.  You only need `Makefile.am` if you want to change
 147 it or regenerate `Makefile.in` using a newer version of `automake`.
 148
 149 Sharing Defaults
 150 ----------------
 151
 152 If you want to set default values for `configure` scripts to share,
 153 you can create a site shell script called `config.site` that gives
 154 default values for variables like `CC`, `cache_file`, and `prefix`.
 155 `configure` looks for `PREFIX/share/config.site` if it exists, then
 156 `PREFIX/etc/config.site` if it exists.  Or, you can set the
 157 `CONFIG_SITE` environment variable to the location of the site script.
 158 A warning: not all `configure` scripts look for a site script.
 159
 160 Operation Controls
 161 ------------------
 162
 163 `configure` recognizes the following options to control how it
 164 operates.
 165
 166 `--cache-file=FILE`
 167      Use and save the results of the tests in FILE instead of
 168      `./config.cache`.  Set FILE to `/dev/null` to disable caching, for
 169      debugging `configure`.
 170
 171 `--help`
 172      Print a summary of the options to `configure`, and exit.
 173
 174 `--quiet`
 175 `--silent`
 176 `-q`
 177      Do not print messages saying which checks are being made.
 178
 179 `--srcdir=DIR`
 180      Look for the package's source code in directory DIR.  Usually
 181      `configure` can determine that directory automatically.
 182
 183 `--version`
 184      Print the version of Autoconf used to generate the `configure`
 185      script, and exit.
 186
 187 `configure` also accepts some other, not widely useful, options.
 188
 189 Cleaning up build files
 190 -----------------------
 191
 192 You can remove the generated files from the source code directory by
 193 typing `make clean`.  To also remove the files that `configure`
 194 created (so you can compile the package for a different computer),
 195 type `make distclean`.  There is also a `make maintainer-clean`
 196 target, but that is intended mainly for stow's developers.  If you use
 197 it, you may have to get all sorts of other programs in order to
 198 regenerate files that came with the distribution.
 199
 200 License for this file
 201 ---------------------
 202
 203 Copying and distribution of this file, with or without modification,
 204 are permitted in any medium without royalty provided the copyright
 205 notice and this notice are preserved.  This file is offered as-is,
 206 without any warranty.