Patch to INSTALL.CVS to clarify why `make bootstrap' sometimes fails.

Patch to INSTALL.CVS to clarify why `make bootstrap' sometimes fails.

[Alan Mackenzie]

Hi, again!

I would like to install the following patch to INSTALL.CVS.  This
clarifies the failure of `make bootstrap' to the point where even I
would have understood it.

Any objections?




2008-06-07  Alan Mackenzie  <acm@muc.de>

	* INSTALL.CVS: Clarify why `make bootstrap' sometimes fails.


Index: INSTALL.CVS
===================================================================
RCS file: /cvsroot/emacs/emacs/INSTALL.CVS,v
retrieving revision 1.18
diff -c -r1.18 INSTALL.CVS
*** INSTALL.CVS	7 May 2008 07:35:40 -0000	1.18
--- INSTALL.CVS	7 Jun 2008 09:47:51 -0000
***************
*** 14,25 ****
    $ make bootstrap
  
  The bootstrap process makes sure all necessary files are rebuilt
! before it builds the final Emacs binary.
  
! If 'make bootstrap' fails, it may be necessary to do 'make maintainer-clean'
! followed by configure before trying it again.  (Occasionally the loaddefs.el
! file gets into a bad state due to changes in the Lisp libraries; this procedure
! forces it to be regenerated.)
  
  Normally, it is not necessary to use "make bootstrap" after every CVS
  update.  Unless there are problems, we suggest using the following
--- 14,27 ----
    $ make bootstrap
  
  The bootstrap process makes sure all necessary files are rebuilt
! before it builds the final Emacs binary.  It doesn't always work when
! there are stale files from a previous build in the directory tree.
  
! So if 'make bootstrap' fails, it may be necessary first to do 'make
! maintainer-clean' to clear out these stale files.  You can then try
! again, starting with `./configure'.  (Occasionally the loaddefs.el
! file gets into a bad state due to changes in the Lisp libraries; this
! procedure forces it to be regenerated.)
  
  Normally, it is not necessary to use "make bootstrap" after every CVS
  update.  Unless there are problems, we suggest using the following



-- 
Alan Mackenzie (Nuremberg, Germany).

Re: Patch to INSTALL.CVS to clarify why `make bootstrap' sometimes fails.

[Eli Zaretskii]

> Date: Sat, 7 Jun 2008 10:14:46 +0000
> From: Alan Mackenzie <acm@muc.de>
> 
> I would like to install the following patch to INSTALL.CVS.  This
> clarifies the failure of `make bootstrap' to the point where even I
> would have understood it.
> 
> Any objections?

Looks fine to me, but please wait for at least Stefan and Yidong to
approve, and possibly also Glenn.

Thanks.

Re: Patch to INSTALL.CVS to clarify why `make bootstrap' sometimes fails.

[Stefan Monnier]

> Any objections?

Yes.
  
> ! So if 'make bootstrap' fails, it may be necessary first to do 'make
> ! maintainer-clean' to clear out these stale files.  You can then try
> ! again, starting with `./configure'.  (Occasionally the loaddefs.el
> ! file gets into a bad state due to changes in the Lisp libraries; this
> ! procedure forces it to be regenerated.)

[ Alan, this is not aimed at you. ]
Rather than improve the documentation of our Makefile's brokenness,
e should fix the beast.  E.g. `make bootstrap' should begin by doing
a `maintainer-clean'.


        Stefan

Re: Patch to INSTALL.CVS to clarify why `make bootstrap' sometimes fails.

[Miles Bader]

Stefan Monnier <monnier@iro.umontreal.ca> writes:
> Rather than improve the documentation of our Makefile's brokenness,
> e should fix the beast.  E.g. `make bootstrap' should begin by doing
> a `maintainer-clean'.

Doesn't that remove configure/Makefile/...?!

[Removing those seems unnecessary and annoying/dangerous-if-you're-making...]

-Miles

-- 
Learning, n. The kind of ignorance distinguishing the studious.

Re: Patch to INSTALL.CVS to clarify why `make bootstrap' sometimes fails.

[Glenn Morris]

Alan Mackenzie wrote:

> I would like to install the following patch to INSTALL.CVS.  This
> clarifies the failure of `make bootstrap' to the point where even I
> would have understood it.

You can add whatever documentation you like. It's already been
established that people won't read it.

Re: Patch to INSTALL.CVS to clarify why `make bootstrap' sometimes fails.

[Glenn Morris]

Stefan Monnier wrote:

> Rather than improve the documentation of our Makefile's brokenness,
> e should fix the beast.  E.g. `make bootstrap' should begin by doing
> a `maintainer-clean'.

I already made it run autogen-clean, which should fix the autoload issue.
More I think might be overkill.

But do what you like. People will still build some other way and get
all huffy when it fails.

Re: Patch to INSTALL.CVS to clarify why `make bootstrap' sometimes fails.

[Stefan Monnier]

>> Rather than improve the documentation of our Makefile's brokenness,
>> we should fix the beast.  E.g. `make bootstrap' should begin by doing
>> a `maintainer-clean'.
> Doesn't that remove configure/Makefile/...?!

Well, maybe you shouldn't take the above too literally.

> [Removing those seems unnecessary and annoying/dangerous-if-you're-making...]

Indeed, you wouldn't want to do that in maintainer-clean.
But maintainer-clean does more, otherwise it wouldn't be useful before
running ./configure.


        Stefan

Re: Patch to INSTALL.CVS to clarify why `make bootstrap' sometimes fails.

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Sat, 07 Jun 2008 14:40:11 -0400
> Cc: emacs-devel@gnu.org
> 
> `make bootstrap' should begin by doing a `maintainer-clean'.

And then what does one do if a bootstrap fails half-way through, and
one wants to continue it after fixing the problem?

Re: Patch to INSTALL.CVS to clarify why `make bootstrap' sometimes fails.

[David Kastrup]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Stefan Monnier <monnier@iro.umontreal.ca>
>> Date: Sat, 07 Jun 2008 14:40:11 -0400
>> Cc: emacs-devel@gnu.org
>> 
>> `make bootstrap' should begin by doing a `maintainer-clean'.
>
> And then what does one do if a bootstrap fails half-way through, and
> one wants to continue it after fixing the problem?

That's an expert operation with tripup potential.  The default bootstrap
should just work, however slowly.

Maybe we should add a target "continue-bootstrap" if this occurs often
enough to make people want it.

Anyway, maintainer-clean does too much: it kills the record of how I ran
configure the last time.  If we had a "bootstrap-clean", that would
possibly already help.

Of course, all of these are extra targets and extra doc.  But I think
that the default bootstrap should be rather safe than sorry.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Patch to INSTALL.CVS to clarify why `make bootstrap' sometimes fails.

[Eli Zaretskii]

> From: David Kastrup <dak@gnu.org>
> Cc: Stefan Monnier <monnier@iro.umontreal.ca>,  acm@muc.de,  emacs-devel@gnu.org
> Date: Sat, 07 Jun 2008 22:52:45 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> From: Stefan Monnier <monnier@iro.umontreal.ca>
> >> Date: Sat, 07 Jun 2008 14:40:11 -0400
> >> Cc: emacs-devel@gnu.org
> >> 
> >> `make bootstrap' should begin by doing a `maintainer-clean'.
> >
> > And then what does one do if a bootstrap fails half-way through, and
> > one wants to continue it after fixing the problem?
> 
> That's an expert operation with tripup potential.

No, it isn't.  Continuing from where the previous run with the same
arguments left off is a normal Make operation.

Re: Patch to INSTALL.CVS to clarify why `make bootstrap' sometimes fails.

[David Kastrup]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: David Kastrup <dak@gnu.org>
>> Cc: Stefan Monnier <monnier@iro.umontreal.ca>,  acm@muc.de,  emacs-devel@gnu.org
>> Date: Sat, 07 Jun 2008 22:52:45 +0200
>> 
>> Eli Zaretskii <eliz@gnu.org> writes:
>> 
>> >> From: Stefan Monnier <monnier@iro.umontreal.ca>
>> >> Date: Sat, 07 Jun 2008 14:40:11 -0400
>> >> Cc: emacs-devel@gnu.org
>> >> 
>> >> `make bootstrap' should begin by doing a `maintainer-clean'.
>> >
>> > And then what does one do if a bootstrap fails half-way through, and
>> > one wants to continue it after fixing the problem?
>> 
>> That's an expert operation with tripup potential.
>
> No, it isn't.  Continuing from where the previous run with the same
> arguments left off is a normal Make operation.

bootstrap is not exactly a standard target, and we don't have a target
bootstrap-clean that would avoid having to call configure from scratch.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Patch to INSTALL.CVS to clarify why `make bootstrap' sometimes fails.

[Eric Hanchrow]

>>>>> "David" == David Kastrup <dak@gnu.org> writes:

    David> Anyway, maintainer-clean does too much: it kills the record
    David> of how I ran configure the last time.  

The "configure" for Subversion creates a file called "config.nice" which
contains the command line with which you invoked "configure", for just
that reason.

-- 
Humor can be dissected as a frog can, but the thing dies in the
process and the innards are discouraging to any but the pure
scientist.
        --E.B. White

Re: Patch to INSTALL.CVS to clarify why `make bootstrap' sometimes fails.

[Stefan Monnier]

> And then what does one do if a bootstrap fails half-way through, and
> one wants to continue it after fixing the problem?

Good question.  And not a new one: this problem has existed for a long
time now.  I think we need a separate target for that.
Unless we can figure out a way to turn

     make bootstrap
into
     setup-bootstrap
     make


-- Stefan

Re: Patch to INSTALL.CVS to clarify why `make bootstrap' sometimes fails.

[Stefan Monnier]

David> Anyway, maintainer-clean does too much: it kills the record
David> of how I ran configure the last time.  

> The "configure" for Subversion creates a file called "config.nice" which
> contains the command line with which you invoked "configure", for just
> that reason.

Odd!  Isn't "./config.status --recheck" the standard way to do that?


        Stefan

Re: Patch to INSTALL.CVS to clarify why `make bootstrap' sometimes fails.

[Stephen J. Turnbull]

Stefan Monnier writes:

 > David> Anyway, maintainer-clean does too much: it kills the record
 > David> of how I ran configure the last time.  
 > 
 > > The "configure" for Subversion creates a file called "config.nice" which
 > > contains the command line with which you invoked "configure", for just
 > > that reason.
 > 
 > Odd!  Isn't "./config.status --recheck" the standard way to do that?

It is.  But like most things in autotools, you cannot rely on it.
Specifically, it may not do exactly the same thing that calling
configure directly does.

Also, config.status is a generated file and the standards say to
remove it.  I think that's plausible.  config.nice is arguably not a
generated file, it's a user-created script, which should not be
removed according to that standard.

Re: Patch to INSTALL.CVS to clarify why `make bootstrap' sometimes fails.

[Eli Zaretskii]

> From: David Kastrup <dak@gnu.org>
> Cc: monnier@iro.umontreal.ca,  acm@muc.de,  emacs-devel@gnu.org
> Date: Sun, 08 Jun 2008 00:22:16 +0200
> 
> >> > And then what does one do if a bootstrap fails half-way through, and
> >> > one wants to continue it after fixing the problem?
> >> 
> >> That's an expert operation with tripup potential.
> >
> > No, it isn't.  Continuing from where the previous run with the same
> > arguments left off is a normal Make operation.
> 
> bootstrap is not exactly a standard target, and we don't have a target
> bootstrap-clean that would avoid having to call configure from scratch.

What I described above is common for _all_ targets in the Makefile.
That's how Make works, so deliberately disrupting that to such an
extreme degree as suggested here would unpleasantly surprise users.

Re: Patch to INSTALL.CVS to clarify why `make bootstrap' sometimes fails.

[Alan Mackenzie]

Hi, Stefan!

On Sat, Jun 07, 2008 at 02:40:11PM -0400, Stefan Monnier wrote:
> > Any objections?

> Yes.

> > ! So if 'make bootstrap' fails, it may be necessary first to do 'make
> > ! maintainer-clean' to clear out these stale files.  You can then try
> > ! again, starting with `./configure'.  (Occasionally the loaddefs.el
> > ! file gets into a bad state due to changes in the Lisp libraries; this
> > ! procedure forces it to be regenerated.)

> [ Alan, this is not aimed at you. ]

> Rather than improve the documentation of our Makefile's brokenness,
> we should fix the beast.  E.g. `make bootstrap' should begin by doing a
> `maintainer-clean'.

However, that's going to take time, and discussion of it has already
become controversial.  When that's been settled, INSTALL.CVS will need
changing anyway.

So, how about letting me install the patch as it is; nobody has objected
to it as such.

Thanks!

>         Stefan

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: Patch to INSTALL.CVS to clarify why `make bootstrap' sometimes fails.

[Richard M Stallman]

    >> `make bootstrap' should begin by doing a `maintainer-clean'.
    >
    > And then what does one do if a bootstrap fails half-way through, and
    > one wants to continue it after fixing the problem?

    That's an expert operation with tripup potential.  The default bootstrap
    should just work, however slowly.

    Maybe we should add a target "continue-bootstrap" if this occurs often
    enough to make people want it.

I agree.

Re: Patch to INSTALL.CVS to clarify why `make bootstrap' sometimes fails.

[David Kastrup]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: David Kastrup <dak@gnu.org>
>> Cc: monnier@iro.umontreal.ca,  acm@muc.de,  emacs-devel@gnu.org
>> Date: Sun, 08 Jun 2008 00:22:16 +0200
>> 
>> >> > And then what does one do if a bootstrap fails half-way through, and
>> >> > one wants to continue it after fixing the problem?
>> >> 
>> >> That's an expert operation with tripup potential.
>> >
>> > No, it isn't.  Continuing from where the previous run with the same
>> > arguments left off is a normal Make operation.
>> 
>> bootstrap is not exactly a standard target, and we don't have a target
>> bootstrap-clean that would avoid having to call configure from scratch.
>
> What I described above is common for _all_ targets in the Makefile.
> That's how Make works, so deliberately disrupting that to such an
> extreme degree as suggested here would unpleasantly surprise users.

Do you really think that it is common for typical users to habitually
fix bootstrap errors and continue, to a degree where they get annoyed
when this process loses them 10 minutes "each time"?  And they won't, in
all their annoyance, read the docs or Makefile and discover
"bootstrap-continue"?  I find that hard to believe.

Anyway, how about including my repeated suggestion of a
"bootstrap-clean" target in your browbeating while you are standing up
for the status quo?

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Patch to INSTALL.CVS to clarify why `make bootstrap' sometimes fails.

[Eli Zaretskii]

> From: David Kastrup <dak@gnu.org>
> Date: Sun, 08 Jun 2008 10:33:15 +0200
> Cc: acm@muc.de, monnier@iro.umontreal.ca, emacs-devel@gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > What I described above is common for _all_ targets in the Makefile.
> > That's how Make works, so deliberately disrupting that to such an
> > extreme degree as suggested here would unpleasantly surprise users.
> 
> Do you really think that it is common for typical users to habitually
> fix bootstrap errors and continue, to a degree where they get annoyed
> when this process loses them 10 minutes "each time"?

It's common for those who habitually use "make bootstrap".  And 10
minutes can be as much as 30 on slower machines, which isn't fun at
all.

> And they won't, in all their annoyance, read the docs or Makefile
> and discover "bootstrap-continue"?  I find that hard to believe.

IMO, it's a bad mantra to go against user expectations, even if they
are documented.

> Anyway, how about including my repeated suggestion of a
> "bootstrap-clean" target in your browbeating

You don't need me to include it.

> while you are standing up for the status quo?

Not for status quo, for knowing thy tools, and for personal
soul-searching _before_ blaming ``broken tools'' and ``broken build
processes''.

Re: Patch to INSTALL.CVS to clarify why `make bootstrap' sometimes fails.

[David Kastrup]

Eli Zaretskii <eliz@gnu.org> writes:

> Not for status quo, for knowing thy tools, and for personal
> soul-searching _before_ blaming ``broken tools'' and ``broken build
> processes''.

As maintainer of AUCTeX and preview-latex (the latter being particularly
insidious with regard to the things it is messing with) I found that
after a while the excitement about having software be a testing stone
for the users' intelligence and yourself being correct wears off.  After
tripping up enough of them, never mind how much it is their fault not to
mind their step, you move.  Sooner or later.  Doing it sooner is more
efficient in the long run.

Never mind that it's all somebody else's fault.  For example,
preview.sty will in certain situations issue the following stern
warning:

      \PackageWarningNoLine{preview}{%
    Your document class has a bad definition^^J
    of \string#1, most likely^^J
    \string\let\string#1=\string#2^^J
    which has now been changed to^^J
    \string\def\string#1{\string#2}^^J
    because otherwise subsequent changes to \string#2^^J
    (like done by several packages changing float behaviour)^^J
    can't take effect on \string#1.^^J
    Please complain to your document class author}%
      \def#1{#2}\fi\fi}

We got a bug report every few months about yet another document class
written or derived from an old buggy code base that tripped up also
other packages.  It has been a lot of effort to teach people what is
wrong and have it reported upstream.  Most of the upstream reports had
no satisfactory followup.  Now of course, _we_ were right.  But it did
not help.  The above code then takes a crowbar and smashes things in a
certain way, assuming that they are broken in a certain way when it
decides that they could not possibly work otherwise.

We did not get a single report after that.  People don't care as long as
they get through somehow.

Don't turn the act of working with your software into an educational
enterprise.  Nobody will thank you for that.  Deal with the stupidity,
ignorance and lethargy of the world in general and move on.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Patch to INSTALL.CVS to clarify why `make bootstrap' sometimes fails.

[Glenn Morris]

Eli Zaretskii wrote:

> Not for status quo, for knowing thy tools, and for personal
> soul-searching _before_ blaming ``broken tools'' and ``broken build
> processes''.

+1.

Re: Patch to INSTALL.CVS to clarify why `make bootstrap' sometimes fails.

[Stefan Monnier]

> However, that's going to take time, and discussion of it has already
> become controversial.  When that's been settled, INSTALL.CVS will need
> changing anyway.

Indeed, nobody objected.  You can even mention that this current
situation it described is undesirable and helpful souls are welcome to
fix it right.


        Stefan