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

[Julien Fischer]

Hi Zoltan,

On Fri, 14 Jan 2022, Zoltan Somogyi wrote:

> 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.

Please don't do anything to either of those options; I just had a grep
through the G12 source code which is using them all over the place.

>> (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.

I imagine there is a fair amount of overlap between the two; obviously
check_libgrades it not restricted to just the standard library, it also
checks that any user-specified libraries are present in the required
grades.

IIRC, the stituation is that mmc (i.e. the compiler invoked on a single
module program) and mmc --make use detect_libgrades to construct the
initial set of libgrades and then any user-specified modifications are
applied on top of that.  We used to do this by writing --libgrade
options into the global Mercury.config file at configuration time, but
doing so means that you can not install (or indeed uninstall) additional
grades without modifying that part of the Mercury.config file.

The rationale for this was to support (or at least simplify) finer
grained packaging of Mercury (e.g. one .deb or .rpm for the base system,
another for the debug grades, another for the profiling grades etc) and
also to allow installation of additional library grade from source after
the initial installation has been completed.  (I think there were some
additional changes to the configure script to support that last use case,
that never made it in for one reason or another.)

(mmake doesn't support any of this and just reads its configured
list of library grades from one of its configuration files.)

> We already record the set of grades to be installed in a file,
> .configured_library_grades,

We do, but that assumes that the set of *installed* library grades is
going to remain the same as set of *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.

I think we should avoid baking configuration information into the
compiler as much as possible.  In this case, if the installation has
been "tampered" with then it seem like a source of bugs.

Julien.