| 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 | * ≥ 1GB RAM (for 32-bit platforms) or ≥ 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. |