[m-rev.] for post-commit review: propose a new structure for options.m

[Julien Fischer]

Hi,

I realise it's rather late in the day for a review of this.

On Wed, 4 Jun 2025 at 12:38, Zoltan Somogyi <zoltan.somogyi at runbox.com> wrote:
>
> Propose a new structure for options.m.

...

> diff --git a/compiler/options.m b/compiler/options.m
> index c55f4b2c1..74e3d0dc7 100644
> --- a/compiler/options.m
> +++ b/compiler/options.m

...

> @@ -1273,6 +1331,7 @@ option_defaults(Opt, Data) :-
>
>  :- type option_category
>      --->    oc_help
> +            % The one option that calls for output of help text.
>
>      ;       oc_warn_dodgy
>              % Warnings about code that is possibly incorrect.
> @@ -1282,27 +1341,61 @@ option_defaults(Opt, Data) :-
>              % Warnings about programming style.
>      ;       oc_warn_ctrl
>              % OPtions that *control* warnings.
> +            % XXX Split into subparts, one for each of oc_warn_*
> +            % that some now-oc_warn_ctrl option controls.
> +            % This should enable us to put the documentation of e.g.
> +            % inform_incomplete_switch_threshold, immediately after
> +            % the documentation of inform_incomplete_switch.
>      ;       oc_warn_halt
>              % Options that specify when warnings should treated as errors.
>      ;       oc_inform
>              % Requests for information.
>      ;       oc_verbosity
> +            % Options that users can use to control how many progress updates
> +            % they want the compiler to give them.
>      ;       oc_opmode
>              % Options that are used only to select an invocation's op_mode.
>      ;       oc_aux_output
> +            % Options that ask the compiler to modify some aspect
> +            % of the generated target code.
> +            % XXX This name is non-descriptive.
> +            % XXX We now also use it for things that the above description
> +            % does not cover. We should put them into other categories.
>      ;       oc_semantics
>              % Options that specify which semantics variant to use.
>      ;       oc_grade
> +            % Options that affect binary compatibility.
>      ;       oc_internal
> -            % Options that should not be used even by developers.
> -    ;       oc_codegen
> -    ;       oc_spec_opt
> +            % Options for compiler use only, that should not be used
> +            % even by developers.
>      ;       oc_opt
> +            % Optimization options that are enabled at -O<N> for some N.
> +            % XXX Rename to oc_level_opt?
> +            % XXX We should subdivide into HLDS->HLDS, HLDS->MLDS, HLDS->LLDS,
> +            % MLDS->MLDS, LLDS->LLDS, MLDS->target, LLDS->target,
> +            % maybe indicated by _hh, _hm, _hl etc suffixes,
> +            % to allow automatic generation of the existing help subsections.
> +    ;       oc_spec_opt
> +            % Optimization options that are not enabled at -O<N> for any N.
> +            % XXX Rename to oc_sep_opt, with "sep" standing for "separate
> +            % from optimization levels", or oc_sa_opt, with "sa" being short
> +            % for "stand-alone"?
> +            % XXX Subdidivde as with oc_opt.
>      ;       oc_opt_ctrl
>              % Options that control optimization levels.
>      ;       oc_target_comp
> +            % Options that control how the target language files we generate
> +            % are further compiled.
> +            % XXX Subdivide into oc_target_c/oc_target_java/oc_target_csharp.
>      ;       oc_link
> +            % Options that control how executables, or their equivalents
> +            % for some target languages, are generated.
> +            % XXX Subdivide into oc_link_c/oc_link_java/oc_link_csharp.
> +            % XXX Are the oc_link options that apply to more than one target?

At the moment, I don't think so. --runtime-flags could in principle be supported
across multiple target languages. (A subset of the C runtime flags are supported
the Java backend.)

--output-file *should* be supported across all backends, but the fact that its
NYI for --make means that it is not currently usable with C# or Java.

>      ;       oc_buildsys
> +            % XXX Document me.
> +            % XXX We should separate search path options (the majority)
> +            % from everything else.
>      ;       oc_dev_ctrl
>              % Options developers can use to control what the compiler does.
>      ;       oc_dev_debug

...

> @@ -1608,6 +1707,7 @@ optdef(oc_semantics, reorder_conj,                      bool(yes)).
>  optdef(oc_semantics, reorder_disj,                      bool(yes)).
>  optdef(oc_semantics, fully_strict,                      bool(yes)).
>  optdef(oc_semantics, allow_stubs,                       bool(no)).
> +% XXX These stretch the definition of "semantics" beyond the breaking point.
>  optdef(oc_semantics, infer_types,                       bool(no)).
>  optdef(oc_semantics, infer_modes,                       bool(no)).
>  optdef(oc_semantics, infer_det,                         bool(yes)).

oc_infer?

> @@ -1770,7 +1870,7 @@ optdef(oc_internal, type_check_constraints,             bool(no)).
>      % Code generation options.
>
>  optdef(oc_dev_debug, table_debug,                        bool(no)).
> -optdef(oc_codegen,  trad_passes,                         bool(yes)).
> +optdef(oc_dev_ctrl, trad_passes,                         bool(yes)).
>  optdef(oc_dev_ctrl, parallel_liveness,                   bool(no)).
>  optdef(oc_dev_ctrl, parallel_code_gen,                   bool(no)).
>  optdef(oc_internal, reclaim_heap_on_failure,             bool_special).
> @@ -1785,8 +1885,11 @@ optdef(oc_config,   num_real_r_temps,                    int(5)).
>  optdef(oc_config,   num_real_f_temps,                    int(0)).
>      % The `mmc' script will override the above defaults with
>      % values determined at configuration time.
> -optdef(oc_codegen,  max_jump_table_size,                 int(0)).
> -    % 0 indicates any size.
> +optdef(oc_config,   max_jump_table_size,                 int(0)).
> +    % 0 indicates jump tables can be any size.
> +    % XXX This option works around limitations in 1998 C compilers.
> +    % Its value should be set automatically by handle_options.m
> +    % based on the value of the c_compiler_type option.

As I am sure you are aware, this option predates the addition of
c_compiler_type. There are two C compilers that require this:

1. lcc -- this no longer an issue as Mercury can no longer be
   built with lcc.

2. MSVC -- the configure sets the maximum jump table size to 512
   "to avoid a fixed limit in the compiler".

>  optdef(oc_internal, max_specialized_do_call_closure,     int(5)).
>      % mercury.do_call_closure_N exists for N <= option_value;
>      % set to -1 to disable. Should be less than or equal to
> @@ -2224,14 +2327,17 @@ optdef(oc_buildsys, target_env_type,                    string("posix")).
>      % Miscellaneous options
>
>  optdef(oc_misc,     filenames_from_stdin,               bool(no)).
> +% XXX Should we add new category, named maybe oc_errors, for options
> +% that control how and/or when the compiler generates diagnostics?
> +% Include options that reverse the order of errors, or limit error contexts.

oc_errors seems a poor name as presumably these options also control the same
aspects for warnings.  I would be prefer something like oc_diag_out or
oc_diag_fmt.

I agree with the rest of the proposals.

Julien.