The New Jersey Machine-Code Toolkit --- Source Distribution

This file acts as a README file for the New Jersey Machine-Code Toolkit. It tells you what you need to ftp and what to do with the results. If you just want to grab everything and not think, get the master compressed tar file.

The toolkit is written in a combination of Icon and C. To use the toolkit, you will need a C compiler, and you will need to get Icon from the Icon Project (FAQ here) at the University of Arizona. You can get binaries for the 386 DOS, Linux, SPARC SunOS, and other targets.

What's available

Toolkit sources

The base directory contains the minimum you need to use the toolkit: source code and reference manual. If you prefer, you can get a compressed tar file.

The base sources aren't very readable, because the actual sources are written as a literate program. The base sources don't contain any comments, and they're full of ugly #line directives. The advantage of using the base sources, though, is that you never have to tinker with mk and noweb. You don't even have to know what they are.

You don't have to venture into the sources to use the toolkit, but if you wish to, you can look in src directory, which is also available in compressed tar form. That directory contains all the noweb sources, a mkfile, and a large PostScript document containing source code with explanation. It might be easier to browse the sources rendered as HTML.

Sample specifications

We have written annotated specifications for the MIPS R3000, SPARC, Alpha, and Intel Pentium architectures. We also have Doug Currie's PowerPC specification. If you just want to use these specifications, they can be found in the base-specs directory or compressed tar file). If you want to study them, the literate source code is in the specs directory, along with another large PostScript document that shows them with annotations. All the specification goo is available in a single compressed tar file.

Sample applications

We have had many requests for sample applications that help show people how to use the toolkit. We have a work in progress that may one day help people see how to build assemblers, disassemblers, linkers, and interpreters. It is unfinished, but we provide it in the hope that it may prove useful.

We also have a simple but useful disassembler for the SPARC.

The examples are available in a compressed tar file.

Building the toolkit

We only provide instructions for building the toolkit from the base sources provided in the base directory. If you want to build it from the literate sources, use mk.

Sample checkers

The toolkit can validate a specification against an existing assembler. We have validated the MIPS and SPARC specifications and the 32-bit subset of the Pentium specification that are distributed with the toolkit. The base-checker directory, also in a compressed tar file, contains all the files necessary to build the checkers for those targets. Its makefile can be used as a roadmap for building checkers for other targets.

Building the toolkit

We only provide instructions for building the toolkit from the base sources provided in the base directory. If you want to build it from the literate sources, use mk.

If you don't already have Icon installed (version 8.10 or later), you'll need to do that first. Then

build the generator/translator:
```
  icont tools
  
```
Building the toolkit library requires an ANSI C compiler. We usually use gcc.
```
  gcc -c -I. mclib.c
  
```
1. Install the tools binary somewhere on your PATH.
2. Put the library header mclib.h where your C compiler can find it.
3. Put the library object code mclib.o where your linker can find it.

Now you're set to build your applications.

Correspondence

Send all correspondence to toolkit@cs.princeton.edu.