mirror of
https://github.com/Mercury-Language/mercury.git
synced 2025-12-16 22:35:41 +00:00
0607c27543
The non-style changes include
- Replacing outdated information with up to date information.
- Deleting fully obsolete information, such as references to the IL backend.
- Replacing list entries that were just bare words or phrases
with full sentences, where this is useful.
- Improvements to make documents easier to read and understand.
However, the bulk of the diff consists of style changes. The initial main
of these changes are to eliminate, or at least reduce, inconsistencies
- between the styles of the different parts of each document, and
- between the styles of differents documents.
This applies both as they appear in a browser, and in the source .html file.
The main style changes are
- Add a vim mode line to each file.
- Do not specify a color for the page background; let the browser decide.
- Add a heading to the top of each page that echoes the title.
- Avoid SHOUTING in headings.
- Avoid the unneeded use of <hr>.
- Avoid the use of headings (e.g. h5) that are so low in the hierarchy that
browsers render them in a font that is *smaller* than the usual font.
- Replace definition lists with standard unordered lists
when the list items are not definitions.
- Replace ordered lists with standard unordered lists
when the list items have no meaningful order.
- Do not indent the contents of unordered lists, with the exception of
nested lists.
- Unless all entries in a list are extremely short,
do not try to put anything next to <li>.
- Fix violations reported by weblint.
compiler/notes/compiler_design.html:
The changes described above.
Explicitly introduce the notion of the middle end.
compiler/notes/bootstrapping.html:
Rewrite this almost from scratch.
compiler/notes/work_in_progress.html:
Rename the page to make it clear that these issues are NOT being
worked on.
compiler/notes/release_checklist.html:
compiler/notes/todo.html:
Note that these lists are quite out of date.
compiler/notes/allocation.html:
compiler/notes/analysis.html:
compiler/notes/bytecode.html:
compiler/notes/c_coding_standard.html:
compiler/notes/coding_standards.html:
compiler/notes/developer_intro.html:
compiler/notes/failure.html:
compiler/notes/gc_and_c_code.html:
compiler/notes/glossary.html:
compiler/notes/grade_library.html:
compiler/notes/index.html:
compiler/notes/interface_files.html:
compiler/notes/mlds_tail_recursion.html:
compiler/notes/overall_design.html:
compiler/notes/promise_ex.html:
compiler/notes/reviews.html:
compiler/notes/trailing.html:
compiler/notes/type_class_transformation.html:
compiler/notes/upgrade_boehm_gc.html:
compiler/notes/Mmakefile:
Add a target to run weblint on all the HTML files.
177 lines
5.9 KiB
HTML
177 lines
5.9 KiB
HTML
<!--
|
|
vim: ts=4 sw=4 expandtab ft=html
|
|
-->
|
|
|
|
<html>
|
|
<head>
|
|
<title>Notes On The Design Of The Mercury Implementation</title>
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<h1>Notes On The Design Of The Mercury Implementation</h1>
|
|
|
|
This file contains some information
|
|
about the design of the whole Mercury implementation,
|
|
in particular listing the different major subsystems
|
|
and how we manage dependencies between different subsystems.
|
|
<p>
|
|
See also <a href="compiler_design.html">compiler_design.html</a>
|
|
for information on the design of the compiler subsystem.
|
|
|
|
<h2>Subsystems and subdirectories</h2>
|
|
|
|
<p>
|
|
The Mercury implementation is divided into several major subsystems.
|
|
Each major subsystem is put in a different subdirectory.
|
|
<p>
|
|
In general, each subsystem is written in a single language;
|
|
we prefer not to mix different languages in a single directory,
|
|
and so if we plan to implement what is conceptually a single subsystem
|
|
in two languages (as is the case for the Mercury debugger)
|
|
then we generally divide that conceptual subsystem
|
|
into different subdirectories for each language.
|
|
<p>
|
|
The subdirectories containing major subsystems are as follows:
|
|
|
|
<ul>
|
|
<li>
|
|
boehm_gc: the Boehm (et al.) conservative garbage collector (written in C)
|
|
<li>
|
|
runtime: the Mercury runtime system (written in C)
|
|
<li>
|
|
library: the Mercury standard library (written in Mercury)
|
|
<li>
|
|
compiler: the Mercury compiler (written in Mercury)
|
|
<li>
|
|
trace: the part of the Mercury debugger that is written in C
|
|
<li>
|
|
browser: the part of the Mercury debugger that is written in Mercury
|
|
<li>
|
|
mdbcomp: the library that defines the Mercury data structures
|
|
generated by the compiler for the debugger
|
|
<li>
|
|
ssdb: support code for the source-to-source debugger (written in Mercury)
|
|
<li>
|
|
slice: tools for manipulating slices and dices (written in Mercury)
|
|
<li>
|
|
profiler: the Mercury profiler (written in Mercury)
|
|
<li>
|
|
deep_profiler: the Mercury deep profiler (written in Mercury)
|
|
<li>
|
|
analysis: an inter-module analysis framework
|
|
(written in Mercury; code moved to compiler)
|
|
<li>
|
|
extras: additional Mercury libraries.
|
|
</ul>
|
|
|
|
In addition, there are some extra subdirectories
|
|
for scripts and utility programs:
|
|
|
|
<ul>
|
|
<li>
|
|
scripts: shell scripts used by the Mercury implementation
|
|
(mostly written in standard Bourne shell,
|
|
but some on other scripting languages)
|
|
<li>
|
|
util: utility programs (written in C)
|
|
</ul>
|
|
|
|
These extra subdirectories provide the infrastructure and "glue code"
|
|
that connects the major subsystems.
|
|
There is also some additional infrastructure
|
|
(the autoconf configuration stuff and the primary Makefile and Mmakefile)
|
|
in the top-level directory.
|
|
<p>
|
|
As well as the subdirectories
|
|
containing the major subsystems and the glue code,
|
|
there are also some subdirectories that just provide documentation:
|
|
|
|
<ul>
|
|
<li>
|
|
doc: documentation for users (mostly written in TexInfo)
|
|
<li>
|
|
samples: example programs
|
|
</ul>
|
|
|
|
<p>
|
|
Finally there are some directories containing stuff
|
|
that is for the developers of the Mercury implementation,
|
|
rather than being part of the Mercury implementation:
|
|
|
|
<ul>
|
|
<li>
|
|
tools: scripts that are useful
|
|
in the development of the Mercury implementation,
|
|
but which are not actually part of the end product
|
|
<li>
|
|
compiler/notes: documentation for developers of the Mercury implementation
|
|
<li>
|
|
tests: a big suite of test cases.
|
|
</ul>
|
|
|
|
<h2>Programs, shell scripts, and file names</h2>
|
|
|
|
Often executable programs in the Mercury implementation
|
|
will need to access files provided by the Mercury implementation.
|
|
However, we want to avoid hard-coding path names in the executables,
|
|
and Unix does not provide any reasonable way for a program to determine
|
|
what directory the executable file is in.
|
|
<p>
|
|
To solve this problem,
|
|
executable programs which need to know path names are never invoked directly.
|
|
Instead, we always write a small shell script
|
|
that acts as a front-end for the executable program
|
|
(e.g. scripts/mmc is the front-end for compiler/mercury_compile).
|
|
The hard-coded path names get put in the shell script,
|
|
which passes them on to the program as parameters or environment variables.
|
|
The shell script is itself automatically generated from a template
|
|
(e.g. scripts/mmc.in) that contains symbolic names of the form @foo@;
|
|
the top-level `configure' script fills in the values for these
|
|
based on the user-specified parameters to the configure script.
|
|
The configure script is itself generated by `autoconf' from `configure.in'.
|
|
|
|
<h2>Libraries and dependencies</h2>
|
|
|
|
Each major subsystem (which doesn't include `extras')
|
|
gets compiled to a single library or executable program.
|
|
<p>
|
|
On most systems, mutual recursion between libraries is not very well supported.
|
|
On Unix, for static linking
|
|
you need to list the libraries more than once on the command line.
|
|
And on Windows, allowing mutual recursion between different DLLs
|
|
requires some fairly major contortions.
|
|
<p>
|
|
To avoid such difficulties,
|
|
and for the sake of portability to future systems
|
|
which may impose similar requirements,
|
|
it is a design principle of the Mercury implementation
|
|
that there should be no mutual recursion between libraries.
|
|
<p>
|
|
The Mercury linker links the different components that make up a program
|
|
in the following order:
|
|
|
|
<ul>
|
|
<li> the object of the auto-generated init file (generated by util/mkinit.c)
|
|
<li> the main program object files (e.g. compiler/*.o or profiler/*.o)
|
|
<li> trace library (trace/libmer_trace.a)
|
|
<li> ssdb library (ssdb/libmer_ssdb.a)
|
|
<li> browser library (browser/libmer_browser.a)
|
|
<li> mdbcomp library (mdbcomp/libmer_mdbcomp.a)
|
|
<li> standard library (library/libmer_std.a)
|
|
<li> runtime library (runtime/libmer_rt.a)
|
|
<li> Boehm collector (boehm_gc/libgc.a)
|
|
</ul>
|
|
|
|
To avoid circularities,
|
|
libraries cannot contain direct calls to any routines
|
|
that are defined in libraries (or object files)
|
|
that occur earlier in the above list.
|
|
Any such calls must be made into indirect calls via function pointers.
|
|
These function pointers can be initialized by the auto-generated init file,
|
|
which, since it is at the start of the list,
|
|
can refer to functions in any of the other components.
|
|
|
|
</body>
|
|
</html>
|