convert INSTALL to Markdown

1 files changed, 175 insertions, 0 deletions

diff --git a/INSTALL.md b/INSTALL.md
new file mode 100644
index 0000000..f962755
--- /dev/null
+++ b/INSTALL.md
@@ -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.
+