[m-rev.] for post-commit review: update description of module compilation

[Julien Fischer]

On Sun, 31 Aug 2025 at 23:24, Zoltan Somogyi <zoltan.somogyi at runbox.com>
wrote:
> Update the description of module compilation.

...


> diff --git a/doc/mercury_user_guide.texi b/doc/mercury_user_guide.texi
> index 81dd36224..231dbeced 100644
> --- a/doc/mercury_user_guide.texi
> +++ b/doc/mercury_user_guide.texi
> @@ -2370,6 +2370,8 @@ specifically, the subset that come after
@var{module_3} in the module order.
>  @node Creating target and object code files
>  @section Creating target and object code files
>
> + at heading Compiling Mercury programs in C grades
> +
>  To compile a Mercury source file to C code,
>  use a command such as
>
> @@ -2380,16 +2382,30 @@ mmc --grade asm_fast.gc -C @var{module_name}.m
>  @findex --target-code-only
>
>  On that command line,
> -the @code{--grade asm_fast.gc} part obviously specifies the grade,
> -while the @code{-C} option,
> -whose long name is @code{--target-code-only},
> +the @command{--grade asm_fast.gc} part obviously specifies the grade,

Delete "obviously".

Use @option rather than @command where appropriate here and elsewhere below.

> +while the @command{-C} option,
> +whose long name is @command{--target-code-only},
>  tells the compiler to stop after generating the target language file
>  (in this case, @file{@var{module_name}.c}).
>
> -You can then compile @file{@var{module_name}.c} to @file{@var
{module_name}.o},
> +You can then
> +compile @file{@var{module_name}.c} to @file{@var{module_name}.o}
yourself,
>  or you can tell the Mercury compiler to do this for you.
> -To compile a source file not just to C code but to object code,
> -use the command
> +
> +The command for doing it yourself is a command such as
> + at example
> +mgnuc --grade asm_fast.gc -- -c @var{module_name}.c -o
@var{module_name}.o
> + at end example
> +
> +The part of the command line
> +between the command name (@command{mgnuc})
> +and to the double dash (@command{--})
> +contains the options interpreted by @command{mgnuc},
> +while the part after the double dash contains options
> +for the configured C compiler (usually gcc, clang, or MSVC).

I don't think you need to list the C compilers there.

> +The command that tells the Mercury compiler
> +to generate both the @file{.c} and @file{.o} file of a module is
>
>  @example
>  mmc --grade asm_fast.gc -c @var{module_name}.m
> @@ -2397,14 +2413,63 @@ mmc --grade asm_fast.gc -c @var{module_name}.m
>  @findex -c
>  @findex --compile-only
>
> -The @code{-c} option, whose long name is @code{--compile-only},
> +The @command{-c} option, whose long name is @command{--compile-only},
>  tells the compiler to stop after compiling the Mercury code into object
code.
> -(In grades that target Java,
> -it tells the compiler to stop after generating @file{@var
{module_name}.class},
> -and In grades that target C#,
> -it tells the compiler to stop after generating @file{@var
{module_name}.dll},
> -since these file types are the equivalents of object files
> -for these target languages.)
> +
> +If the source file contains nested modules,
> +then both the main module in the file,
> +and all the submodules nested inside it, directly or indirectly,
> +will all get compiled
> +first to separate @file{.c} files,
> +and then to separate @file{.o} files.
> +
> + at heading Compiling Mercury programs in Java grades
> +
> +In grades that target Java,
> + at command{-C} (@command{--target-code-only}) tells the compiler to stop
> +after generating @file{@var{module_name}.java}:
> +
> + at example
> +mmc --grade java -C @var{module_name}.m
> + at end example
> +
> +while @command{-c} (@command{--compile-only})
> +tells the compiler to stop
> +after generating @file{@var{module_name}.class}:
> +
> + at example
> +mmc --grade java -c @var{module_name}.m
> + at end example
> +
> +since @file{.class} files are the Java equivalents of object files for C.
> +
> +If the source file contains nested modules,
> +then both the main module in the file,
> +and all the submodules nested inside it, directly or indirectly,
> +will all get compiled
> +first to separate @file{.java} files,
> +and then to separate @file{.class} files.

You should mention that both the .java and .class files created by the
above examples will be placed in a directory named jmercury.

...

> diff --git a/scripts/mgnuc.in b/scripts/mgnuc.in
> index fcb9a2d3c..4b83a6527 100644
> --- a/scripts/mgnuc.in
> +++ b/scripts/mgnuc.in
> @@ -9,10 +9,6 @@
>  # This file may only be copied under the terms of the GNU General
>  # Public License - see the file COPYING in the Mercury distribution.
>
 #---------------------------------------------------------------------------#
> -#
> -# IMPORTANT: the manpage is produced automatically from this help
> -# message, so if you change the help message, don't forget to check
> -# that the manpage still looks OK.
>
>  #
*************************************************************************
>  # *** IMPORTANT NOTE: any changes to this file may also require similar
***
> @@ -121,9 +117,12 @@ halt_at_warn_if_possible=false
>  # include the file `init_grade_options.sh-subr'
>  @INIT_GRADE_OPTIONS@
>
> +# IMPORTANT: The manpage is produced automatically from this help
message,
> +# so if you change it, do not forget to check that the manpage still
looks OK.
> +
>  Help="\
>  Name:   mgnuc - Mercury front-end to GNU C
> -Usage:  mgnuc [<options>] [-- <gcc options>] files...
> +Usage:  mgnuc [<options>] [-- <gcc/clang/msvc options>] files...

One minor point; if msvc is an option, then this script cannot really be
a "front-end to GNU C".  Perhaps, we should just s/GNU C/C/.

Also, I would just say "C compiler options" rather than listing specific
C compilers.

>  Options:
>      -v, --verbose
>          Echo gcc command before executing it.
> @@ -152,8 +151,9 @@ Options:
>  ${grade_usage}
>
>  Description:
> -    This runs gcc with the appropriate options for compiling Mercury
programs.
> -    Normally it invokes gcc with almost all warnings enabled,
> +    This command runs the configured C compiler (usually gcc, clang, or
msvc)

Again, I would not list the C compilers there.

> +    with the appropriate options for compiling Mercury programs.
> +    Normally it invokes the C compiler with almost all warnings enabled,
>      but this can be changed using \`--no-check' option.
>  Environment variables:
>      MERCURY_DEFAULT_GRADE.

The rest looks fine.

Julien.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mercurylang.org/archives/reviews/attachments/20250902/acffa6ab/attachment.html>