[m-dev.] proposal: rename the --generate-module-order option

[Zoltan Somogyi]

On Tue, 19 Aug 2025 13:32:38 +1000, Peter Wang <novalazy at gmail.com> wrote:

> On Mon, 18 Aug 2025 17:41:58 +0200 "Zoltan Somogyi" <zoltan.somogyi at runbox.com> wrote:
> > This option does not do anything on its own; it is only ever
> > consulted when making dependencies. I propose that we
> > 
> > - rename it to --generate-dependencies-record-trans-opt-order,
> >   or preferably something shorter that still gets its purpose across,
> >   and
> 
> I think the module order doesn't necessarily have to do with trans-opt
> files, so I would remove that part of it.

As you mention below, opt_deps_spec.m generates both .order
and .order_trans_opt files, the latter of which is specifically for .trans_opt
files, so I will document that.

> The --generate-module-order option used to imply --generate-dependencies
> until commit 1fcdc4cdc. You wrote:
> 
>     the new documented (and implemented) behavior is actually more useful,
>     since it allows both options to be specified in Mmakefiles or
>     Mercury.options files, have them be acted on when making dependencies,
>     but not get error messages about incompatible op mode options.
> 
> Making it an only_opmode option is fine by me, but contradicts the
> benefit you mentioned.

Yes, that is a good point. 

The problem I was trying to solve is that "mmc --generate-module-order prog.m"
*looks* like it should do something (generate a .order file) that it does not do.
Maybe a better solution is to rename the option to remove that impression.
Some name such as --output-module-order-files-when-generating-dependencies
would be expressive enough, but also too long. Does anyone have a shorter name
that still works?

- the ability of 
> > That's one proposal. The other is that regardless of whether
> > we do the above or not, the name of the file we output to
> > should be main_module.trans_opt_order, not simply main_module.order,
> > since the former is much more expressive.
> > 
> > Opinions?
> 
> Actually, there's another "module order" file. The second file is named
> .order_trans_opt. It records the module order for the purposes of making
> .trans_opt files, which is affected by the --trans-opt-deps-spec option.

Looking at the code of compute_opt_trans_opt_deps_graph,
the first file records the contents of ImpDepsGraph, while the second
records the contents of TransOptDepsGraph. In the absence of
--trans-opt-deps-spec, TransOptDepsGraph will be the transitive closure
of ImpDepsGraph. My graph theory is a bit rusty, but my intuition says
that the list of SCCs of the transitive closure should be the same as
the list of the SCCs of the original graph. Does anyone know for sure?

I am asking purely for the purpose of how to word the user guide.
I know that the second file is worthwhile regardless of the answer,
since the application of --trans-opt-deps-spec definitely *can*
change the result.

> Maybe name the two files something like .module_order and
> .module_order_for_trans_opt?

I agree, those are better names.

> > the trans_opt part of the "compilation in detail" chapter,
> > and I am not sure how the order works. It was originally
> > purely lexicographic order, but I know Peter has made
> > significant changes. I know these changes include deleting
> > edges from the dependency graph from which we can compute
> > a better, non-lexicographic order, and I know that the option
> > for deleting edges is private, but I don't know (a) why is it
> > private,(b) whether the whole computing-the-order-
> > nonlexicographically-from-dependencies system is private
> > as well, and (c) where the order is recorded (outside of the
> > .order file, which, since its creation is optional, I presume
> > the implementation itself does not use.)
> > 
> > Peter, can you please enlighten me?
> 
> The mechanism for breaking up SCCs in the dependency graph is the
> --trans-opt-deps-spec option. The file used for the standard library
> is library/mer_std.trans_opt_deps_spec. The file format is currently
> only documented in the comment above read_trans_opt_deps_spec_file.
> 
> I have no objection if you want to document the option and make it
> public, now that it has been tested for a while. Few users should need
> it, since transitive intermodule optimization does not work with
> mmc --make. And, if other projects have a large cycle in their
> dependency graph, they can probably better solve the problem by
> reorganising their modules than using this special (hacky) mechanism.

Thanks for that info. But it seems I did not phrase question (c) well.
When the compiler is asked to build module_x.trans_opt, where does
the compiler get a list of the .trans_opt files that it is allowed to read
in the process? That is program-level, not module-level info, so it
must be transmitted from "mmc --generate-dependencies prog.m"
to "mmc -make-transitive-optimization-interface module_x.m"
by being stored in an agreed-upon place. What is that place?
Is it an mmakefile fragment file? If yes, which one? prog.dep? prog.dv?
In that case, how does the compiler know which program module_x
is part of, when it could be part of several? Is it module_x.d?
And in any case, which variable or rule in the file?

Zoltan.