<html><head><title>NJ Machine-Code Toolkit Source Distribution v0.5a</title></head><body>
<h1>The New Jersey Machine-Code Toolkit --- Source Distribution</h1>
This file acts as a README file for the <a href=index.html>New Jersey
Machine-Code Toolkit</a>.
It tells you what you need to <a href=ftp><tt>ftp</tt></a> and
<a href=building>what to do</a> with the
results. If you just want to grab everything and not think,
get <a href=v0.5a.tar.gz>the master compressed tar file</a>.
<p>
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
<a href=http://www.cs.arizona.edu/icon/>Icon Project</a> (FAQ
<a href=http://www.cs.arizona.edu/icon/faq.htm>here</a>;) at the
<a href=http://www.cs.arizona.edu>University of Arizona</a>.
You can get binaries for
<a href=ftp://ftp.cs.arizona.edu/icon/binaries/msdos-386>386 DOS</a>,
<a href=ftp://ftp.cs.arizona.edu/icon/binaries/unix/linux-icon.tar.gz>Linux</a>,
<a href=ftp://ftp.cs.arizona.edu/icon/binaries/unix/sunos-icon.tar.gz>SPARC SunOS</a>,
<a href=http://sunsite.unc.edu/pub/packages/solaris/sparc/icon.9.3.SPARC.Solaris.2.5.pkg.tgz>SPARC Solaris</a>,
<a href=ftp://ringer.cs.utsa.edu/pub/icon/nt/console/>32-bit Windows</a>,
and <a href=ftp://ftp.cs.arizona.edu/icon/binaries>other</a> targets.
<h2><a name=ftp>What's available</a></h2>
<h3>Toolkit sources</h3>
The <a href=base>base</a> directory contains the minimum you need to
use the toolkit: source code and <a href=base/refman.ps>reference
manual</a>.
If you prefer, you can get a <a href=base.tar.gz>compressed tar file</a>.
<p>
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 <code>#line</code> directives.
The advantage of using the base sources, though, is that you never
have to tinker with <tt>mk</tt> and
<tt><A href=http://www.eecs.harvard.edu/~nr/noweb/intro.html>noweb</a></tt>;.
You don't even have to know what they are.
<p>
You don't have to venture into the sources to use the toolkit, but if you wish to,
you can look in <a href=src>src</a> directory, which is also available
in <a href=src.tar.gz>compressed tar</a> form.
That directory contains all the
<tt><A href=http://www.eecs.harvard.edu/~nr/noweb/intro.html>noweb</a></tt>; sources, a
<tt>mkfile</tt>, and a <a href=src/source.ps>large PostScript
document</a> containing source code with explanation.
It might be easier to browse the <a href=htmlsrc>sources rendered as HTML</a>.
<h3>Sample specifications</h3>
We have written <a href=specs>annotated specifications</a> for the
<a href=specs/mips.nw>MIPS R3000</a>,
<a href=specs/sparc.nw>SPARC</a>,
<a href=specs/alpha.nw>Alpha</a>,
and
<a href=specs/pentium.nw>Intel Pentium</a>
architectures.
We also have <a href=specs/ppc.nw>Doug Currie's PowerPC specification</a>.
If you just want to use these specifications, they can be found in the
<a href=base-specs>base-specs directory</a> or
<a href=base-specs.tar.gz>compressed tar file</a>).
If you want to study them, the literate source code is in the
<a href=specs>specs</a> directory, along with another
<a href=specs/specs.ps>large PostScript document</a> that shows them
with annotations.
All the specification goo is available in a single
<a href=specs.tar.gz>compressed tar file</a>.
<h3>Sample applications</h3>
We have had many requests for sample applications that help show
people how to use the toolkit.
We have a <a href=examples/xs/xs.html>work in progress</a> 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.
<p>
We also have a simple but useful
<a href=examples/sparc/index.html>disassembler for the SPARC</A>.
<p>
The examples are available in a <a href=examples.tar.gz>compressed tar file</a>.
<h3>Sample checkers</h3>
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 <a href=base-checker>base-checker directory</a>, also in a
<a href=base-checker.tar.gz>compressed tar file</a>,
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.
<h2><a name=building>Building the toolkit</a></h2>
We only provide instructions for building the toolkit from the base sources provided in the <a href=base>base</a> directory. If you want to build it from the literate sources, use <tt>mk</tt>.
<blockquote><em>The toolkit needs a patch for the current versions of gcc. Use <a href=patch/mclib.c><tt>patch/mclib.c</tt></a>, <a href=patch/mclib.h><tt>patch/mclib.h</tt></a>, and <a href=patch/mclib.nw><tt>patch/mclib.nw</tt></a> instead of the versions in the distribution</em></blockquote>
<p>
If you don't already have Icon installed (version 8.10 or later),
you'll need to do that first.
Then
<ol>
<li>build the generator/translator:
<pre>
icont tools
</pre>
<li>Building the toolkit library requires an ANSI C compiler.
We usually use gcc.
<pre>
gcc -c -I. mclib.c
</pre>
<li><ol>
<li>Install the <tt>tools</tt> binary somewhere on your PATH.
<li>Put the library header <tt>mclib.h</tt> where your C compiler
can find it.
<li>Put the library object code <tt>mclib.o</tt> where your linker
can find it.
</ol>
</ol>
Now you're set to build your applications.
<h2>Correspondence</a></h2>
Send all correspondence to
<a href=mailto:toolkit@cs.princeton.edu>toolkit@cs.princeton.edu</a>.
</body></html>