[m-rev.] for review: updates for non-C grades in user's guide

[Julien Fischer]

Hi Zoltan,

On Sun, 21 Jun 2020, Zoltan Somogyi wrote:

> 2020-06-21 16:51 GMT+10:00 Julien Fischer<jfischer at opturion.com>:

>> diff --git a/README.Java b/README.Java
>> index 49647cb..d8c547d 100644
>> --- a/README.Java
>> +++ b/README.Java
>> @@ -44,7 +44,7 @@ Now you can run hello
>>
>>  Note that hello is a simple shell script that invokes the program using the
>>  Java interpreter.  The actual class files are stored in the Mercury
>> -subdirectory in `classs'.  These class files will be packaged up into Java
>> +subdirectory in `classs'.  These class files will be packaged up into a Java
>>  archive (JAR) named `hello.jar'.
>
> I think that `classs' needs to be followed by (a) a confirmation that the triple s
> is not a typo, and (b) an explanation of the naming scheme that adds the third s.\

Actually, I've just deleted that sentence. At the time it was written
`Mercury/classs` was the only location that the generated class files
were placed. As mentioned by the following line we now package them up
into JAR files and it is those that users (and wrapper shell scripts)
should be using.

>> @@ -234,8 +234,10 @@ by the Mercury compiler. The non-standard extensions are necessary
>>  to avoid conflicts with system header files.
>>  @file{.java}, @file{.class} and @file{.jar} files are Java source code,
>>  Java bytecode and Java archives respectively.
>> - at file{.cs} files are C# source code.
>> - at c XXX mention .dll and .exe?
>> + at c when we support shared libraries on Windows .dll will also be used for them.
>> + at file{.cs} files are C# source code, @file{.dll} files are library
>> +assemblies and, when compiling to C#, @file{.exe} files are process
>> +assemblies.
>>  @file{.erl} and @file{.beam} files are Erlang source code and
>>  bytecode (object) files respectively.
>
> It may be a good idea to put the descriptions of the file kinds specific
> to each target language in separate paragraphs.

I'll do that as a separate change, since it's very much an existing
problem.

>>  @file{.beams} directories are collections of @file{.beam} files which
>> @@ -247,12 +249,11 @@ act like a library archive.
>>  @chapter Using the Mercury compiler
>>  @cindex Microsoft Management Console
>>
>> -Following a long Unix tradition,
>> -the Mercury compiler is called @samp{mmc}
>> +The Mercury compiler is called @samp{mmc}
>>  (for ``Melbourne Mercury Compiler'').
>>  @pindex mmc
>>  Some of its options (e.g.@: @samp{-c}, @samp{-o}, and @samp{-I})
>> -have a similar meaning to that in other Unix compilers.
>> +have a similar meaning to that in other compilers.
>>
>>  (Note that on Microsoft Windows systems the name @samp{mmc} is also used by the
>>  executable for the Microsoft Management Console.
>
> I would add a comma after "systems".

Done.

> Do we explain anywhere what users need to do if "mmc" resolves to the Windows
> management console for them? If not, we should.

The sentence that immediately follows does just that.

>> @@ -277,27 +278,65 @@ This argument processing is done recursively.
>>  The contents of the @samp{@@file} is split into arguments
>>  one per line in the file.
>>
>> -To compile a program which consists of just a single source file,
>> -use the command
>> +To compile a program that consists of a single source file, use the command
>>
>>  @example
>>  mmc @var{filename}.m
>>  @end example
>>
>> -Unlike traditional Unix compilers, however,
>> - at samp{mmc} will put the executable into a file called @file{@var{filename}},
>> -not @file{a.out}.
>> +Note that compiling a single source file as above only works when targeting C;
>> +if you are generating C#, Java or Erlang you must use the @samp{--make} option.
>> +For programs that consist of more than one source file, you can use + at samp{--make} option to @samp{mmc}, or Mmake (@pxref{Using Mmake}).
>> +Note that Mmake only works when targeting C; if you are generating C#, Java or
>> +Erlang you must use the @samp{--make} option.
>
> All of the above is likely to be confusing. In my experience, if you what you write
> follows the schema "Do action A. But if condition C holds, then do action B instead",
> then people will do A as soon as they have read the first sentence, even if
> condition C holds. (I got this is a lot in lab classes). I have learned to put the
> conditions up front.
>
> If you don't want to take a stab at such a rewriting, I will do it after you commit.

I'm not entirely sure what you have mind, so please do.

>> +The use of @samp{mmc --make} is recommended.
>
>> +When targeting C on systems that do not require an executable file extension,
>> + at samp{mmc} will put the executable into a file called @file{@var{filename}}; on
>> +systems that use the @file{.exe} executable file extension (e.g. Windows) the
>> +executable will be put into a file called @file{@var{filename}.exe}.
>
> I would reword the second half as
>
> on systems (such as WIndows) that use .exe as the file extension for executables,
> mmc will put the executable into a file called filename.exe.

Done.

>> +When targeting C#, @samp{mmc} will generate a process assembly called
>> + at file{@var{filename}.exe}.
>> +On non-Windows systems, @samp{mmc} will also generate a shell script called
>> + at file{@var{filename}} that invokes the CLI execution environment
>> +on the process assembly.
>> +On Windows, the process assembly can be run directly and nothing further
>> +is required.
>
> Nothing further than *what* is required?
>
> I would reword as
>
> On Windows, this process assembly can be run directly (hence the .exe suffix).

Done, although I've omitted the bit in parentheses since for C# the .exe
extension is present on every system, regardless of whether the it can
be run directly or not.
(On Linux you can run process assemblies directly by registering the
appropriate things with the kerenl using binfmt, but that's beyond
the scope of the Mercury documentation and it's not the usual setup
on most Linux systems anyway.)

> On non-Windows systems, which cannot run process assemblies directly,
> mmc will also generate a shell script called filename that invokes the CLI
> execution environment on the process assembly.
>
>> +(See the file @file{README.CSharp} included in the Mercury distribution for
>> +further details.)
>
> I would reverse the pointer; i.e. I would move the discussion of Mono and .NET
> from README.CSharp to here.

I'll deal with that as a separate change; that discussion really needs
to go into a separate section as including it disrupts the flow of this
one too much.

>> +When targeting Java, @samp{mmc} will package up all of the class files for the
>> +executable into a Java archive (JAR) named @file{@var{filename}.jar}.
>> +It will also generate a shell script called @file{@var{filename}} that invokes
>> +the program using the Java interpreter.
>> +If you are using the Windows command line interpreter, @samp{cmd.exe},
>
> Is cmd.exe usually described as an interpreter?

That's what Microsoft call it ;-)

>>  then
>> + at samp{mmc} will generate a batch file called @file{@var{filename}.bat} that
>> +invokes the program using the Java interpreter instead.
>
> Instead of what?

I meant that it will generate a batch file instead of a shell script.
Reworded as:

    If you are using the Windows command line interpeter, @samp{cmd.exe},
    then instead of a shell script, @samp{mmc} will generate a batch file called
    @file{@var{filename}.bat} that invokes the program using the Java
    interpreter.
>
>> +(See the file @file{README.Java} included in the Mercury distribution for
>> +further details.)
>
> I would do the same shuffle here.

I've deleted that line; README.Java doesn't provide any more information
on how to invoke Java grade exectutables than what is here.

>> +When targeting Erlang, @samp{mmc} will place all of the object files for
>> +the executable into the subdirectory @file{Mercury/beams}.
>> +It will also generate a shell script named @file{@var{filename}} that starts
>> +the Erlang runtime system and runs the program.
>> +If you are using the Windows command line interpreter, @samp{cmd.exe}, then
>> + at samp{mmc} will generate a batch file called @file{@var{filename}.bat} that
>> +starts the Erlang runtime system and runs the program instead.
>
> Again, instead of what?
>
>> +(See the file @file{README.Erlang} included in the Mercury distribution for
>> +further details.)
>
> And here.

Also deleted, for the same reason as Java.

>>  @noindent
>> -If you use Mmake or @samp{mmc --make}, then you don't need to understand the
>> +If you use Mmake or @samp{mmc --make}, then you do not need to understand the
>>  details
>>  of how the Mercury implementation goes about building programs.
>>  Thus you may wish to skip the rest of this chapter.
>> @@ -388,9 +427,9 @@ the name of the C file of every module in the program.
>>  The order of the arguments is not important.
>>  The @samp{mgnuc} command is the Mercury GNU C compiler;
>>  it is a shell script that invokes the GNU C compiler @samp{gcc}
>> - at c (or some other C compiler if GNU C is not available)
>>  with the options appropriate for compiling
>>  the C programs generated by Mercury.
>> +Despite the name, it can be used with C compilers other than GNU C.
>
> I would reword the line above the deleted comment as
>
> it is a shell script that invokes the configured C compiler
>
> and then replace the line you added with
>
> (In the early days of the Mercury project, the configured C compiler
> was almost always gcc, which is why the name of the script is what it is,
> but the script itself will work with clang or MSVC as well.)

Done, that's a better way of putting it.

>> @@ -1041,6 +1081,8 @@ library should be created: @samp{shared} or @samp{static}. The
>>  @samp{--lib-linkage} option can be specified multiple times.
>>  In our example, the files @samp{libmypackage.a} and @samp{libmypackage.so}
>>  should appear in the current directory.
>> +(On macOS @samp{libmypackage.dylib} will appear instead of
>> + at samp{libmypackage.so}.)
>
> Again, I would put the condition (which in this case is the OS) up front.

Again, not quite sure what you had in mind.

>> @@ -1348,31 +1390,23 @@ EXTRA_LIBRARIES-foo = mylib4foo
>>  @cindex jar files
>>  @cindex Java libraries
>>
>> -Libraries are handled a little differently for the Java grade.  Instead of
>> -compiling object code into a static or shared library, the class files are
>> -added to a jar (Java ARchive) file
>> -whose name has the form @file{@var{library-name}.jar}.
>> -
>> -To create or install a Java library, simply specify that you want to use the
>> -java grade, either by setting @samp{GRADE=java} in your Mmakefile, or by
>> -including @samp{--java} or @samp{--grade java} in your @samp{GRADEFLAGS}, then
>> -follow the instructions as above.
>> +To create or install a library in the Java grade, specify that you want to
>> +use the Java grade and use @samp{mmc --make}.
>> +Mmake does @emph{not} support Java targets.
>>
>> -Java libraries are installed to the directory
>> - at file{@var{prefix}/lib/mercury/lib/java}.  To include them in a program, in
>> -addition to the instructions above, you will need to include the installed jar
>> -file in your @samp{CLASSPATH}, which you can set using
>> - at samp{--java-classpath @var{jarfile}} in @samp{MCFLAGS}.
>> +Libraries are compiled to class files that are added to a Java archive (JAR)
>> +file whose name has the form @file{@var{library-name}.jar}.
>
> This chunk of the diff deletes some information it does not replace.
> Is this intentional, and if so, why?

It is intentional. There are two pieces of information there:

1. Where libraries are installed in the java grade.  This is redundant,
the layout we use for library installation directories is described
elsewhere and the java grade follows that layout.

2. Using --java-classpath option directly to add a Mercury library to
the CLASSPATH of the Java compiler has not been necessary for a very
long time.  You can (and should) just use the --mercury-library option
as with libraries in any other grade. The Mercury compiler will handle
the construction of the CLASSPATH for the Java compiler automatically.

> Other than the above, the diff is fine.

Thanks for that; I'll commit this with the changes above and make
the other changes later this week.

Julien.