[m-dev.] for review: developer introduction for webpage

[Zoltan Somogyi]

On 16-Jan-2001, Tyson Dowd <trd at cs.mu.OZ.AU> wrote:
> +The first thing to realize is that when you install the compiler, you
> +don't have to install all the grades.  You can set the make variable
> +LIBGRADES to set the list of "extra" grades to install.  If you set it
> +to empty, it will install only the default grade (probably asm_fast.gc).
> +<p>
> +A good way to do this is to create (or modify an existing) Mmake.params
> +file in the top-level of the mercury distribution (in the same directory
> +as README and NEWS).  Mmake.params is used to set local workspace
> +options and is very useful for overriding default mmake settings.
> +Add the line
> +<pre>
> +LIBGRADES=
> +</pre>
> +and you won't have to wait for all those grades to be installed.

You should also mention that you can also select LIBGRADES at configuration
time.

> +<h2>Quick installation of subsystems</h2>
> +
> +It's also worth noticing that each subsystem (the runtime, the compiler,
> +the library, etc) can be installed by itself.  If you make a change to the
> +compiler, you can install it with
> +<pre>
> +cd compiler ; mmake install
> +</pre>
> +Be aware that this will only install one grade -- if you want to install
> +just the library in all the grades in LIBGRADES, try:
> +<pre>
> +cd compiler ; mmake install
> +</pre>

I have never done the above, and I think the advice you give there is
dangerous, since novices cannot be expected to understand the implications
of installing subsystems separately, since they don't know all the subsystem
interdependencies. This section should be deleted.

> +If you've made changes to the compiler or library that you think are
> +working fine, you may want to make sure you haven't messed up some other
> +part of the compiler.

Not "may want to"; "should".

> +Stage 3 uses the stage 2 Mercury compiler to build another Mercury
> +compiler.  This ensures that the stage 2 Mercury compiler not only
> +builds, but actually works.  Stage 3 actually just compares the output
> +of stage 1 and stage 2 compilers -- if they generate exactly the same code,
> +everything is good.  If they generate different code, something bad must
> +have happened, chances are the code generated by the stage 1 compiler is
> +wrong, and so compiler we used to generate stage 2 is probably executing
> +incorrectly (and so it's output is different to the output of the
> +compiler before hand).  If this happens, the compiler doesn't
> +"bootstrap" -- it cannot reliably compile itself.

Replace with:

Bootcheck then uses the stage 2 Mercury compiler to build the C files of
another Mercury compiler, the stage 3 compiler, and compares them with the
C files of the stage 2 compiler, which were built by the stage 1 compiler.
If they differ, then the stage 2 compiler does not execute the same algorithm
as the stage 1 compiler. Since the stage 1 and 2 compilers were built from the
same source, the difference must have been introduced by differences in the
compilers used to compile that source. Since stage 1 was compiled with a
trusted compiler, the compiler used to generate the stage 2 executable (i.e.
the stage 1 compiler) must be buggy. If this happens, the compiler doesn't
"bootstrap" -- it cannot reliably compile itself.

> +<p>
> +Finally, if you have checked out the "tests" module from CVS, the
> +bootcheck will use the stage 2 compiler, library and runtime to run all
> +the tests in the testing hierarchy.

Not "if"; running the test cases should be mandatory.

Zoltan.
--------------------------------------------------------------------------
mercury-developers mailing list
Post messages to:       mercury-developers at cs.mu.oz.au
Administrative Queries: owner-mercury-developers at cs.mu.oz.au
Subscriptions:          mercury-developers-request at cs.mu.oz.au
--------------------------------------------------------------------------