The New Jersey Machine-Code Toolkit --- Source for ML Version
This ML implementation of the New Jersey
Machine-Code Toolkit is distributed ``as is,'' for experimental
purposes only.
If you can figure out how to make it do useful things, we're both
surprised.
The toolkit is written in a combination of Icon and Standard ML.
(Actually, the toolkit does not run any Icon code, but Icon is used to
generate some of the ML code that makes up the toolkit.)
To make things even more interesting, the source code is written in
noweb.
Finally, the toolkit uses special
Standard ML
of New Jersey features, especially the Compilation Manager.
Preliminaries
First, get and install the software tools you will need.
- Get and install Icon from the
Icon Project (FAQ
here) at the
University of Arizona.
You can get binaries for
386 DOS,
Linux,
SPARC SunOS,
SPARC Solaris,
32-bit Windows,
and other targets.
- Get and install the
noweb
literate-programming tool.
- Get and install
Standard ML
of New Jersey, version 110 or later.
Avoid the ``experimental'' versions; use something matching 110.0.*.
Naturally, you will need the binaries for these things on your
execution path.
The final preliminary is to download the Toolkit
source package.
Building the tools and the toolkit
Untar the toolkit source package, which will create an mltk
directory.
Edit the shell script
mltk/install, setting the variables in the script according to the
comments.
Then run cd mltk; ./install, which should
- Compile and install the tools needed to build the toolkit.
- Build sml-nw, a version of Standard ML of New Jersey that
understands how to use these tools build the toolkit.
If an error occurs during this step, see below.
- Compile the toolkit itself.
You can then change to the mltk/src directory and use the toolkit.
You have to start sml-nw and tell it CM.make();
to get access to the innards. You'll have to read the ML code to see
what's there. Most of the useful stuff is in the main.nw
module.
Potential errors building sml-nw
An error may occur when building sml-nw, because not all
SML/NJ versions beyond 110 treat CM tools in the same way.
If you are using an older version like 110.0.3, you will have to
change tools/export.sml to conform.
As distributed, the file contains the following binding:
val runlex =
Tools.stdShellProcessor
( { command = command, tool = "ML-Lex+" } (* old style *)
; { mkCommand = fn () => command, tool = "ML-Lex+" } (* new style *)
)
If the compiler complains, you can simply remove the line marked `new style'.
Another potential error may occur because of other version
incompatibilities; you may have to remove line 3 from
tools/export.sml:
val _ = Compiler.Control.MC.bindContainsVar := false;
Using the ML version
The ML version of the toolkit can be used reliably to generate
decoders, and it has some optimizations that are not in the Icon
version.
For generating encoding procedures, this version should be considered
wildly experimental; it is missing some crucial pieces, and it has
some untried and untested code.
Regrettably, I have not had time to develop a command-line
interface or a manual, even for the decoding stuff.
Your best bet is to study the two modules in the source file
usercode.nw, which can be used to generate matchers.
- The templates represent the user's choice of how to fetch
values, how to do address arithmetic, etc.
(They correspond to the templates in the Icon version, which are
documented in the manual.)
- The [[matcher]] is a curried version of the decoder builder.
It is curried so that you can suck in a bunch of specifications once,
then use those specifications to generate many different decoders (or
different versions of the same decoder).
For example,
val mike = CC.matcher ["../cc/mike/pentium.spec", "../cc/mike/penwait.spec"];
reads these specs and turns mike into a match compiler.
Then
mike "../cc/mike/dis.m";
runs the match compiler and writes the results on ../cc/mike/dis.m.d.
Correspondence
Send all correspondence to
toolkit@eecs.harvard.edu.