improving INSTALL contents, take two

[Eric Blake]

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

A while ago, there was a thread on improving INSTALL, to which Ralf gave a
good summary:
http://lists.gnu.org/archive/html/autoconf/2009-05/msg00065.html

I intentionally have not visited that email for a couple months now, so
that when I went to write up the text today, my mind would have to visit
all of the points in that email in isolation.  I think the following patch
covers all the points raised back then.  Any objections before I push this?

> For whatever benefit, I will do the work to summarize the thread.
> Consider me vetoing any patch proposal on this subject that do not take
> into account *ALL* of the following points (not just some or most of
> them, but *ALL* of them; it's not that hard):
> 
> - The INSTALL file is supposed to be usable for all packages that either
>   use Autoconf, or use both Autoconf and Automake, or use none of them
>   but otherwise follow the GNU Coding Standards (thereafter dubbed GCS)
>   reasonably well.  This means you should not claim that anything works
>   unless it is guaranteed under each of the three situations, and it
>   should not guarantee GNUisms any more than useful for many developers.
>   Leveraging end-user documentation as a handle against developers is
>   just the wrong approach and will only lead to frustration.

I've tried to make it clear up front that INSTALL is a generic document,
and that not all packages provide all features.

> - DESTDIR support is described as optional in GCS.  This means that
>   developers can choose to not support it, and that users cannot rely on
>   it working.  INSTALL should thus not promise it without caution.
> 
> - DESTDIR cannot work with w32-style paths, at least not without *a lot*
>   of uglification code that would need to be done within Automake and
>   any hand-written (un)install rules.  The reason for this is that
>     ./configure --prefix=C:/usr/local
>     make
>     make install DESTDIR=C:/tmp
> 
>   will try to write to C:/tmpC:/usr/local, which is an illegal path on
>   w32 systems due to the second colon.  Thus INSTALL should not promise
>   that DESTDIR works on all operating systems.  Please note that some
>   w32 environments (such as Cygwin) allow you to use unix-style
>   `/paths', but not all of them do, and it won't work with so-called
>   "native apps" that don't link against Cygwin libraries, so one cannot
>   expect end users to be able to use them either.
> 
> - `make install prefix=...' diversion is not optional in GCS.  While it
>   may be conceptually uglier than the DESTDIR approach, it is the only
>   working one on w32, and it is recommended that developers support
>   this in their makefiles whenever possible.  (Even with this support in
>   place however, DESTDIR is simpler to use (whenever possible), as it
>   allows the user to forget which paths she overrode earlier; example:
>     ./configure --bindir=/foo --sysconfdir=/bar
>     make
> 
>   and then
>     make install prefix=/divert bindir=divert/foo sysconfdir=/divert/bar
> 
>   vs.
>     make install DESTDIR=/divert
> 
>   Of course the super-smart end-user could have used something like
>     ./configure --prefix=/ --bindir='${prefix}/foo' ...
> 
>   but I for one consider documenting this a bit over the top in INSTALL.
> 
> - The fact that DESTDIR does not work on w32 without Cygwin, does not
>   make DESTDIR unusable.  w32 may be an important system to many, but
>   many packages do not target w32, and the GCS explicitly allow GNU
>   packages to simply ignore anything w32-specific.  I'm not promoting
>   this actively, but it sure weakens any argument to remove DESTDIR
>   support from packages.
> 
> - In practice, unfortunately many packages using GNU Libtool do not
>   support
>      make install prefix=...
> 
>   diversion fully, unless the prefix ends in the string that was the
>   configured prefix (i.e., there are some libtool use cases which are
>   not supported).  This is a bug in Libtool, which can and will be fixed
>   eventually, but it will be some work and is probably not possible
>   fully transparently.  (BTW, this isn't all that big of a problem on
>   w32, as there, relinking of libraries is not necessary because there
>   is no library run path hardcoding on this system).  Details here are a
>   bit intricate, but not interesting for the discussion of the contents
>   of the INSTALL file.  What is interesting is that it would be nice if
>   the INSTALL file would not promise what a package could not hold.
> 
>   Yes, and of course another conclusion from this is that packages using
>   Libtool do not fully conform to GCS.  Sue Libtool, give me more time
>   for hacking so I can fix more bugs.
> 
> - If DESTDIR were documented in INSTALL, it would probably be useful
>   to mention that DESTDIR should be unset during the `./configure' and
>   the `make' stages, and should be used only at `make install' time.
> 
> - Developers are expected to never initialize the DESTDIR make macro
>   in any of the makefile files.  This allows the end user to portably
>   use
>     make install DESTDIR=...
> 
>   rather than having to resort to
>     env DESTDIR=... make -e install
> 
>   in order to avoid the issue with non-GNU make implementations
>   described in
>   
> <http://www.gnu.org/software/autoconf/manual/html_node/Macros-and-Submakes.html>.

I think I hit all of these points - the Installation Names node now
mentions both DESTDIR and 'make prefix= install' as two different methods,
and tries to list caveats for each.

> 
> - `./configure --help' is not really the best place to document things
>   that do not have anything to do with configure, but only with `make'.
>   Take into account that packages that use Autoconf may reasonably not
>   use `make' at all, but some other build tool like cmake, scons or so;
>   and we don't want `./configure --help' to contain generic contents
>   for all the possible build tools.
> 
> - It would be good if the silent-rules API
>   (--{disable,enable}-silent-rules, and V=0, V=1) were mentioned
>   somewhere.

Exactly why 'make V=0' is documented in INSTALL, not ./configure --help.

> - `make install FOO=VAL' should never alter anything in the build
>   directory; more precisely, it should be possible to install as a
>   different user than the one who ran `make all'.  (Libtool kind of
>   breaks this sometimes and on some systems, too, but only inside the
>   Libtool-private .libs (or _libs) subdirectories.  This will be fixed
>   in a future Libtool release.

Somewhat mentioned above.

> Further helpful information:
> 
> - The `make distcheck' provided by Automake rules tests DESTDIR support.
> 
> - Practice shows that even `make uninstall' is broken in many packages
>   (as an example of the level of GCS support that packages have in
>   practice, outside of well-exercised code paths).

Also mentioned in the basic information.

> 
> - With Automake 1.11, `make install bindir=""' will allow the end-user
>   to avoid installing any files in $bindir, but that is something I do
>   not think we should be documenting at this point either.  Previous
>   Automake versions would cause some error, or overwrite files in the
>   build directory, or, if DESTDIR=/foo were also set, put files
>   erroneously into /foo.
> 
> - s/Linux/GNU Linux/  of course, whereever applicable.
> 

- --
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

iEYEARECAAYFAkps/fQACgkQ84KuGfSFAYCshwCfZWMH36ra5MJ+ptpgM3ii68r6
g0QAnAu1dhLpjJnI4ooemWt57Q+tvUgw
=mnXI
-----END PGP SIGNATURE-----

>From eea15b967527c54e2b908e69f6c585b031b17212 Mon Sep 17 00:00:00 2001
From: Eric Blake <address@hidden>
Date: Sun, 26 Jul 2009 19:06:06 -0600
Subject: [PATCH] Document some optional features in INSTALL.

* doc/install.texi (Basic Installation): Mention that INSTALL is
generic, and that not all packages implement all features.
Mention 'make distcheck' for maintainers, and 'make installcheck'
for users.
(Installation Names): Mention DESTDIR vs. 'make prefix= install'
as ways to alter the configuration, with caveats of each.  Move
--program-prefix discussion...
(Optional Features): ...here.  Mention --enable-silent-rules and
use of make V=0.

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

diff --git a/ChangeLog b/ChangeLog
index e4619f0..c5a3dab 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,16 @@
 2009-07-26  Eric Blake  <address@hidden>

+       Document some optional features in INSTALL.
+       * doc/install.texi (Basic Installation): Mention that INSTALL is
+       generic, and that not all packages implement all features.
+       Mention 'make distcheck' for maintainers, and 'make installcheck'
+       for users.
+       (Installation Names): Mention DESTDIR vs. 'make prefix= install'
+       as ways to alter the configuration, with caveats of each.  Move
+       --program-prefix discussion...
+       (Optional Features): ...here.  Mention --enable-silent-rules and
+       use of make V=0.
+
        Basic improvements to INSTALL.
        * doc/install.texi (Basic Installation): Use better markup.
        (Multiple Architectures): Introduce the term VPATH.
diff --git a/doc/install.texi b/doc/install.texi
index abd710d..789a156 100644
--- a/doc/install.texi
+++ b/doc/install.texi
@@ -23,6 +23,11 @@ Basic Installation
 should configure, build, and install this package.  The following
 more-detailed instructions are generic; see the @file{README} file for
 instructions specific to this package.
address@hidden autoconf
+Some packages provide this @file{INSTALL} file but do not implement all
+of the features documented below.  The lack of an optional feature in a
+given package is not necessarily a bug.
address@hidden ifclear

 The @command{configure} shell script attempts to guess correct values
 for various system-dependent variables used during compilation.  It uses
@@ -66,11 +71,17 @@ Basic Installation

 @item
 Optionally, type @samp{make check} to run any self-tests that come with
-the package.
+the package, generally using the just-built uninstalled binaries.

 @item
 Type @samp{make install} to install the programs and any data files and
-documentation.
+documentation.  When installing into a prefix owned by root, it is
+recommended that the package be configured and built as a regular user,
+and only the @samp{make install} phase executed with root privileges.
+
address@hidden
+Optionally, type @samp{make installcheck} to repeat any self-tests, but
+this time using the binaries in their final installed location.

 @item
 You can remove the program binaries and object files from the source
@@ -84,7 +95,15 @@ Basic Installation

 @item
 Often, you can also type @samp{make uninstall} to remove the installed
-files again.
+files again.  In practice, not all packages have tested that
+uninstallation works correctly, even though it is required by the
address@hidden Coding Standards.
+
address@hidden
+Some packages, particularly those that use Automake, provide @samp{make
+distcheck}, which can by used by developers to test that all other
+targets like @samp{make install} and @samp{make uninstall} work
+correctly.  This target is generally not run by end users.
 @end enumerate

 @node Compilers and Options
@@ -159,16 +178,52 @@ 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.
+
+The most portable way to affect installation locations is to pass the
+correct locations to @command{configure}; however, many packages provide
+one or both of the following shortcuts to change installation locations
+without having to reconfigure or recompile.
+
+The first method involves passing additional @command{make} variables
+for each affected directory as part of the command line to @samp{make
+install}.  For example, @samp{make install prefix=/path/to/alternate}
+will choose an alternate location, as well as influencing all other
+directory configuration variables that were expressed in terms of
address@hidden@address@hidden (or, put another way, all directories specified
+during @command{configure} but not in terms of the common prefix must
+each be overridden at install time for the entire installation to be
+relocated).  The approach of makefile variable overrides for each
+directory variable is required by the @acronym{GNU} Coding Standards,
+and ideally causes no recompilation.  However, some platforms have known
+limitations with the semantics of shared libraries that end up requiring
+recompilation when using this method, particularly noticeable in
+packages that use @acronym{GNU} Libtool.
+
+The second method involves assigning the @command{make} variable
address@hidden as part of the command line to @samp{make install}.  For
+example, @samp{make install DESTDIR=/path/to/alternate} will prepend
address@hidden/path/to/alternate} before all installation paths.  The approach
+of @samp{DESTDIR} overrides is not required by the @acronym{GNU} Coding
+Standards, and does not work on platforms that have drive letters.  On
+the other hand, it does better at avoiding recompilation issues, and
+works well regardless of whether any directory options were not
+specified in terms of the common prefix at @command{configure} time.
+For packages which support @samp{DESTDIR}, the variable should remain
+undefined during @command{configure} and @samp{make all}, and only be
+specified during @samp{make install}.
+
address@hidden Optional Features
address@hidden Optional Features

 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}
 the option @address@hidden or
 @address@hidden

address@hidden Optional Features
address@hidden Optional Features
-
 Some packages pay attention to @address@hidden options
 to @command{configure}, where @var{feature} indicates an optional part
 of the package.  They may also pay attention to
@@ -183,6 +238,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.3.334.g916e1