From 4feff09211081c9423d933944620808b3d98b43b Mon Sep 17 00:00:00 2001 From: Adam Spiers Date: Mon, 16 Nov 2015 22:21:44 +0000 Subject: [PATCH] convert INSTALL to Markdown --- INSTALL | 172 ---------------------------------------------------- INSTALL.md | 175 +++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 2 +- 3 files changed, 176 insertions(+), 173 deletions(-) delete mode 100644 INSTALL create mode 100644 INSTALL.md diff --git a/INSTALL b/INSTALL deleted file mode 100644 index d00e279..0000000 --- a/INSTALL +++ /dev/null @@ -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. - 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. + diff --git a/README.md b/README.md index 9d0a5f1..4f8e816 100644 --- a/README.md +++ b/README.md @@ -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 --------