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