[m-rev.] for post-commit review: fill in most of the grade modifiers section

[Zoltan Somogyi]

On Fri, 8 Aug 2025 14:19:45 +1000, Julien Fischer <jfischer at opturion.com> wrote:

> Hi Zoltan,
> 
> On Thu, 7 Aug 2025 at 15:14, Zoltan Somogyi <zoltan.somogyi at runbox.com> wrote:
> 
> > The second is for .c_debug. The issue here is a contradiction.
> > It is clear that this grade component is for MLDS grades, but for
> > which targets?
> 
> Why is that clear?

I was looking at the grade library, which has, on line 439 of grade_spec.m:

        "The .c_debug grade component is not supported by the LLDS backend.",
        % We could possibly support it for grades that do not use any gcc
        % extensions to C, but invoking gdb on object code that uses
        % e.g. gcc extensions to execute gotos between modules without going
        % through function prologues/epilogues is not going to be
        % remotely useful.

I would add that even in grade none, the threaded code will confuse
the hell out of anyone who is not a Mercury implementor.

You are right that the compiler does not currently enforce this restriction,
and therefore commands such as "mmc --grade none.c_debug ..." work.

> Does that grade component not apply to the LLDS
> grades at all?

Clearly, at the moment it does, but I think it is not something
users should be doing. We can either

- document the availability of c_debug in LLDS grades, but add
  strong warnings about that not being useful, or

- disable c_debug in LLDS grades.

The code in grade_spec.m suggests to me that the last time we had this
argument, years ago, we probably chose the second option.

Even us implementors have not needed to debug very low level details
in years. When we do, we can just enable .c_debug in LLDS grades,
track down and fix whatever issue needs fixing, and disable .c_debug
in LLDS grades again.

> Using gdb-level debugging will obviously be significantly
> less useful in many of the LLDS grades because:
> 
> 1. The Mercury-level debugger is available in those grades.
> 2. Some of what we do in the asm_fast and reg grades might be a bit
>    "interesting"  for gdb.

I think "interesting", even in the sense of the Chinese curse, is underselling
things a bit ...

> That said, I cannot think of any reason why running a program in say
> none.gc.c_debug under gdb should not work.  If you are trying to debug
> the contents of foreign_proc or foreign_code pragmas, you may well want
> to do this.

If those foreign_procs or foreign_codes are written by implementors
specifically for the LLDS backend, then yes, I agree, but see above
about undisable then disable.

If the foreign code is not specific to the LLDS backend, then you are
far better off using gdb on a hlc.c_debug.gc executable.

> > The name says it is for C, compile_target_code.m
> > says it is for C (i.e. the code for compiling Java and C# files does not
> > consult the option representing it), but the code that computes grades
> > accepts its presence when targeting Java or C#.
> 
> The original motivation for the addition of .c_debug (then, .ll_debug) was
> for debugging problems in C grades.
> 
> README.Java.md has a section on "Java-level debugging".  As written,
> it looks as though debugging symbols would only be present for classes
> in your program, not those of the standard library.
> 
> > I can see two ways to resolve this contradiction. One is to stop accepting
> > java.c_debug and csharp.c_debug grades. The other is to rename the
> > modifier to .target_debug, and make compile_target_code.m pay attention
> > to it when compiling Java and C# files. I think the second way is preferable,
> > *provided* that there is a single, at-least-relatively-stable way to enable
> > debuggability of Java and C# code.
> 
> There is. The handling of the --target-debug _option_ in the compiler
> is correct for
> Java and probably correct for C#.  I don't think anything is required for the
> .target_debug grade beyond ensuring that is enabled.

Agreed. I will rename the grade modifier .c_debug to .target_debug
in a separate commit, and make it set the target_debug option.

Zoltan.