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.