improve INSTALL contents (was: Core-utils 7.2; building only 'su')

[Eric Blake]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

According to Eric Blake on 4/15/2009 5:51 AM:
>> Maybe the generic INSTALL file should provide pointers to more
>> comprehensive documentation?
> 
> I tend to agree that INSTALL should either mention DESTDIR (and probably
> also V, which now plays a role with new enough automake), or at least
> point to the GNU Coding Standards and the Automake manual overview of the
> GNU build system.  Does anyone want to beat me to a patch?

Comments before I apply this to autoconf?

- --
Don't work too hard, make some time for fun as well!

Eric Blake             address@hidden
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (Cygwin)
Comment: Public key at home.comcast.net/~ericblake/eblake.gpg
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAkoKwlYACgkQ84KuGfSFAYBxaACgpcO1oGS3YdLJFDAhyt5sq2hm
KAEAniZgDkg4MU8GowDA83eVO+aq0xaS
=sYDO
-----END PGP SIGNATURE-----

>From a59b2a274edeaa8b5eef00462bb187223ad03a0e Mon Sep 17 00:00:00 2001
From: Eric Blake <address@hidden>
Date: Mon, 4 May 2009 16:56:42 -0600
Subject: [PATCH] Add more meat to INSTALL.

* doc/install.texi (Optional Features): Mention recent automake's
implementation of silent rules.
(Installation Names): Mention DESTDIR installation.
(Multiple Architectures): Mention the term VPATH.
(Basic Installation): Fix markup.

Signed-off-by: Eric Blake <address@hidden>
---
 ChangeLog        |    7 +++++++
 doc/install.texi |   39 +++++++++++++++++++++++++++++++++------
 2 files changed, 40 insertions(+), 6 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 88f4171..e9b4858 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,12 @@
 2009-05-13  Eric Blake  <address@hidden>

+       Add more meat to INSTALL.
+       * doc/install.texi (Optional Features): Mention recent automake's
+       implementation of silent rules.
+       (Installation Names): Mention DESTDIR installation.
+       (Multiple Architectures): Mention the term VPATH.
+       (Basic Installation): Fix markup.
+
        Document zsh bug with empty commands.
        * doc/autoconf.texi (Special Shell Variables) <?>: Add mention of
        more problems with $?.
diff --git a/doc/install.texi b/doc/install.texi
index a51882c..00897d2 100644
--- a/doc/install.texi
+++ b/doc/install.texi
@@ -45,16 +45,16 @@ Basic Installation
 want to keep, you may remove or edit it.

 The file @file{configure.ac} (or @file{configure.in}) is used to create
address@hidden by a program called @code{autoconf}.  You need
address@hidden by a program called @command{autoconf}.  You need
 @file{configure.ac} if you want to change it or regenerate
address@hidden using a newer version of @code{autoconf}.
address@hidden using a newer version of @command{autoconf}.

 @noindent
 The simplest way to compile this package is:

 @enumerate
 @item
address@hidden to the directory containing the package's source code and type
address@hidden to the directory containing the package's source code and type
 @samp{./configure} to configure the package for your system.

 Running @command{configure} might take a while.  While running, it prints some
@@ -113,7 +113,8 @@ Multiple Architectures
 @command{cd} to the directory where you want the object files and
 executables to go and run the @command{configure} script.
 @command{configure} automatically checks for the source code in the
-directory that @command{configure} is in and in @file{..}.
+directory that @command{configure} is in and in @file{..}.  This is
+known as a @dfn{VPATH} build.

 With a address@hidden @command{make},
 it is safer to compile the package for one
@@ -144,7 +145,8 @@ Installation Names
 @file{/usr/local/bin}, include files under @file{/usr/local/include}, etc.
 You can specify an
 installation prefix other than @file{/usr/local} by giving
address@hidden the option @address@hidden
address@hidden the option @address@hidden, where
address@hidden must be an absolute path.

 You can specify separate installation prefixes for architecture-specific
 files and architecture-independent files.  If you pass the option
@@ -156,7 +158,25 @@ Installation Names
 In addition, if you use an unusual directory layout you can give options
 like @address@hidden to specify different values for
 particular kinds of files.  Run @samp{configure --help} for a list of
-the directories you can set and what kinds of files go in them.
+the directories you can set and what kinds of files go in them.  In
+general, the default for these options is expressed in terms of
address@hidden@address@hidden, so that specifying just @option{--prefix} will
+affect all of the other directory specifications.
+
+Depending on the package, the default directory layout chosen during
address@hidden can be altered during subsequent execution of
address@hidden  For example, the command @samp{make
+prefix=/path/to/alternate} will choose an alternate prefix, and
+additionally impact all configuration variables that were expressed in
+terms of @address@hidden@}}.  However, some programs need to know at
+compile time where files will be installed, so the user should ensure
+that the same directory choice is made for both @samp{make all} and
address@hidden install}.  Some packages also support installation into a
+staging area, via @samp{make address@hidden install}.  If your
address@hidden does not understand arguments containing variable
+assignments, you can try @samp{env address@hidden make -e install},
+although you must then be careful of any other environment variables
+affecting @command{make} behavior.

 If the package supports it, you can cause programs to be installed with
 an extra prefix or suffix on their names by giving @command{configure}
@@ -180,6 +200,13 @@ Optional Features
 @address@hidden and @address@hidden to
 specify their locations.

+Some packages offer the ability to configure how verbose the execution
+of @command{make} will be.  For these packages, running
address@hidden/configure --enable-silent-rules} sets the default to minimal
+output, which can be overridden with @code{make V=1}; while running
address@hidden/configure --disable-silent-rules} sets the default to verbose,
+which can be overridden with @code{make V=0}.
+
 @node Particular Systems
 @section Particular systems

-- 
1.6.3.rc3.2.g4b51