[m-rev.] for review: keep the invocation automatically up-to-date

[Julien Fischer]

On Sat, 19 Jul 2025 at 07:43, Zoltan Somogyi <zoltan.somogyi at runbox.com> wrote:

> The main issue I am seeking feedback on is that after this diff,
> making the user guide requires compiler/mercury_compile to be
> up to date. The other rules of doc/Mmakefile already depend
> on the contents of the compiler directory, but they do so only for
> .m files, which do not need to be built.
>
> Note that the top level makefile builds the doc directory *after*
> the compiler directory, so this won't be an issue in the vast majority
> of cases, but maybe one of you knows an atypical case where it may
> cause an issue.

> Keep the invocation chapter always up-to-date.
>
> doc/user_guide.texi:
>     Replace the invocation chapter part of this file with a @include
>     of a new file, ug_invocation.texi, which contains the output of
>     "mmc --help-texinfo".
>
> doc/Mmakefile:
>     Make user_guide.texi_pp dependent on ug_invocation.texi.
>     Do not force the rebuilding of the info/pdf/etc versions
>     of the user guide if, when we check whether ug_invocation.texi
>     is still current, we find that it is.
>
> diff --git a/doc/Mmakefile b/doc/Mmakefile
> index 7fcf17ade..5606b0c33 100644
> --- a/doc/Mmakefile
> +++ b/doc/Mmakefile
> @@ -141,6 +141,42 @@ mercury.html: mercury.html.in ../VERSION
>  mercury.info: mercury.info.in ../VERSION
>      $(SED_CMD)
>
> +# user_guide.texi_pp @includes ug_invocation.texi, so all targets
> +# that want to process user_guide.texi must make user_guide.texi first.
> +# user_guide.texi_pp is the only such *direct* target; all the others
> +# go through it.
> +user_guide.texi_pp: ug_invocation.texi
> +
> +# The rule for ug_invocation.texi_date compares any existing
> +# file ug_invocation.texi against its "new" intended contents, and
> +# leaves it unchanged, including its timestamp, if the "new" contents
> +# would be the same as the old. Then, after gmake executes  @:,
> +# the silent do-nothing command, it will believe that ug_invocation.texi
> +# is up-to-date regardless of whether the rule for ug_invocation.texi_date
> +# updated it or not.
> +#
> +# This is the same scheme that scripts/Mmake.rules uses for e.g.
> +# .int and .date files. Both copies of this scheme lead to strange errors
> +# if the timestamp file exists but the file it is the timestamp OF has been
> +# deleted. This is not usually a problem though, first because making
> +# such deletions accidentally is rare, and second because an "mmake clean"
> +# fixes the issue by deleting the timestamp file as well.
> +ug_invocation.texi: ug_invocation.texi_date
> +    @:
> +
> +ug_invocation.texi_date: ../compiler/mercury_compile

For C grades, that should at least be:

    ../compiler/mercury_compile$(EXT_FOR_EXE)

The situation for non-C grades, in the rare circumstance that stage 1 is built
in them, is a bit more complicated; $(EXT_FOR_EXE) should be ignored for
non-C grades on Windows, except for actual .NET on Windows IIRC. I will check
all this after you commit.

That diff looks ok otherwise.

Julien.