Re: improving INSTALL contents, take two

[Eric Blake]

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

According to Alfred M. Szmidt on 7/29/2009 12:51 AM:

Sorry for taking so long to revisit this email.

>    address@hidden
>    +Optionally, type @samp{make installcheck} to repeat any self-tests, but
>    +this time using the binaries in their final installed location.
> 
> Maybe mention that installcheck should be run as a normal user, and
> that it doesn't install anything?

Sounds reasonable.

> 
>     @item
>    @@ -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.
> 
> `..., unless they are explicitly declared as well.'?

Yes, that aids reading.

> 
>    +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}
> 
> A very minor nitpick, we use the word `path' to mean a list of
> directories to search through, not an single directory.  The above
> would be clearer with `prefix=/installation/directory'.

Good point.  Done.

> 
>    +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.  
> 
> I find this paragraph extremely confusing, and am not entierly sure
> what is being said.

I hope the tweaked wording addresses this.  I didn't opt for an example,
as the paragraph is already quite long.  The idea is that:

./configure --prefix=/dir/a --bindir=/dir/b

implies that you must use:

make install prefix=/stage/dir/a bindir=/stage/dir/b

if you want to simulate DESTDIR=/stage via make variable overrides.

>    +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}.
> 
> Does anyone know of a package that gets affected during
> configure/install time by DESTDIR?  I find the aboe a bit confusing,
> and think that it might be worth not mentioning it at all.

On review, I agree - that sentence is more of a how-to to the package
maintainer ("don't do this, or your user's can't use DESTDIR"), not to the
person installing the built package.  I removed it.

> I feel a bit like a kid who got a nice lollipop, and is complaining
> that it is to sweet when I write this.

And I feel sorry for not listening to your complaint months ago ;)  Hope
the new version is even better!

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

iEYEARECAAYFAkrXHUoACgkQ84KuGfSFAYBdOQCeIDfbekdhtFXWdMAcasazye/u
T5QAnRULelLc3bDq8+GNzay3MwGqSeUM
=2GRG
-----END PGP SIGNATURE-----

>From 2b3da72ef3f4a226d9e1529e788e23f025e92118 Mon Sep 17 00:00:00 2001
From: Eric Blake <address@hidden>
Date: Thu, 15 Oct 2009 07:00:38 -0600
Subject: [PATCH] Improve INSTALL wording.

* doc/install.texi (Basic Installation): Clarify installcheck
behavior.
(Installation Names): Mention that --prefix only overrides
directory locations not specified on the command line.  Prefer
/alternate/directory over /path/to.  Remove a sentence targeted to
the developer, not the user.
* THANKS: Update.
Suggested by Alfred M. Szmidt.

Signed-off-by: Eric Blake <address@hidden>
---
 ChangeLog        |   12 ++++++++++++
 doc/install.texi |   31 ++++++++++++++++---------------
 2 files changed, 28 insertions(+), 15 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 074546c..2cd033f 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,15 @@
+2009-10-15  Eric Blake  <address@hidden>
+
+       Improve INSTALL wording.
+       * doc/install.texi (Basic Installation): Clarify installcheck
+       behavior.
+       (Installation Names): Mention that --prefix only overrides
+       directory locations not specified on the command line.  Prefer
+       /alternate/directory over /path/to.  Remove a sentence targeted to
+       the developer, not the user.
+       * THANKS: Update.
+       Suggested by Alfred M. Szmidt.
+
 2009-10-15  Peter Breitenlohner  <address@hidden>

        Fix typos in documentation.
diff --git a/doc/install.texi b/doc/install.texi
index 4f3301f..5ce59eb 100644
--- a/doc/install.texi
+++ b/doc/install.texi
@@ -84,7 +84,10 @@ Basic Installation

 @item
 Optionally, type @samp{make installcheck} to repeat any self-tests, but
-this time using the binaries in their final installed location.
+this time using the binaries in their final installed location.  This
+target does not install anything.  Running this target as a regular
+user, particlarly if the prior @samp{make install} required root
+privileges, verifies that the installation completed correctly.

 @item
 You can remove the program binaries and object files from the source
@@ -169,7 +172,7 @@ Installation Names
 You can specify an
 installation prefix other than @file{/usr/local} by giving
 @command{configure} the option @address@hidden, where
address@hidden must be an absolute path.
address@hidden must be an absolute file name.

 You can specify separate installation prefixes for architecture-specific
 files and architecture-independent files.  If you pass the option
@@ -184,7 +187,8 @@ Installation Names
 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@}}, so that specifying just @option{--prefix} will
-affect all of the other directory specifications.
+affect all of the other directory specifications that were not
+explicitly provided.

 The most portable way to affect installation locations is to pass the
 correct locations to @command{configure}; however, many packages provide
@@ -194,12 +198,12 @@ Installation Names

 The first method involves providing an override variable for each
 affected directory.  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@}} (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
+prefix=/alternate/directory} will choose an alternate location for all
+directory configuration variables that were expressed in terms of
address@hidden@address@hidden  Any directories that were specified during
address@hidden, 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
@@ -207,16 +211,13 @@ Installation Names
 noticeable in packages that use @acronym{GNU} Libtool.

 The second method involves providing the @samp{DESTDIR} variable.  For
-example, @samp{make install DESTDIR=/path/to/alternate} will prepend
address@hidden/path/to/alternate} before all installation paths.  The approach
+example, @samp{make install DESTDIR=/alternate/directory} will prepend
address@hidden/alternate/directory} before all installation names.  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 even when some directory options were not specified in terms
-of @address@hidden@}} at @command{configure} time.  For packages which
-support @samp{DESTDIR}, the variable should remain undefined during
address@hidden and @samp{make all}, and only be specified during
address@hidden install}.
+of @address@hidden@}} at @command{configure} time.

 @node Optional Features
 @section Optional Features
-- 
1.6.5.rc1