[m-rev.] for post-commit review: semantic help pieces for grade options

[Julien Fischer]

On Tue, 1 Jul 2025 at 22:06, Zoltan Somogyi <zoltan.somogyi at runbox.com> wrote:

> Convert grade options to semantic help_pieces.
>
> compiler/options.m:
>     As above.
>
> compiler/optdb_help.m:
>     Add a new help_piece.
>
> compiler/print_help.m:
>     Handle the new help_piece, and prepare for commented-out
>     texinfo documentation for private options.
>
> tests/warnings/help_text.err_exp:
>     Expect the updated help text.

...


> diff --git a/compiler/options.m b/compiler/options.m
> index aae4a92e8..417deecf4 100644
> --- a/compiler/options.m
> +++ b/compiler/options.m
> @@ -1516,23 +1516,45 @@ optdb(oc_opmode,    only_opmode_output_optimization_options_upto, int(-1),
>      % Some merely control *how* a grade's functionality operates;
>      % others are internal-use-only.
>
> -% ZZZ Come back to add semantic help_pieces to oc_grade options.
> -
>  % Grade options, part a: specifying a complete grade
>
>  optdb(oc_grade_gen, grade,                             string_special,
>      % The `mmc' script will pass the default grade determined
>      % at configuration time.
>      short_arg_help('s', "grade", [], "grade", [
> -        w("Select the compilation model. The <grade> should consist of"),
> -        w("one of the base grades `none', `reg', `asm_fast', `hlc', `java'"),
> -        w("or `csharp',"),
> +        w("Select the compilation model."),
> +        % XXX Should we add this?

I think so.

> +        % This model, which Mercury calls a *grade*, specifies
> +        % what properties the resulting executable or library should have.
> +        % (Properties such as "can be debugged with the Mercury debugger".)

I would add a second example there.

> +        % As such, it controls decisions that must be made the same way
> +        % in all the modules of a program.
> +        % For example, it does not make sense
> +        % to compile some modules of a program to C and some to Java;
> +        % nor does it make sense
> +        % to compile some modules to support profiling
> +        % and some to not support profiling.
> +        w("The"), arg("grade"), w("should consist of one of the base grades"),
> +        samp("none", ","), samp("reg", ","), samp("asm_fast", ","),
> +        samp("hlc", ","), samp("java", ","), w("or"), samp("csharp", ","),
>          w("followed by zero or more of the grade modifiers"),
> -        w("`.gc', `.prof', `.memprof', `.profdeep', `.tr',"),
> -        w("`.spf', `.stseg', `.debug', and `.par'."),
> -        w("Depending on your particular installation, only a subset"),
> -        w("of these possible grades will have been installed."),
> -        w("Attempting to use a grade which has not been installed"),
> +        w("in the following options."),
> +        % "following options" because this old list is seriously incomplete:
> +        % w("`.gc', `.prof', `.memprof', `.profdeep', `.tr',"),
> +        % w("`.spf', `.stseg', `.debug', and `.par'."),
> +        w("The names of all grade modifiers start with a period,"),
> +        w("so a complete grade name consists of a list of name components"),
> +        w("(the base grade and some grade modifiers) separated by periods."),
> +        blank_line,
> +        w("Note that not all combinations of components are allowed,"),
> +        w("and that the Mercury standard library"),
> +        w("will have been installed on your system"),
> +        w("in only a subset of the set of all possible grades."),
> +        blank_line,
> +        w("Attempting to build a program"),
> +        w("in a grade which has not been installed"),
> +        w("or to link together modules"),
> +        w("that have been compiled in different grades,"),
>          w("will result in an error at link time.")])).s

That's only sometimes true. The only way you will get a link error is if you
try to build a library using mmake in a grade that is not installed.

If you try to build an executable in a grade that is not installed using
mmake you will get an error from mkinit (the .init files for the standard
library in that grade cannot be found).

If you are compiling a single module program or using --make, the compiler
checks whether the standard library is present in the selected grade and will
print a error saying that the grade is not available if it is not.

...

> @@ -1546,30 +1568,36 @@ optdb(oc_grade_target, target,                         string("c"),
>              arg_align("java",   "(grades: java)")], [
>          w("Specify the target language: C, C# or Java."),
>          w("The default is C."),
> -        w("Targets other than C imply `--high-level-code' (see below).")])).
> +        w("Targets other than C imply"), opt("--high-level-code"),
> +        w("(see below).")])).
>  optdb(oc_grade_target, compile_to_c,                   special,
>      alt_help("compile-to-c", ["compile-to-C"], [
> -        w("An abbreviation for `--target c --target-code-only'."),
> -        w("Generate C code in `<module>.c', but do not generate object"),
> -        w("code.")])).
> +        w("An abbreviation for"),
> +        opt("--target c"), opt("-target-code-only", "."),
> +        w("Generate C code in"), file_var("module", "c", ","),
> +        w("but do not generate object code.")])).
>  optdb(oc_grade_target, java,                           special,
>      alt_help("java", ["Java"], [
> -        w("An abbreviation for `--target java'.")])).
> +        w("An abbreviation for"), opt("--target java", ".")])).
>  optdb(oc_grade_target, java_only,                      special,
>      % XXX Using "object code" for Java is iffy.
> +    % XXX Would replacing it with ".jar files" be better?

I would replace "object code" with "Java bytecode" there.

>      alt_help("java-only", ["Java-only"], [
> -        w("An abbreviation for `--target java --target-code-only'."),
> -        w("Generate Java code in `<module>.java', but do not generate"),
> -        w("object code.")])).
> +        w("An abbreviation for"),
> +        opt("--target java"), opt("--target-code-only", "."),
> +        w("Generate Java code in"), file_var("module", "java", ","),
> +        w("but do not generate object code.")])).
>  optdb(oc_grade_target, csharp,                         special,
>      alt_help("csharp", ["C#"], [
> -        w("An abbreviation for `--target csharp'.")])).
> +        w("An abbreviation for"), opt("--target csharp", ".")])).
>  optdb(oc_grade_target, csharp_only,                    special,
>      % XXX Using "object code" for C# is iffy.
> +    % XXX Would replacing it with ".dll files" be better?

Here I would replace "object code" with "CIL bytecode" there.

>      alt_help("csharp-only", ["C#-only"], [
> -        w("An abbreviation for `--target csharp --target-code-only'."),
> -        w("Generate C# code in `<module>.cs', but do not generate"),
> -        w("object code.")])).
> +        w("An abbreviation for"),
> +        opt("--target csharp"), opt("--target-code-only", "."),
> +        w("Generate C# code in"), file_var("module", "cs", ","),
> +        w("but do not generate object code.")])).
>
>  %---------------------%
>
>
> @@ -1617,20 +1645,22 @@ optdb(oc_grade_mlds, highlevel_code,                   bool(no),
>              ["high-level-c", "high-level-C",
>              "highlevel-code", "highlevel-c", "highlevel-C"],
>              "(grades: hlc, csharp, java)", [
> -        w("Use an alternative back-end that generates high-level code"),
> -        w("rather than the very low-level code that is generated by our"),
> -        w("original back-end.")])).
> +        w("Use the MLDS backend,"),
> +        w("which generates idiomatic high-level-language code,"),
> +        w("rather than the LLDS backend,"),
> +        w("which generates assembly language code in C syntax.") ])).
>  optdb(oc_grade_mlds, c_debug_grade,                    bool(no),
>      alt_align_help("c-debug-grade", [],
>              "(grades: hlc)", [
>          w("Require that all modules in the program"),
>          w("be compiled to object code"),
>          w("in a way that allows the program executable to be debuggable"),
> -        w("with debuggers for C, such as gdb. This option is intended mainly"),
> -        w("for the developers of Mercury, though it can also help to debug"),
> +        w("with debuggers for C, such as"), code("gdb", "."),
> +        w("This option is intended mainly for the developers of Mercury,"),
> +        w("though it can also help to debug"),
>          w("C code included in Mercury programs."),
> -        w("This option is used only when targeting C"),
> -        w("with `--high-level-code'.")])).
> +        w("This option is used only when targeting C with"),
> +        opt("--high-level-code", ".")])).

I don't think this is restricted to high-level C grades.

> @@ -1682,10 +1712,16 @@ optdb(oc_grade_dbg, source_to_source_debug,            bool(no),
>  optdb(oc_grade_prof, profiling,                        bool_special,
>      short_alt_align_help('p', "profiling", [],
>              "(grade modifier: `.prof')", [
> -        w("Enable time and call profiling. Insert profiling hooks in the"),
> -        w("generated code, and also output some profiling"),
> -        w("information (the static call graph) to the file"),
> -        file_var("module", "prof", "."),
> +        w("Prepare the generated code for time profiling"),
> +        w("by Mercury's version of the standard Unix profiler"),
> +        code("gprof", ","),
> +        w("which is a tool called"), code("mprof", "."),
> +        w("In"), samp(".prof"), w("grades, the compiler will insert"),
> +        w("profiling hooks into the generated code (e.g. to count calls),"),
> +        w("and will also output the static call graph of the module to"),
> +        file_var("module", "prof"), w("for use by"), code("mprof", "."),
> +        % XXX Should we add an xref to one of the profiling chapter's sections?
> +        % XXX If so, which one?

"Building profiled applications", or perhaps just the chapter as whole?

> @@ -1693,7 +1729,9 @@ optdb(oc_grade_prof, time_profiling,                    special,
>  optdb(oc_grade_prof, memory_profiling,                 special,
>      alt_align_help("memory-profiling", [],
>              "(grade modifier: `.memprof')", [
> -        w("Enable memory and call profiling."),
> +        w("Prepare the generated code for"),
> +        w("profiling of memory usage and retention by mprof."),
> +        % XXX Should we add an xref to the profiling chapter's memprof section?

Yes.

> @@ -1900,12 +1949,14 @@ optdb(oc_grade_etc, parallel,                          bool(no),
>  optdb(oc_grade_etc, maybe_thread_safe_opt,             string("no"),
>      % XXX How is a yes/no argument better than a no- prefix?
>      arg_help("maybe-thread-safe", "{yes, no}", [
> -        w("Specify how to treat the `maybe_thread_safe' foreign code"),
> -        w("attribute. `yes' means that a foreign procedure with the"),
> -        w("`maybe_thread_safe' option is treated as though it has a"),
> -        w("`thread_safe' attribute. `no' means that the foreign"),
> -        w("procedure is treated as though it has a `not_thread_safe'"),
> -        w("attribute. The default is `no'.")])).
> +        w("Specify how to treat the compiler should treat the"),

Delete "to treat" there.

The rest looks fine.

Julien.