The ML Kit README file                             September 20, 2001

        ML Kit home page: http://www.it.edu/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 de-allocation
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 is available, one that generates efficient native code
for the x86 architecture and one that generates portable bytecode that
can 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 is distributed under the GNU Public License. See the file
copyright for details.

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 is 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/RuntimeWithGC/ 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.

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
