Re: improve INSTALL contents

[Ralf Wildenhues]

Hello Jim, Alfred,

* Jim Meyering wrote on Sun, May 17, 2009 at 03:50:18PM CEST:
> [I've dropped Cc'd coreutils and automake lists]

Thanks.

> Alfred M. Szmidt wrote:
> >    can you please also read, and follow
> >    <http://lists.gnu.org/archive/html/autoconf/2009-05/msg00058.html>?
> >    I'm sure you must have missed it because I failed to spam it to
> >    three mailing lists.  But your repetitions are just as boring as
> >    those from everyone else.  And get bug-coreutils and automake off
> >    the recipients lists!
> >
> > I do not see what point you are trying to make.  And please be more
> > polite in the future.

> I believe his point is that this thread seems disproportionately
> long (and cross-posted too widely) for the small potential benefit,
> if ever something comes of it.

That is one point.

> If you want to pursue, please try to keep to the topic at hand
> and propose precise new wording, or maybe better, just table it for now.
> Objection without conter-proposal is a recipe for never-ending debate.

Well, objection per se is ok.  But not taking into account all that has
already been discussed is being impolite to all list readers.

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.

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

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

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


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

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



Now, the above is what I got when going through the whole thread once
again (plus a couple more bits that I could think of).  All patch
proposals so far have failed to take into account one or more of the
points mentioned.  Several mails in this thread have dealt with the same
issues twice or more times.  It's as if people ask questions but don't
read answers, and that is what is very impolite towards other people on
this mailing list.  Even more so when done from non-newbies.  I don't
expect newbies to be this diligent.

I hope this clears everything up.

Cheers,
Ralf