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

[Julien Fischer]

On Fri, 14 Jan 2022, Zoltan Somogyi wrote:

> On Fri, 14 Jan 2022 23:34:14 +1100 (AEDT), Julien Fischer <jfischer at opturion.com> wrote:
>>> 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;
>
> Since you asked, I won't, though that is just one option, not two :-)
>
> I will fix the doc of --output-libgrade.
>
>> I just had a grep
>> through the G12 source code which is using them all over the place.
>
> Using them for what purpose, if I may ask?

Their intended purpose: controlling what set of grades a library is
installed in.  Most G12 components have particular requirements about
what features are present in the compilation model (e.g. trailing,
double precision floats).  G12's configure script builds up a
configuration variable containing of --libgrade options based on
those requirements, plus user preferences as to whether profiling
or debugging are enabled, and then we do:

     --no-libgrade $(LIBGRADE_FLAGS)

in the config file.

(If that configuration system had been written several years later
I guess we would have used --libgrade-{include,exclude}, but they
didn't exist at the time.)

>> 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.)
>
> While the above is a useful goal, I would point out that it is also sort-of
> dangerous, unless accompanied by *some* mechanism for ensuring
> that the newly installed library files are compatible with the existing ones.
> If e.g. the old one has module_a.p/3, but the new one has module_a.p/4,
> and neither has the one in the other, then recompiling a user program
> after switching grade may yield an unexpected error.

All true, but that's a separate problem. For stable releases it
shouldn't be too much of a problem unless whoever is packging it somehow
mixes incomptible versions, otherwise dependency management is
(allegedly) one of the things that package managers are supposed to do.

Julien.