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

[Peter Wang]

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.

> 
> - make it an only_opmode option.

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.

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

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

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

Peter