[m-dev.] for review: developer introduction for webpage
Tyson Dowd
trd at cs.mu.OZ.AU
Tue Jan 16 16:16:40 AEDT 2001
Hi,
My action item from the last meeting...
===================================================================
Estimated hours taken: 2.5
information/developers/developer_intro.html:
information/include/developer.inc:
Write an introduction to developers to tell them about
Mmake.params, mmake install, tools/lmc and tools/bootcheck.
Index: information/developers/developer_intro.html
===================================================================
RCS file: developer_intro.html
diff -N developer_intro.html
--- /dev/null Tue Nov 21 11:53:28 2000
+++ developer_intro.html Tue Jan 16 16:13:34 2001
@@ -0,0 +1,179 @@
+<html>
+<head>
+
+<title>The Mercury Project: Developer Introduction </title>
+</head>
+<body bgcolor="#ABCDEF" text="#000000">
+
+<h2>An introduction to the Mercury source code and tools</h2>
+
+Author: Tyson Dowd -- trd at cs.mu.oz.au
+<p>
+
+The source code to Mercury is freely available and may be modified by
+anyone. However, there's a bit of a difference between being legally
+allowed to modify the code, and actually being able to do it! The
+Mercury system is quite large, and as the compiler for Mercury is
+written in Mercury itself, there are a few tricks worth learning if you
+are going to develop with Mercury.
+<p>
+This document aims to help developers get started with the Mercury
+development environment, by explaining some of the special tools that
+are available for developers.
+<p>
+Other useful documents are in the
+<a href="../developer.html">Developers Information</a> section
+of the web site. In particular you may wish to see how to access the
+Mercury CVS repository and read about the design of the Mercury compiler.
+<p>
+This document is a work-in-progress, if there is particular information
+you feels is useful, please let me know and I will write something about
+it.
+
+<h2>About grades</h2>
+
+The Mercury system uses the word "grade" to refer to a set of
+compilation options for the system. Some of them are for benchmarking
+purposes, others enable debugging or profiling, and others enable
+research features. Many grades are incompatible with each other.
+<p>
+Mixing and matching grades can be the cause of headaches. It's a good
+idea to `mmake realclean' build from scratch if you run into weird
+problems and have been changing grades. The Mercury system makes a
+pretty good attempt to try to stop this kind of thing resulting in a
+crashing program, but you will often get linker errors if you try to
+build different parts of the compiler in incompatible grades.
+
+<h2>Setting the installation path</h2>
+
+If you want to install your own compiler, you will probably want to keep
+it separate from a working stable compiler (or else you might make a mistake
+that makes it impossible to compile the compiler anymore!).
+<p>
+When you run configure, you can set an installation path. For example:
+<pre>
+./configure --prefix /tmp/mercury/install
+</pre>
+will set the installation path to /tmp/mercury/install. Make sure you
+set your PATH so that it includes the `bin' subdirectory of your install
+path -- in this example it would be /tmp/mercury/install/bin. And be
+sure that this is earlier in your path than any other Mercury
+installation (for example, one in /usr/bin or /usr/local/bin).
+
+<h2>Installing fewer grades</h2>
+
+If you make a lot of changes to the compiler, you will find it a bit time
+consuming to install the entire Mercury system to run a few tests.
+<p>
+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 can also set this variable on a once off basis on the command line.
+<pre>
+mmake install LIBGRADES=
+</pre>
+<p>
+
+<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>
+
+<h2>Using the local build directory</h2>
+
+If you only need to run your version of mmc (and don't need mmake), you
+don't need to install at all. There is a script in the tools directory
+of the Mercury distribution called `lmc'. You can use this script just
+like mmc, but it will use the Mercury compiler, library, runtime, etc that
+you have in an uninstalled workspace.
+<p>
+You need to set the environment variable WORKSPACE to point to the
+workspace you are using. The easiest way to do this is to create a
+small script which sets WORKSPACE and runs lmc.
+For example if you are using $HOME/mercury as your workspace:
+<pre>
+#!/bin/sh
+WORKSPACE=$HOME/mercury
+export WORKSPACE
+$WORKSPACE/tools/lmc "$@"
+</pre>
+See the tools/lmc file for further documentation on this tool -- it can
+also run the compiler under gdb or compile programs suitable for C level
+debugging.
+
+<h2>Bootchecking</h2>
+
+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.
+<p>
+The bootcheck script in the tools directory of the Mercury compiler
+is just what you need to do this. It works in a number of
+<em>stages</em>, where each stage is the output of the compiler we built
+in the previous stage.
+<p>
+Stage 1 is to build a working Mercury compiler (just like typing mmake
+at the top level of the mercury distribution). We build this compiler
+using a known, trusted, stable Mercury compiler.
+<p>
+Stage 2 uses the stage 1 Mercury compiler to build a stage 2 Mercury
+compiler. This ensures that you can still build the compiler using your
+modifications.
+<p>
+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.
+<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.
+<p>
+Check out the tools/bootcheck script to see further documentation on how
+it works. You can build only specific stages, just run the tests, omit
+building certain parts of the compiler, and much much more.
+<p>
+Bootchecking can take quite a while -- 1-3 hours is not uncommon. It's
+a good idea to run the bootcheck in the background and log the results
+to a file. For example:
+<pre>
+./tools/bootcheck > bootchecklog.Jan21 2>&1 &
+tail -f bootchecklog.Jan21
+</pre>
+
+<p>
+<hr>
+<p>
+or see our <a href = "../email.html" >contact</a> page.<br>
+
+Last update was $Date: 2000/08/22 09:41:55 $ by $Author: petdr $@cs.mu.oz.au
+</body>
+</html>
+
Index: information/include/developer.inc
===================================================================
RCS file: /home/mercury1/repository/w3/information/include/developer.inc,v
retrieving revision 1.5
diff -u -r1.5 developer.inc
--- information/include/developer.inc 2000/08/09 07:46:52 1.5
+++ information/include/developer.inc 2001/01/15 05:18:17
@@ -9,6 +9,14 @@
-------->
<p>
<ul>
+<li> <strong>Developer Introduction</strong> <br>
+ Tips and tricks for developers just starting to work with
+ the Mercury source code.<p>
+
+ Available in
+ <a href="developers/developer_intro.html">HTML</a>
+ <p>
+
<li> <strong>Remote CVS Access</strong> <br>
How to access the CVS repository from your machine.<p>
--
Tyson Dowd #
# Surreal humour isn't everyone's cup of fur.
trd at cs.mu.oz.au #
http://www.cs.mu.oz.au/~trd #
--------------------------------------------------------------------------
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
--------------------------------------------------------------------------
More information about the developers
mailing list