Commit | Line | Data |
---|---|---|
7f918cf1 CE |
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. |