convert INSTALL to Markdown
This commit is contained in:
Adam Spiers
parent
589da27138
commit
4feff09211
3 changed files with 176 additions and 173 deletions
172
INSTALL
172
INSTALL
|
|
@ -1,172 +0,0 @@
|
|||
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.
|
||||
|
||||
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. Type `perl Build.PL'.
|
||||
|
||||
4. 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. 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.
|
||||
|
||||
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.
|
||||
|
||||
175
INSTALL.md
Normal file
175
INSTALL.md
Normal file
|
|
@ -0,0 +1,175 @@
|
|||
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.
|
||||
|
||||
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. Type `perl Build.PL`.
|
||||
|
||||
4. 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. 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.
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -31,7 +31,7 @@ which can be found in the file [`COPYING`](COPYING).
|
|||
Installation
|
||||
------------
|
||||
|
||||
See [`INSTALL`](INSTALL) for installation instructions.
|
||||
See [`INSTALL.md`](INSTALL.md) for installation instructions.
|
||||
|
||||
Feedback
|
||||
--------
|
||||
|
|
|
|||
Loading…
Reference in a new issue