[m-dev.] for review: add compiler/notes/overall_design.html
Fergus Henderson
fjh at cs.mu.OZ.AU
Thu Aug 17 18:58:54 AEST 2000
Estimated hours taken: 2
Add some more documentation to compiler/notes.
compiler/notes/overall_design.html:
New file. Contains a list of the major sub-systems
in the compiler, and a description of how we handle
some of the dependency issues that arise.
compiler/notes/compiler_design.html:
Add a link to overall_design.html.
----------
It's probably easier to review the lynx output rather than
the TexInfo source, so I've included that first. But the
full diff is also encluded below.
|
| _________________________________________________________________
|
| This file contains some information about the design of the whole
| Mercury implementation, in particular listing the different major
| sub-systems and how we manage dependencies between different
| sub-systems.
|
| See also [1]compiler_design.html for information on the design of the
| compiler sub-system.
| _________________________________________________________________
|
| Sub-systems and sub-directories
|
| The Mercury implementation is divided into a number of major
| sub-systems. Each major sub-system is put in a different
| sub-directory.
|
| In general each sub-system 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 sub-system in two languages
| (as is the case for the Mercury debugger) then we generally divide
| that conceptual sub-system into different sub-directories for each
| language.
|
| The sub-directories containing major sub-systems are as follows:
| * boehm_gc: the Boehm (et al.) conservative garbage collector
| (written in C)
| * runtime: the Mercury runtime system (written in C)
| * library: the Mercury standard library (written in Mercury)
| * compiler: the Mercury compiler (written in Mercury)
| * trace: the part of the Mercury debugger that is written in C
| * browser: the part of the Mercury debugger that is written in
| Mercury
| * profiler: the Mercury profiler (written in Mercury)
| * extras: additional Mercury libraries. These are distributed
| separately from the main Mercury distribution.
|
| In addition, there are some extra sub-directories for scripts and
| utility programs:
| * scripts: shell scripts used by the Mercury implementation (mostly
| written in standard Bourne shell)
| * util: utility programs (written in C)
|
| These extra sub-directories provide the infrastructure and "glue code"
| that connects the major sub-systems. There's also some additional
| infrastructure (the autoconf configuration stuff and the primary
| Makefile and Mmakefile) in the top-level directory.
|
| As well as the sub-directories containing the major sub-systems and
| the glue code, there are also some sub-directories that just provide
| documentation:
| * doc: documentation for users (mostly written in TexInfo)
| * samples: example programs
|
| Finally there are some directories containing stuff that is for the
| developers of the Mercury implementation, rather than being part of
| the Mercury implementation:
| * tools: scripts that are useful in the development of the Mercury
| implementation, but which are not actually part of the end product
| * compiler/notes: documentation for developers of the Mercury
| implementation
| * tests: a big suite of test cases. These are distributed separately
| from the main Mercury distribution.
|
| Programs, shell scripts, and file names
|
| 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.
|
| 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'.
|
| Libraries and dependencies
|
| Each major sub-system (except `extras') gets compiled to a single
| library or executable program. 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. On IRIX, mutual recursion between shared libraries prevents the
| use of "QuickStart". And on Windows, allowing mutual recursion between
| different DLLs requires some fairly major contortions. 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. The Mercury linker links the different components
| that make up a program in the following order:
| * the object of the auto-generated init file (generated by
| util/mkinit.c)
| * the main program object files (e.g. compiler/*.o or profiler/*.o)
| * trace library (trace/libmer_trace.a)
| * browser library (browser/libmer_browser.a)
| * standard library (library/libmer_std.a)
| * runtime library (runtime/libmer_rt.a)
| * Boehm collector (boehm_gc/libgc.a)
|
| 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.
| _________________________________________________________________
|
| Last update was $Date: 2000/06/01 08:48:26 $ by $Author: fjh
| $@cs.mu.oz.au.
|
| References
|
| 1. file://localhost/home/hg/fjh/mercury/compiler/notes/compiler_design.html
Workspace: /home/pgrad/fjh/ws/hg
Index: compiler/notes/compiler_design.html
===================================================================
RCS file: /home/mercury1/repository/mercury/compiler/notes/compiler_design.html,v
retrieving revision 1.48
diff -u -d -r1.48 compiler_design.html
--- compiler/notes/compiler_design.html 2000/06/01 08:48:26 1.48
+++ compiler/notes/compiler_design.html 2000/08/17 08:47:01
@@ -12,6 +12,10 @@
This file contains an overview of the design of the compiler.
+See also <a href="overall_design.html">overall_design.html</a>
+for an overview of how the different sub-systems (compiler,
+library, runtime, etc.) fit together.
+
<hr>
<!---------------------------------------------------------------------------->
Index: compiler/notes/overall_design.html
===================================================================
RCS file: overall_design.html
diff -N overall_design.html
--- /dev/null Thu Mar 30 14:06:13 2000
+++ overall_design.html Thu Aug 17 18:50:35 2000
@@ -0,0 +1,165 @@
+<html>
+<head>
+<title>
+ Notes On The Design Of The Mercury Implementation
+</title>
+</head>
+
+<body bgcolor="#ffffff" text="#000000">
+
+<hr>
+<!---------------------------------------------------------------------------->
+
+This file contains some information about the design of the whole Mercury
+implementation, in particular listing the different major sub-systems
+and how we manage dependencies between different sub-systems.
+
+<p>
+
+See also <a href="compiler_design.html">compiler_design.html</a>
+for information on the design of the compiler sub-system.
+
+<hr>
+<!---------------------------------------------------------------------------->
+
+<h2> Sub-systems and sub-directories </h2>
+
+<p>
+
+The Mercury implementation is divided into a number of major sub-systems.
+Each major sub-system is put in a different sub-directory.
+
+<p>
+
+In general each sub-system 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 sub-system in two
+languages (as is the case for the Mercury debugger) then we generally
+divide that conceptual sub-system into different sub-directories for
+each language.
+
+<p>
+
+The sub-directories containing major sub-systems 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> profiler: the Mercury profiler (written in Mercury)
+<li> extras: additional Mercury libraries. These are distributed
+ separately from the main Mercury distribution.
+</ul>
+
+In addition, there are some extra sub-directories for
+scripts and utility programs:
+
+<ul>
+<li> scripts: shell scripts used by the Mercury implementation
+ (mostly written in standard Bourne shell)
+<li> util: utility programs (written in C)
+</ul>
+
+These extra sub-directories provide the infrastructure and "glue code"
+that connects the major sub-systems. There's also some additional
+infrastructure (the autoconf configuration stuff and the primary
+Makefile and Mmakefile) in the top-level directory.
+
+<p>
+
+As well as the sub-directories containing the major sub-systems and the
+glue code, there are also some sub-directories 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. These are distributed
+ separately from the main Mercury distribution.
+</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 sub-system (except `extras') gets compiled to a single
+library or executable program.
+
+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. On IRIX, mutual
+recursion between shared libraries prevents the use of "QuickStart".
+And on Windows, allowing mutual recursion between different DLLs
+requires some fairly major contortions.
+
+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.
+
+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> browser library (browser/libmer_browser.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.
+
+<hr>
+<!---------------------------------------------------------------------------->
+
+Last update was $Date: 2000/06/01 08:48:26 $ by $Author: fjh $@cs.mu.oz.au. <br>
+</body>
+</html>
--
Fergus Henderson <fjh at cs.mu.oz.au> | "I have always known that the pursuit
WWW: <http://www.cs.mu.oz.au/~fjh> | of excellence is a lethal habit"
PGP: finger fjh at 128.250.37.3 | -- the last words of T. S. Garp.
--------------------------------------------------------------------------
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