[m-rev.] for post-commit review: finish the intermodule opt section in the user guide

[Julien Fischer]

On Sat, 30 Aug 2025 at 03:27, Zoltan Somogyi <zoltan.somogyi at runbox.com>
wrote:

> diff --git a/doc/mercury_user_guide.texi b/doc/mercury_user_guide.texi
> index 79d268e94..0b7f1d8a8 100644
> --- a/doc/mercury_user_guide.texi
> +++ b/doc/mercury_user_guide.texi
> @@ -2330,20 +2334,96 @@ Mercury's first step
>  towards avoiding circular dependencies between @file{.trans_opt} files
>  is to impose an order on the modules of the program
>  when the @command{mmc --generate-dependencies} command is executed for
it.
> -This order is recorded in the @file{.dv}
> -The second step is to ensure that
> -a @file{.trans_opt} file can only ever depend on
> - at file{.trans_opt} files that @emph{follow} it in the order,
> -never ones that @emph{precede} it.
> +(One reason, though not the only one,
> +why @command{mmc --make} does not support @file{.trans_opt} files is that
> +it neither has nor needs a @command{mmc --generate-dependencies} step.)

That doesn't seem a very strong reason, presuambly *if* mmc --make were
modified to support transitive intermodule-optimization, we would modify
its internal dependency mechanism to account for that?

...

> -mmc --make-transitive-optimization-interface @var{module_1}.m
@var{module_2}.m @dots{}
> + at command{mmc --generate-dependencies --also-output-module-order prog.m}.
> + at end example
> +
> +After this command, @file{prog.module_order} will contain
> +the strongly connected components (SCCs)
> +of the module dependency graph of the program in a top-down order,
> +with different SCCs separated by blank lines,
> +and with the different modules in each SCC being listed
> +one per line with no blank lines between them.

I would break that up into separate sentences, the second beginning
with: "The graph will be in a top-down order ..."

> +The order of the modules of the program
> +is exactly the order in which appear in this file.
> +
> + at c JUNK
> + at c The compiler does this when making dependencies for
> + at c This order is recorded in the @file{.d}
> + at c The second step is to ensure that
> + at c a @file{.trans_opt} file can only ever depend on
> + at c @file{.trans_opt} files that @emph{follow} it in the order,
> + at c never ones that @emph{precede} it.
> +
> +To actually construct the @file{.trans_opt} files for e.g.@:
> + at file{@var{module_1}.m} and @file{@var{module_2}.m},
> +use a command such as
> +
> + at example
> +mmc --make-transitive-optimization-interface --analyse-exceptions
@var{module_1}.m @var{module_2}.m
>  @end example
>  @findex --make-transitive-optimization-interface
>  @findex --make-trans-opt
>
> +Beside @option{--analyse-exceptions},
> +the following options also record their results in @file{.trans_opt}
files.
> + at itemize @option
> + at c @item @option{--analyse-closures}, and

The analysis carried out by --analyse-closures is within a module only.
Its results are not placed in .opt or .trans_opt files.

> + at item --enable-termination
> +This option turns on Mercury's first termination analyser,
> +which uses linear inequalities.
> + at item --enable-termination2
> +This option turns on Mercury's second termination analyser,
> +which uses convex constraints.
> + at item --analyse-trail-usage and
> +This option turns on an analysis
> +that reports which predicates and functions

What do you mean by "reports"? The analysis determines which
predicates and functions do not touch the trail, but it doesn't
report them, except to the rest of the compiler.

> +definitely do not touch the trail,
> +enabling the compiler to reduce the overhead of trailing.
> +(This analysis is applicable only in trailing grades.)
> + at item --analyse-mm-tabling
> +This option turns on an analysis
> +that reports which predicates and functions have call trees

Similarly.

> +that do not involve mininal model tabled procedures at all,

s/mininal/minimal/

> +enabling the compiler to reduce the overhead of minimal model tabling.
> +(This analysis is applicable only in minimal model grades.)
> + at end itemize
> +
> +The results of both termination analysis systems
> +can be used by the user to spot potential performance problems.
> +(That performance problem @emph{may} be non-termination,
> +but the analyser's inability to prove termination
> +may also be caused by less drastic performance problems.)

I suggest: s/caused by/indicative of/

> +The compiler can also perform more optimizations on calls
> +for which it knows that the called predicate and function always
terminates.
> +
> +After @file{.trans_opt} files containing such analysis results

Delete "such".

> +have been created,
> +any invocation of @command{mmc} to compile say @var{module_3}
> +with the @code{--transitive-intermodule-optimization} option
> +(or @code{--trans-intermod-opt} for short),

Delete the parenthised bit; there's no point cluttering the text
up by reminding readers of what abbreviations exist for options.)

The rest looks fine.

Julien.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mercurylang.org/archives/reviews/attachments/20250830/3aa7b480/attachment.html>