[Bug gas/32254] Build problems related to doc/asconfig.texi

[nickc at redhat dot com]

https://sourceware.org/bugzilla/show_bug.cgi?id=32254

--- Comment #5 from Nick Clifton <nickc at redhat dot com> ---
(In reply to rdiez-2006 from comment #4)

> Therefore, there seems to be a race condition with the install-strip target
> when using parallel builds. Generation of doc/asconfig.texi is not
> serialised properly in the makefile.


> Users shouldn't really need implement a workaround like the "find . -name
> *.info -exec touch {}" you suggested.

True - but it does work.  Plus even if this problem is fixed it will only
affect newer distributions.  Having the workaround in place means that the
Toolchain script will work with older distributions.


> I would fix that bug first. Unfortunately, I do not know enough about
> Binutils' build system to do that myself.

Sadly, neither do I.  The sad truth is that the build system is very old, very
crufty, and prone to breaking whenever changes are made.  A better solution
would be to add support for a more modern build system (meson+ninja maybe ?)
and then allow users to choose which system they want to use.


> Nevertheless, I tried, and I tracked the generation rule down to
> binutils-gdb/gas/doc/local.mk :
> 
> %D%/asconfig.texi: %D%/$(CONFIG).texi %D%/$(am__dirstamp)
>       $(AM_V_at)rm -f %D%/asconfig.texi
>       $(AM_V_GEN)cp  $(srcdir)/%D%/$(CONFIG).texi %D%/asconfig.texi 
>       && touch -m -r $(srcdir)/%D%/$(CONFIG).texi %D%/asconfig.texi
>       $(AM_V_at)chmod u+w %D%/asconfig.texi
> 
> I think there are several issues with that rule.
> 
> The file deletion upfront is probably what makes the race condition visible.
> But the whole generation strategy is wrong: if there is an error half-way
> while copying the asconfig.texi, or in the chmod command, then the build
> system will leave a corrupt file behind.
> 
> The right strategy is to copy the file to a different filename first, like
> asconfig.texi.tmp, adjust the permissions etc. on it, and then move the file
> to its final filename. The move is an atomic operation on the filesystem.
> That is actually the only way to guarantee robust error handling in a
> makefile.
>
> Instead of running chmod as a separate step, I would copy the file with: cat
> %D%/$(CONFIG).texi > %D%/asconfig.texi
>
> I am guessing that this rule just selects the full documentation, or a short
> version of it, based on the value of $(CONFIG). I suspect that setting the
> target file to the same date as the source file is wrong. This means that,
> if $(CONFIG) changes, the date of the generated doc/asconfig.texi may move
> to the past or to the future. I would say that generated files should have
> the timestamp set to the generation time. I mean that the 'touch' command
> should be removed.
> 
> The dependency on a directory timestamp "%D%/$(am__dirstamp)" is iffy. In a
> makefile, files should generally depend on files, and it should not be
> necessary to use timestamping tricks. But perhaps you know the reason?

No, actually I agree with you on that one.  The dependency does look strange.

So basically you are suggesting that the rule should look like this, right ?

  %D%/asconfig.texi: %D%/$(CONFIG).texi
        $(AM_V_GEN)cat $(srcdir)/%D%/$(CONFIG).texi > %D%/asconfig.texi.tmp
        $(AM_V_at)chmod u+w %D%/asconfig.texi.tmp
        $(AM_V_at)mv %D/asconfig.texi.tmp %D%/asconfig.texi


> I believe that including generated files in source tarballs is bad practice.
> However, the GNU coding standards actually kind of encourage you to ship
> generated .info files:
> 
> -------8<-------8<-------8<-------
> Naturally, all the source files must be in the distribution. It is okay
> to include non-source files in the distribution, provided they are
> up-to-date and machine-independent, so that building the distribution
> normally will never modify them. We commonly include non-source files
> -------8<-------8<-------8<-------

Right - I think that the point is that we do not require anyone who wants to
use the binutils sources to also have the tools for building the documentation.
(They may not be able to obtain them for example, or they may not have access
to the versions of the tools needed to generate the documentation as it is
currently written).  Hence supplying the generated files means that potentially
more people are able to use the binutils.



> If I were to ship pre-built .info files, I would place them into a separate
> "prebuilt" directory. If the info tools are there, I would build the .info
> files. If not, I would take them from the "prebuilt" directory. But I
> wouldn't ship .info files next to their corresponding sources as if they had
> been previously built by the build system on this machine. You wouldn't need
> to worry then about timestamps.

OK, so the algorithm for building the documentation would look something like
this:

  1. If the source .texi is missing then:
       1a. If the .info file is present generate a warning message 
           otherwise generate an error message.
       1b. stop.
  2. If the compiled .info file is present and newer than the .texi file, 
      then there is nothing to do.  Just stop.
  3. If the tools for building the .info file are present, build it.
     If the build fails, issue a message and continue to step 4, otherwise
stop.
  4. If the .info file is in the prebuilt directory, copy it to the build
     directory and stop.
  5. Generate an error message about missing build tools and stop.

How does that sound ?

-- 
You are receiving this mail because:
You are on the CC list for the bug.