README.adoc

November 8, 2023 · View on GitHub

ifdef::env-github[] image:https://github.com/MLton/mlton/actions/workflows/ci.yml/badge.svg[CI, link = https://github.com/MLton/mlton/actions/workflows/ci.yml] endif::[]

MLton is a whole-program optimizing compiler for the Standard{nbsp}ML programming language. MLton generates small executables with excellent runtime performance, utilizing untagged and unboxed native integers, reals, and words, unboxed native arrays, fast arbitrary-precision arithmetic based on GMP, and multiple code generation and garbage collection strategies. In addition, MLton provides a feature rich Standard{nbsp}ML programming environment, with full support for SML97 as given in The Definition of Standard{nbsp}ML (Revised), a number of useful language extensions, a complete implementation of the Standard ML Basis Library, various useful libraries, a simple and fast C foreign function interface, the ML Basis system for programming with source libraries, and tools such as a lexer generator, a parser generator, and a profiler.

== Features

Robustness.
- Supports the full SML{nbsp}97 language as given in The Definition of Standard{nbsp}ML (Revised).
- A complete implementation of the http://sml-family.org/Basis/[Basis Library].
- Generates standalone executables.
- Compiles large programs.
- Support for large amounts of memory (up to 4G on 32-bit systems; more on 64-bit systems).
- Support for large array lengths (up to $2^{31}$ ^ - 1 on 32-bit systems; up to $2^{63}$ ^-1 on 64-bit systems).
- Support for large files, using 64-bit file positions.
Performance.
- Executables have excellent runtime performance.
- Generates small executables.
- Untagged and unboxed native integers, reals, and words.
- Unboxed native arrays.
- Multiple garbage collection strategies.
- Fast arbitrary-precision arithmetic based on https://gmplib.org[GMP].
Tools.
- Source-level http://mlton.org/Profiling[profiling] for both time and allocation.
- MLLex lexer generator.
- MLYacc parser generator.
- MLNLFFIGEN foreign-function-interface generator.
Extensions.
- The http://mlton.org/MLBasis[ML Basis system] for programming with source libraries.
- A number of useful http://mlton.org/SuccessorML[language extensions].
- A simple and fast http://mlton.org/ForeignFunctionInterface[C FFI] that supports calling from SML to C and from C to SML.
- Libraries for http://mlton.org/MLtonWeak[weak pointers] and http://mlton.org/MLtonFinalizable[finalization], http://mlton.org/MLtonThread[threads], http://mlton.org/MLtonCont[continuations], http://mlton.org/MLtonItimer[interval timers] and http://mlton.org/MLtonSignal[signal handlers], http://mlton.org/MLtonWorld[world save and restore], and http://mlton.org/MLtonStructure[more].
Portability.
- Runs on a wide variety of platforms.

== Build and Install (from source)

=== Requirements

==== Software

http://gcc.gnu.org/[GCC] or http://clang.llvm.org[Clang] (The C compiler must support -std=gnu11.)
http://gmplib.org[GMP] (GNU Multiple Precision arithmetic library)
http://savannah.gnu.org/projects/make[GNU Make]
http://www.gnu.org/software/bash/[GNU Bash]
binutils (ar, ranlib, strip, ...)
miscellaneous Unix utilities (diff, find, grep, gzip, patch, sed, tar, ...)
Standard{nbsp}ML compiler to bootstrap:
- http://mlton.org[MLton] (mlton) recommended. Pre-built binary packages for MLton can be installed via an OS package manager or (for select platforms) obtained from http://mlton.org.
- http://www.smlnj.org[SML/NJ] (sml) supported, but not recommended.
- https://polyml.org[Poly/ML] (polyc) supported, but not recommended.
- https://elsman.com/mlkit[MLKit] (mlkit) supported, but not recommended.
(optional, for documentation only) https://ctan.org/tex/[TeX], http://asciidoctor.org/[AsciiDoctor], http://rouge.jneen.net/[Rouge], http://www.graphicsmagick.org/[GraphicsMagick] or https://www.imagemagick.org/[ImageMagick], ...

==== Hardware

≥ 1GB RAM (for 32-bit platforms) or ≥ 2GB RAM (for 64-bit platforms)

=== Build Instructions

On typical platforms, building MLton requires no configuration and can be accomplished via:

[source,shell]

$ make all

A small set of Makefile variables can be used to customize the build:

CC: Specify C compiler. Can be used for alternative tools (e.g., CC=clang or CC=gcc-7).
WITH_GMP_DIR, WITH_GMP_INC_DIR, WITH_GMP_LIB_DIR: Specify GMP include and library paths, if not on default search paths. (If WITH_GMP_DIR is set, then WITH_GMP_INC_DIR defaults to $(WITH_GMP_DIR)/include and WITH_GMP_LIB_DIR defaults to $(WITH_GMP_DIR)/lib.)
MLTON_RUNTIME_ARGS, MLTON_COMPILE_ARGS: Specify runtime and compile arguments given to (the to-be-built) mlton when compiling distributed executables ((self-compiled) mlton, mllex, mlyacc, mlprof, and mlnlffigen). Can be used for testing (e.g., MLTON_COMPILE_ARGS="-codegen c") or for downstream packaging.
OLD_MLTON_RUNTIME_ARGS, OLD_MLTON_COMPILE_ARGS: Specify runtime and compile arguments given to "old" mlton when compiling "new" mlton. Can be used to work around bugs in "old" mlton when compiling "new" mlton.

For example:

[source,shell]

$ make CC=clang WITH_GMP_DIR=/opt/gmp MLTON_COMPILE_ARGS="-codegen c" all

The build artifacts are located under ./build. The just-built mlton can be executed via ./build/bin/mlton.

Building documentation can be accomplished via:

[source,shell]

$ make docs

=== Install Instructions

On typical platforms, installing MLton (after performing make all and, optionally, make docs) to /usr/local can be accomplished via:

[source,shell]

$ make install

A small set of Makefile variables can be used to customize the installation:

PREFIX: Specify the installation prefix.

For example:

[source,shell]

$ make PREFIX=/opt/mlton install

== Install (from binary package)

=== Requirements

==== Software

http://gcc.gnu.org/[GCC] or http://clang.llvm.org[Clang] (The C compiler must support -std=gnu11.)
http://gmplib.org[GMP] (GNU Multiple Precision arithmetic library)
http://savannah.gnu.org/projects/make[GNU Make]
miscellaneous Unix utilities (bzip2, gzip, sed, tar, ...)

=== Binary Package

A .tgz or .tbz binary package can be extracted at any location, yielding README.adoc (this file), CHANGELOG.adoc, LICENSE, Makefile, bin/, lib/, and share/. The compiler and tools can be executed in-place (e.g., ./bin/mlton).

A small set of Makefile variables can be used to customize the binary package via make update:

CC: Specify C compiler. Can be used for alternative tools (e.g., CC=clang or CC=gcc-7).
WITH_GMP_DIR, WITH_GMP_INC_DIR, WITH_GMP_LIB_DIR: Specify GMP include and library paths, if not on default search paths. (If WITH_GMP_DIR is set, then WITH_GMP_INC_DIR defaults to $(WITH_GMP_DIR)/include and WITH_GMP_LIB_DIR defaults to $(WITH_GMP_DIR)/lib.)

For example:

PREFIX: Specify the installation prefix.

For example:

[source,shell]

$ make PREFIX=/opt/mlton install

== Resources

http://mlton.org
Development
- https://github.com/MLton/mlton
- https://github.com/MLton/mlton/pulls[pull requests]
- https://github.com/MLton/mlton/issues[issue tracker]
Mailing lists
- MLton-devel@mlton.org -- MLton developers (https://sourceforge.net/mailarchive/forum.php?forum_name=mlton-devel[archive], https://lists.sourceforge.net/lists/listinfo/mlton-devel[subscribe])
- MLton-user@mlton.org -- MLton user community (https://sourceforge.net/mailarchive/forum.php?forum_name=mlton-user[archive], https://lists.sourceforge.net/lists/listinfo/mlton-user[subscribe])

== Support and Contributing

To report bugs or suggest new features, use the https://github.com/MLton/mlton/issues[issue tracker] or ask on the mailto:mlton-user@mlton.org[mailing list].

https://github.com/MLton/mlton/pulls[Pull requests] with bug fixes or changes are welcome.