README.adoc

   1 = http://mlton.org[MLton]
   2
   3 ifdef::env-github[]
   4 image:https://travis-ci.org/MLton/mlton.svg?branch=master[Build Status, link = https://travis-ci.org/MLton/mlton]
   5 endif::[]
   6
   7 ****
   8 MLton is a whole-program optimizing compiler for the Standard{nbsp}ML
   9 programming language.
  10 ****
  11
  12 == Features
  13
  14  * Portability. Runs on the following platforms:
  15
  16    - ARM: Linux (Debian).
  17    - Alpha: Linux (Debian).
  18    - AMD64: Darwin (Mac OS X), FreeBSD, Linux (Debian, Fedora, Ubuntu, ...),
  19      OpenBSD, Solaris (10 and above).
  20
  21    - HPPA: HPUX (11.11 and above), Linux (Debian).
  22    - IA64: HPUX (11.11 and above), Linux (Debian).
  23    - PowerPC: AIX (5.2 and above), Darwin (Mac OS X), Linux (Debian, Fedora).
  24    - PowerPC64: AIX (5.2 and above).
  25    - S390: Linux (Debian).
  26    - Sparc: Linux (Debian), Solaris (8 and above).
  27    - X86: Cygwin/Windows, Darwin (Mac OS X), FreeBSD, Linux (Debian, Fedora,
  28      Ubuntu, ...), MinGW/Windows, NetBSD, OpenBSD, Solaris (10 and above).
  29
  30  * Robustness.
  31
  32    - Supports the full SML 97 language as given in The Definition of
  33      Standard{nbsp}ML (Revised).
  34    - A complete implementation of the Basis Library.
  35    - Generates standalone executables.
  36    - Compiles large programs.
  37    - Support for large amounts of memory (up to 4G on 32-bit systems;
  38      more on 64-bit systems).
  39    - Support for large array lengths (up to 2^31^ - 1 on 32-bit systems;
  40      up to 2^63^-1 on 64-bit systems).
  41    - Support for large files, using 64-bit file positions.
  42
  43  * Performance.
  44
  45    - Executables have excellent running times.
  46    - Generates small executables.
  47    - Untagged and unboxed native integers, reals, and words.
  48    - Unboxed native arrays.
  49    - Multiple garbage collection strategies.
  50    - Fast arbitrary-precision arithmetic based on the GMP.
  51
  52  * Tools.
  53
  54    - Source-level profiling for both time and allocation.
  55    - MLLex lexer generator.
  56    - MLYacc parser generator.
  57    - MLNLFFIGEN foreign-function-interface generator.
  58
  59  * Extensions.
  60
  61    - A simple and fast C FFI that supports calling from SML to C and from C
  62      to SML.
  63    - The ML Basis system for programming in the very large.
  64    - Libraries for continuations, finalization, interval timers, random numbers,
  65      resource limits, resource usage, signal handlers, object size, system
  66      logging, threads, weak pointers, and world save and restore.
  67
  68
  69 == Build and Install (from source)
  70
  71 === Requirements
  72
  73 ==== Software
  74
  75  * http://gcc.gnu.org/[GCC] or http://clang.llvm.org[Clang] (The C compiler must support `-std=gnu11`.)
  76  * http://gmplib.org[GMP] (GNU Multiple Precision arithmetic library)
  77  * http://savannah.gnu.org/projects/make[GNU Make]
  78  * http://www.gnu.org/software/bash/[GNU Bash]
  79  * binutils (`ar`, `ranlib`, `strip`, ...)
  80  * miscellaneous Unix utilities (`diff`, `find`, `grep`, `gzip`, `patch`, `sed`, `tar`, `xargs`, ...)
  81  * Standard{nbsp}ML compiler and tools to bootstrap:
  82    - http://mlton.org[MLton] (`mlton`, `mllex`, and `mlyacc`) recommended.  Pre-built binary packages for MLton can be installed via an OS package manager or (for select platforms) obtained from `http://mlton.org`.
  83    - http://www.smlnj.org[SML/NJ] (`sml`, `ml-lex`, `ml-yacc`) supported, but not recommended.
  84  * (optional, for documentation only) https://ctan.org/tex/[TeX], http://asciidoc.org/[AsciiDoc], http://pygments.org/[Pygments], http://www.graphicsmagick.org/[GraphicsMagick] or https://www.imagemagick.org/[ImageMagick], ...
  85
  86 ==== Hardware
  87
  88  * &ge; 1GB RAM (for 32-bit platforms) or &ge; 2GB RAM (for 64-bit platforms)
  89
  90 === Build Instructions
  91
  92 On typical platforms, building MLton requires no configuration and can be
  93 accomplished via:
  94
  95 [source,shell]
  96 ----
  97 $ make all
  98 ----
  99
 100 A small set of `Makefile` variables can be used to customize the build:
 101
 102  * `CC`: Specify C compiler.  Can be used for alternative tools (e.g.,
 103    `CC=clang` or `CC=gcc-7`).
 104  * `WITH_GMP_DIR`, `WITH_GMP_INC_DIR`, `WITH_GMP_LIB_DIR`: Specify GMP include
 105    and library paths, if not on default search paths.  (If `WITH_GMP_DIR` is
 106    set, then `WITH_GMP_INC_DIR` defaults to `$(WITH_GMP_DIR)/include` and
 107    `WITH_GMP_LIB_DIR` defaults to `$(WITH_GMP_DIR)/lib`.)
 108  * `MLTON_RUNTIME_ARGS`, `MLTON_COMPILE_ARGS`: Specify runtime and compile
 109    arguments given to (the to-be-built) `mlton` when compiling distributed
 110    executables ((self-compiled) `mlton`, `mllex`, `mlyacc`, `mlprof`, and
 111    `mlnlffigen`). Can be used for testing (e.g., `MLTON_COMPILE_ARGS="-codegen
 112    c"`) or for downstream packaging.
 113  * `BOOTSTRAP_MLTON_RUNTIME_ARGS`, `BOOTSTRAP_MLTON_COMPILE_ARGS`: Specify
 114    runtime and compile arguments given to "old" `mlton` when compiling
 115    "bootstrapped" `mlton`. Can be used to work around bugs in "old" `mlton` when
 116    compiling "bootstrapped" `mlton`.
 117
 118 For example:
 119
 120 [source,shell]
 121 ----
 122 $ make CC=clang WITH_GMP_DIR=/opt/gmp MLTON_COMPILE_ARGS="-codegen c" all
 123 ----
 124
 125 The build artifacts are located under `./build`.  The just-built `mlton` can be
 126 executed via `./build/bin/mlton`.
 127
 128 Building documentation can be accomplished via:
 129
 130 [source,shell]
 131 ----
 132 $ make docs
 133 ----
 134
 135 === Install Instructions
 136
 137 On typical platforms, installing MLton (after performing `make all` and,
 138 optionally, `make docs`) to `/usr/local` can be accomplished via:
 139
 140 [source,shell]
 141 ----
 142 $ make install
 143 ----
 144
 145 A small set of `Makefile` variables can be used to customize the installation:
 146
 147  * `PREFIX`: Specify the installation prefix.
 148
 149 For example:
 150
 151 [source,shell]
 152 ----
 153 $ make PREFIX=/opt/mlton install
 154 ----
 155
 156 == Install (from binary package)
 157
 158 === Requirements
 159
 160 ==== Software
 161
 162  * http://gcc.gnu.org/[GCC] or http://clang.llvm.org[Clang] (The C compiler must support `-std=gnu11`.)
 163  * http://gmplib.org[GMP] (GNU Multiple Precision arithmetic library)
 164  * http://savannah.gnu.org/projects/make[GNU Make]
 165  * http://www.gnu.org/software/bash/[GNU Bash]
 166  * miscellaneous Unix utilities (`bzip2`, `gzip`, `sed`, `tar`, ...)
 167
 168 === Binary Package
 169
 170 A `.tgz` or `.tbz` binary package can be extracted at any location, yielding
 171 `README.adoc` (this file), `CHANGELOG.adoc`, `LICENSE`, `Makefile`, `bin/`,
 172 `lib/`, and `share/`.  The compiler and tools can be executed in-place (e.g.,
 173 `./bin/mlton`).
 174
 175 A small set of `Makefile` variables can be used to customize the binary package
 176 via `make update`:
 177
 178  * `CC`: Specify C compiler.  Can be used for alternative tools (e.g.,
 179    `CC=clang` or `CC=gcc-7`).
 180  * `WITH_GMP_DIR`, `WITH_GMP_INC_DIR`, `WITH_GMP_LIB_DIR`: Specify GMP include
 181    and library paths, if not on default search paths.  (If `WITH_GMP_DIR` is
 182    set, then `WITH_GMP_INC_DIR` defaults to `$(WITH_GMP_DIR)/include` and
 183    `WITH_GMP_LIB_DIR` defaults to `$(WITH_GMP_DIR)/lib`.)
 184
 185 For example:
 186
 187 [source,shell]
 188 ----
 189 $ make CC=clang WITH_GMP_DIR=/opt/gmp update
 190 ----
 191
 192 === Install Instructions
 193
 194 On typical platforms, installing MLton (after optionally performing
 195 `make update`) to `/usr/local` can be accomplished via:
 196
 197 [source,shell]
 198 ----
 199 $ make install
 200 ----
 201
 202 A small set of `Makefile` variables can be used to customize the installation:
 203
 204  * `PREFIX`: Specify the installation prefix.
 205
 206 For example:
 207
 208 [source,shell]
 209 ----
 210 $ make PREFIX=/opt/mlton install
 211 ----
 212
 213 == Resources
 214
 215  * `http://mlton.org`
 216  * mailing lists
 217    - `MLton-devel@mlton.org` -- MLton developers
 218      (https://sourceforge.net/mailarchive/forum.php?forum_name=mlton-devel[archive],
 219      https://lists.sourceforge.net/lists/listinfo/mlton-devel[subscribe])
 220    - `MLton-user@mlton.org` -- MLton user community
 221      (https://sourceforge.net/mailarchive/forum.php?forum_name=mlton-user[archive],
 222      https://lists.sourceforge.net/lists/listinfo/mlton-user[subscribe])
 223
 224 == Need help? Found a bug?
 225
 226 https://github.com/MLton/mlton/issues[Submit an issue] if you need any help.
 227 We welcome pull requests with bug fixes or changes.