[m-rev.] for post-commit review: document the rest of the PROPOSED search options

[Julien Fischer]

On Sat, 21 Dec 2024 at 11:53, Zoltan Somogyi <zoltan.somogyi at runbox.com> wrote:

> Document the rest of the PROPOSED search options ...
>
> ... and rename "normal" to "interface" in the compiler's code.
>
> doc/user_guide.texi:
>     Document the rest of the PROPOSED search options.
>
> compiler/options.m:
>     Change the user-facing names of the PROPOSED search options
>     to the now-documented names.
>
>     Change "normal" to "interface" in these option names.
>
> compiler/file_names.m:
> compiler/find_module.m:
> compiler/globals.m:
>     Change "normal" to "interface" in search specifications.
>
> compiler/generate_dep_d_files.m:
> compiler/handle_options.m:
> compiler/make.get_module_dep_info.m:
> compiler/read_modules.m:
>     Conform to the name changes above.




> diff --git a/compiler/options.m b/compiler/options.m
> index 634467979..05e364ae1 100644
> --- a/compiler/options.m
> +++ b/compiler/options.m

...

> diff --git a/doc/user_guide.texi b/doc/user_guide.texi
> index 5548e918e..bcb3806ea 100644
> --- a/doc/user_guide.texi
> +++ b/doc/user_guide.texi
> @@ -10054,6 +10054,54 @@ Note that if you want to override this list, rather than append to it,
>  then you can set the @env{MERCURY_MC_ALL_C_INCL_DIRS} environment variable
>  to a sequence of @samp{--c-include-directory} options.
>
> + at c @sp 1
> + at c @item --c-include-dir-same-workspace @var{workspace_directory}
> + at c @itemx --c-inc-dir-same-ws @var{workspace_directory}
> + at c @sp 1
> + at c @itemx --c-include-dir-independent-workspace @var{workspace_directory}
> + at c @itemx --c-incl-dir-indep-ws @var{workspace_directory}
> + at c @sp 1
> + at c @itemx --c-include-dir-installed-library @var{install_directory}
> + at c @itemx --c-incl-dir-installed-lib @var{install_directory}
> + at c
> + at c @findex --c-include-dir-same-workspace
> + at c @findex --c-incl-dir-same-ws
> + at c @findex --c-include-dir-independent-workspace
> + at c @findex --c-incl-dir-indep-ws
> + at c @findex --c-include-dir-installed-library
> + at c @findex --c-incl-dir-installed-lib
> + at c @cindex Directories
> + at c @cindex Search path
> + at c Append either the named workspace directory,
> + at c or the named library install directory,
> + at c to one of three separate lists of directories that
> + at c the Mercury compiler tells the C compiler to search for C header files.
> + at c These header files include
> + at c @samp{.mh} and @samp{.mih} files generated by the Mercury compiler,
> + at c as well as any user-provided @samp{.h} files
> + at c that the user has asked the Mercury system to install
> + at c using @samp{--extra-library-header} options.
> + at c Any workspace directory
> + at c named by a @var{--c-include-dir-same-workspace} option
> + at c (or its abbreviated synonym)
> + at c should set the same values
> + at c for the @samp{--use-subdir} and @samp{--use-grade-subdir}
> + at c as the current workspace directory;
> + at c this restriction does not apply to workspace directories
> + at c named in a @var{--c-include-dir-independent-workspace} option
> + at c (or its abbreviated synonym).
> + at c The compiler will first search the workspace directories
> + at c named in @var{--c-include-dir-same-workspace} options,
> + at c second it will search the workspace directories
> + at c named in @var{--c-include-dir-independent-workspace} options,
> + at c and third it will search the library install directories
> + at c named in @var{--c-include-dir-installed-library} options
> + at c (or its abbreviated synonym).

For C header files specifically, there's an extra wrinkle. The existing
--c-include-dir option is also (ab)used to get the Mercury compiler to
tell the C compiler where to find header files for C libraries that are
used by a Mercury program. I think we probably want to keep it around
for that purpose, since:

   --c-include-dir /path/to/some/c/lib

is less cumbersome than:

   --c-flags "-I /path/to/some/c-lib"

> + at c XXX Should we add something to specify that unlike the legacy options,
> + at c the arguments of these options never require any directory name components
> + at c that would be added by --use-subdirs/--use-grade-subdirs?

Would it suffice to say that if those options are used, then the
directory specified
by the option argument is the one containing the Mercury directory?

The diff looks fine otherwise.

Julien.