unstow_node / unstow_existing_node: rename foldable return value
[gnu-stow.git] / INSTALL.md
bloba85ad871a9090ebd3fce70b394a863580ceb463c
1 How to install GNU Stow
2 =======================
4 Prerequisites
5 -------------
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.
13 Installation methods
14 --------------------
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.
20 Advantages of the Autotools approach:
22   - It's arguably more flexible.
24   - It will install the documentation in Info, HTML, man, and PDF
25     formats.
27 Advantages of the `Module::Build` approach:
29   - It's more in keeping with the standard way to distribute CPAN
30     modules.
32   - It performs dependency checking to ensure you have the necessary
33     Perl modules installed.
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:
39 Preparatory steps required only when building from git
40 ------------------------------------------------------
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.
47 First `cd` to the directory containing the source code (and this
48 file), and then run:
50     autoreconf -iv
52 If this runs successfully then you are ready to continue with one of
53 the two installation methods below.
55 Basic Installation via `Module::Build`
56 --------------------------------------
58 The steps in building Stow are:
60 1.  `cd` to the directory containing the source code (and this file).
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.
66     If `make` warns that the Perl module installation directory is
67     not in `@INC`, then you should run:
69         eval `perl -V:siteprefix`
70         ./configure --prefix=$siteprefix && make
72     to avoid a superfluous `use lib` line in your stow executable.
74 3.  Type `perl Build.PL`.
76 4.  Type `./Build install` to install the various files.  As noted
77     above, this installs fewer files than the Autotools installation.
79 Basic Installation via Autotools
80 --------------------------------
82 The steps in building Stow are:
84 1.  `cd` to the directory containing the source code (and this file).
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
92         --with-pmdir=/path/to/perl/modules
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.
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
103         use lib "...";
105     line into the generated stow script to ensure that it can always
106     locate the Perl modules without needing to manually set `PERL5LIB`.
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.
116 Installation Names
117 ------------------
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`.
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`.
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.
136 The configuration system
137 ------------------------
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.
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`.
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`.
156 Sharing Defaults
157 ----------------
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.
167 Operation Controls
168 ------------------
170 `configure` recognizes the following options to control how it
171 operates.
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`.
178 `--help`
179      Print a summary of the options to `configure`, and exit.
181 `--quiet`
182 `--silent`
183 `-q`
184      Do not print messages saying which checks are being made.
186 `--srcdir=DIR`
187      Look for the package's source code in directory DIR.  Usually
188      `configure` can determine that directory automatically.
190 `--version`
191      Print the version of Autoconf used to generate the `configure`
192      script, and exit.
194 `configure` also accepts some other, not widely useful, options.
196 License for this file
197 ---------------------
199 Copying and distribution of this file, with or without modification,
200 are permitted in any medium without royalty provided the copyright
201 notice and this notice are preserved.  This file is offered as-is,
202 without any warranty.