[m-dev.] proposal for a new structure for the inital chapters of the user guide

[Zoltan Somogyi]

On Thu, 17 Jul 2025 02:18:43 +1000, Julien Fischer <jfischer at opturion.com> wrote:
> > Can we actually do so in a non-confusing manner? The reason I ask is that
> > when given "mmc x.m", we don't know in advance whether this is
> >
> > - the compilation of a single-module program, or
> > - the compilation of one module of a multi-module program that is missing a -c,
> >   or the specification of some libraries to link against, or something similar.
> >
> > We don't know which is the case until the linker exits, by which time
> > we have already put the .c and .o files (when targeting C) *somewhere*.
> 
> If you try to compile a multi-module program using mmc x.m you will get
> an error about missing interface files, it never gets anywhere near the linker.

If the interface files are in fact missing. In the case of a missing "-c",
they may have been built before. And a mismatch between search paths
may allow the interface files of an intended-to-be-linked library being found,
but its .a or .so file not being found, though in that case calling it
a "single-module program" is stretching things.

> The argument for this is that beginner users are more likely to be
> using single-module
> compilation

Non-beginners can also forget to add "-c", but I expect you are right.

> and not having the compiler spew generated files
> all over the current working directory is probably less confusing than any
> sudden manifestations of Mercury subdirs.

I would think that would depend greatly on the behavior of the compilers
of the other languages they were used to. (If they can even tell, given that
many people use IDEs.)

> (I would imagine this class of
> users are *not* using the -c option.)

That we agree on.

Note that the reason why I think creating Mercury directories
implicitly is a bad idea is that their mere presence implies the use of
--use-subdirs from the time of their creation to the time of their deletion.
If I give a command that I expect to generate a file in the current directory,
and don't get it (because the file was put inside Mercury instead),
I would be puzzled and somewhat angered by this "spooky action at a distance",
as Einstein would have put it. This is why I committed changes recently
deleting stray Mercury directories in tests/* left by C# and Java bootchecks.
Those directories screwed up all subsequent C bootchecks until their deletion.

Zoltan.