[m-rev.] for post-commit review: improve documentation of query options

[Zoltan Somogyi]

On Fri, 14 Jan 2022 22:20:58 +1100 (AEDT), Julien Fischer <jfischer at opturion.com> wrote:
> >          "--output-libgrades",
> > -        "\tPrint the list of compilation grades in which a library",
> > -        "\tto be installed should be built to the standard output.",
> > +        "\tPrint to standard output the list of compilation grades in which",
> > +        "\tthe Mercury standard library is available with this compiler.",
> 
> The new description is not correct.  --output-libgrades prints the set
> of library grades implied by the installed grades *and* any command line
> options that affect the contents of that set (e.g --libgrades-exclude).
> For example,
> 
>     $ mmc --no-libgrade --output-libgrades
> 
>   should, and does, print nothing.
> 
> --output-libgrades will only print the set of installed library grades in the
> absence of any commmand line options that affect that set.

Agreed about what happens in the presence of user-supplied --libgrade=...
and --no-libgrade options. Question is: are there any use cases in which
non-developers would ever need, or even want, to use those options?
I don't know of any, and would therefore be happy if the --libgrade option
was deleted (see below), though we may need a replacement for
--no-libgrade.
 
> (We should consider adding a new option --output-installed-grades, which just
> prints the installed stdlib grades ignoring any other options that
> affects the library grade set.)

In fact, I was looking at adding such an option when I decided to start with
a cleanup. I found detect_libgrades in mercury_compile_main.m, which uses
--libgrades options internally in what I think is a VERY roundabout way, and
whose code is almost a mirror image of the code in check_libgrades.m.
That relationship tells me that those two pieces of code definitely belong
in the same module; at the very least, in the absence of user-provided
--libgrade options, we could avoid having detect_libgrades compute a set,
and then having check_libgrades run the *same algorithm as detect_libgrades*
before testing if they get the same output.

We already record the set of grades to be installed in a file,
.configured_library_grades, though that file is not used anywhere.
I think we should also put that info into a file in the compiler directory,
use shell code in an mmake action to construct a Mercury module
exporting a single predicate from it, and use that to replace
detect_libgrades in the usual case. We could keep the current code
of detect_libgrades around for situations in which the user is concerned
that the installed set of grades may have been tampered with
after installation. (Or if the "install the stdlib" part of the install
failed, though the usual course of action in such cases is to
delete the incomplete install directory as a whole. Even then,
I would change detect_libgrades to return a set of grade strings,
not a sequence of --libgrade options, and would add that set
to the globals structure, not to the option table.

Zoltan.