Subject: Re: bug#75655: configure doesn't update Makefile

From: Eli Zaretskii <[email-masked]>
Date: Fri, 24 Jan 2025 09:26:28 +0200

> Date: Thu, 23 Jan 2025 20:10:44 +0000
> From: Pip Cet <[email-masked]>
> Cc: Eli Zaretskii <[email-masked]>, [email-masked], [email-masked]
> 
> --- a/INSTALL.REPO
> +++ b/INSTALL.REPO
> @@ -75,18 +75,19 @@ To rebuild Emacs with the default configuration options, you can use:
>  
>    $ make bootstrap configure=default
>  
> -Occasionally, there are changes that 'make bootstrap' won't be able to
> -handle.  The most thorough cleaning can be achieved by 'git clean -fdx'
> -which will leave you with only files from the git repository.  Here
> -are some faster methods for a couple of particular error cases:
> +Rarely, after a git update, all 'make' commands will fail because the
> +Makefile itself is no longer usable.  Error messages such as:
>  
> -    /usr/bin/m4:aclocal.m4:9: cannot open `m4/stdbit_h.m4': No such file or directory
> +    make: *** No rule to make target 'benchmarks/Makefile.in', needed by 'Makefile'.  Stop.
>  
> -This can be fixed with 'rm aclocal.m4'.
> +indicate this.  You should delete and rebuild the Makefile:
>  
> -    make: *** No rule to make target 'lib/Makefile.am', needed by 'lib/Makefile.in'
> +  $ rm -f Makefile
> +  $ make
> +
> +If this doesn't fix the problem, you can clean the git repo:
>  
> -This can be fixed with 'rm lib/Makefile Makefile'.
> +  $ git clean -idX

IMO, this loses useful information about the aclocal.m4 problem.  It
was there because it happened to people, and users who are not experts
in Automake will have trouble coping with it.  I do agree that it
should be very rare, so making it the last problem we describe is
okay.

Moving "git -fdx" to the end and changing it to "git -idx" is also a
mistake, IMO.  It is a much simpler operation to do, and cannot
possibly mistakenly delete required files.  In a clean tree, it is
also TRT.  I'm okay with Stefan's suggestion to explain that this
command removes uncommitted changes, and saying that if there are
uncommitted changes one wants to keep, one should use the interactive
"git -idx" instead.  But let's not spare the important details;
instead, let's describe them, along with the supporting information
that would allow people to make informed decisions what to do in their
particular case.

The text about removing Makefile's should also be amended to explain
that the Makefile file to be removed is in the directory spelled out
by the error message.  The lib/Makefile.am example was better for that
because it included a directory name, but we should amend the text to
say explicitly that the Makefile to be deleted is in the same
directory.

Last, but not least: if we are going to expand INSTALL.REPO to include
a significant amount of additional information for special cases, we
should consider dividing it into sections.  The first section should
just show the nominal sequence of commands to build Emacs, because
that's what the absolute majority of readers will need.  The rest
should have appropriate headings, to allow finding the required
information easily and quickly.  For example, the part we are
discussing here could have a heading like "If you encounter a build
failure" or something to that effect.