[m-rev.] for post-commit review: document the .target_debug and .pregen grade modifiers

[Julien Fischer]

On Sun, 10 Aug 2025 at 22:09, Zoltan Somogyi <zoltan.somogyi at runbox.com> wrote:

> diff --git a/doc/user_guide.texi b/doc/user_guide.texi
> index d0cce5698..6ec948698 100644
> --- a/doc/user_guide.texi
> +++ b/doc/user_guide.texi
> @@ -1516,14 +1516,80 @@ and is compatible only with them.
>  @node Grade modifiers for target language debugging
>  @subsection Grade modifiers for target language debugging
>
> -ZZZ TODO
> +Mercury programs intended to be debugged

*are* intended

> +using @command{mdb}, the Mercury debugger.
> +However, @command{mdb} treats non-Mercury code as a black box,
> +and cannot give any insights into its behavior.
> +
> + at table @code
> + at item .target_debug
> +Compiling programs in a grade that
> +includes the @code{.target_debug} grade modifier
> +generates executables that are intended to be debuggable
> +with usual debuggers for the target language selected by the base grade.
> +
> +This grade modifier is intended mainly
> +to help the implementors of Mercury itself debug interactions
> +between compiler-generated target code and the Mercury runtime system.
> +However, in certain rare cases, it may also be useful to other users
> +in debugging interactions between compiler-generated target code
> +and the contents of @code{foreign_proc} and/or @code{foreign_code} pragmas.
> +
> +This grade modifier could be applicable to all base grades,
> +but is intentionally restricted to MLDS grades.
> +This is because in LLDS grades,
> +the assembler-like C code generated by @command{mmc}
> +will probably confuse debuggers such as @command{gdb},
> +and it will definitely confuse
> +any Mercury programmer whose is not a Mercury implementor.

   *who is* not also a ...

> +The more idiomatic target language code
> +that @command{mmc} generates in MLDS grades
> +is still far from trivial for non-implementors to understand,
> +but at least they have a fighting chance.
> + at end table
>
>  @c ----------------------------------------------------------------------------
>
>  @node Grade modifiers for pregenerated source distributions
>  @subsection Grade modifiers for pregenerated source distributions
>
> -ZZZ TODO
> +There is one grade modifier that users will probably encounter
> +that they will propably never need to use themselves.
> +This the grade modifier that the Mercury team itself
> +uses only for a single purpose: making source distributions.
> +Such distributions include not just the code of the Mercury system,
> +which is mostly written in Mercury itself.
> +but also the C code generated for each Mercury module.
> +This allows people
> +who do not have a working Mercury installation on their machine to create one.
> +
> + at table @code
> + at item .pregen
> +Compiling programs in a grade that
> +includes the @code{.pregen} grade modifier
> +switches off all optional features,
> +and tells the compiler to make the fewest possible assumptions
> +about the platform on which the generated code will run.
> +(For example, the generated code will work
> +on both 32-bit and 64-bit platforms.)
> +
> +Source distributions use grades that include this modifier
> +(the grade usually being @code{hlc.gc.pregen})
> +because it makes the C code in them portable to as many platforms as possible.
> +However, it has no advantages beyond this,
> +and, on 64-bit machines,
> +the requirement to use a data representation scheme
> +that also works on 32-bit platforms
> +imposes a nontrivial cost in performance.
> +This is why for pretty much any purpose other than source distributions,
> +other grades are a better choice.
> +
> +This grade modifier is applicable
> +only to the base grades @code{hlc} and @code{none}.

No, it is applicable to all LLDS base grades. For .pregen grades, as
normally, the
details of which base grade is used are abstracted by macros in the
generated code.
(Values from the configure script determine how those macos are expanded.)

All that said, the chances of the source distributions moving off hlc are
pretty much zero at this point.

Julien.