The ML Kit README file

        ML Kit home page: http://www.itu.dk/research/mlkit/

0. Introduction
---------------
The ML Kit (henceforth refered to as the Kit) is a compiler for the
programming language Standard ML. The Kit covers all of Standard ML,
as defined in the 1997 edition of the Definition of Standard ML and
supports most of the Standard ML Basis Library. The Kit uses a region
based memory management scheme in which allocation and deallocation
primitives are added to the program at compile time. The Kit also
makes it possible to combine the region based memory management scheme
with traditional reference tracing garbage collection. Two versions of
the ML Kit are available, one that generates efficient native code for
the x86 architecture and one that generates portable bytecode to be
interpreted by an abstract machine. The largest program compiled with
the Kit is the Kit itself (around 80.000 lines of SML, plus the Basis
Library).

Features:

  * Region based memory management in combination with reference
    tracing garbage collection.
 
  * All of Standard ML. The Kit compiles all of Standard ML, including
    Modules, as specified by the Definition of Standard ML. The Kit
    also supports large parts of the Standard ML Basis Library.

  * Native backend for the x86 architecture and a bytecode backend 
    for creating portable code.

  * Compilation of large programs. The largest program the Kit
    has compiled is the Kit itself, which is approximately 80,000
    lines of code.

  * Documentation. A comprehensive guide on programming with regions
    in the ML Kit is available in the doc/ directory.

1. Release Numbers
------------------
The Kit follows the convention that releases with odd minor release
numbers (e.g., 3.1.12) are experimental releases whereas releases with
even minor release numbers (e.g., 3.0.1) are stable releases. The
convention only applies to the minor number. If x.y.z is a release
number, y is called the minor release number.

2. License and Copyright
------------------------

The ML Kit compiler is distributed under the GNU Public License. See
the file copyright for details. The runtime system (kit/src/Runtime/)
and libraries (kit/basislib/) is distributed nder the more liberal
MIT License.

3. Installation
---------------
See the INSTALL file in the source distribution.

4. Try It
---------
Assuming the ML Kit is already installed on your system, this
directory contains binaries and documentation for compiling and
running Standard ML programs with the ML Kit. Copy the kitdemo/
directory to your home directory and try compile the helloworld.sml
program:

  % cp -R /usr/share/mlkit/kitdemo ~/kitdemo
  % cd ~/kitdemo
  % mlkit helloworld.sml

The ML Kit should produce an executable file "run":  

  % ./run
  hello world

Documentation for the ML Kit is located in the `doc' directory.

5. Support for Other Platforms and How You Can Help
---------------------------------------------------
Currently, only the Linux/x86 platform and the FreeBSD/x86 platform
(see below) are supported. We hope to port the bytecode interpreter to
run on other platforms as well. If you want to help port the runtime
system to other platforms, please let us know; the runtime system and
bytecode interpreter is written in C (see the src/Runtime/ directory
in the source distribution.)

For the native x86 backend, the Kit calls the gcc compiler to assemble
and link the x86 code files it generates. The native backend for the
HP PA-RISC architecture is no longer supported. We do not plan to
support other native backends than the x86 backend. Suggestions for
improving the x86 assembler code generated by the x86 native backend
(e.g., by peep-hole optimization) are very much welcomed; the flag
--delete_target_files can be used to disable the deletion of the
.s-files generated by the backend.

To use the ML Kit for the FreeBSD/x86 platform, please alter the files

  kit/Makefile
  kit/src/Makefile
  kit/src/Common/SMLofNJOnKit.sml
  kit/src/heap2exec/Makefile

to suit your needs before you proceed with the installation
instructions in the INSTALL file. The port to the FreeBSD/x86 platform
is due to Koshy A Joseph.

6. VCG
------
The VCG tool, which is used to show region flow graphs, can be found at

    http://www.cs.uni-sb.de/RW/users/sander/html/gsvcg1.html

7. Comments and Bug Reports
---------------------------
Please see the www site:

   http://www.it.edu/research/mlkit/

8. Known Bugs and Limitations
------------------------------
Arithmetic and Trigonomitric functions in Math module:
  The implementation uses the C functions specified in math.h.
  Unfortunately, these C functions are platform dependent and 
  do not always return NaN precisely when the Basis
  Library stipulates that they should.

Polymorphic equality:
  Polymorphic equality is implemented only for "regular" data
  types. A datatype binding
 
     tyvarseq_1 tycon_1 = conbind_1 AND ... AND tvseq_n tycon_n = conbind_n

  is {\em regular\/} iff all occurrences of tycon_i, i \in {1,...,n}
  in {conbind_1, ..., conbind_n} are in the context 

     tyvarseq_i tycon_i

-------
Have fun!

The ML Kit Development Team