Commit | Line | Data |
---|---|---|
7f918cf1 CE |
1 | .TH mlton 1 "February 6, 2018" |
2 | .SH NAME | |
3 | \fBmlton\fP \- whole-program compiler for the Standard ML (SML) programming | |
4 | language | |
5 | .SH SYNOPSIS | |
6 | \fBmlton\fP \fI[option ...] file\fB.\fP{\fBc\fP|\fBmlb\fP|\fBo\fP|\fBsml\fP} [file\fB.\fP{\fBc\fP|\fBo\fP|\fBs\fP|\fBS\fP} ...]\fR | |
7 | .SH DESCRIPTION | |
8 | .PP | |
9 | \fBMLton\fP is run from the command line with a collection of options | |
10 | followed by a file name and a list of files with which to compile, assemble, and | |
11 | link with. The simplest case is to run \fBmlton foo.sml\fP, where | |
12 | \fBfoo.sml\fP contains a valid SML program, in which case MLton | |
13 | compiles the program to produce an executable \fBfoo\fP. Since | |
14 | \fBMLton\fP does not support separate compilation, the program must be | |
15 | the entire program you wish to compile. However, the program may | |
16 | refer to signatures and structures defined in the Basis Library. | |
17 | ||
18 | Larger programs, spanning many files, may be compiled with the ML | |
19 | Basis system. In this case, \fBmlton foo.mlb\fP will compile | |
20 | the complete SML program described by the basis \fBfoo.mlb\fP, which | |
21 | may specify both SML files and additional bases. See the \fBMLton | |
22 | Guide\fP for details. | |
23 | ||
24 | \fBMLton\fP's compile-time options control the name of the output | |
25 | file, the verbosity of compile-time messages, and whether or not | |
26 | certain optimizations are performed. They also can specify | |
27 | which intermediate files are saved and can stop the compilation process | |
28 | early, at some intermediate pass, in which case compilation can be | |
29 | resumed by passing the generated files to \fBMLton\fP. \fBMLton\fP | |
30 | uses the input file suffix to determine the type of input program. | |
31 | The possibilities are \fB.c\fP, \fB.mlb\fP, \fB.o\fP, \fB.s\fP, and \fB.sml\fP. | |
32 | ||
33 | With no arguments, \fBMLton\fP prints the version number and exits. | |
34 | For a usage message, run \fBMLton\fP with an invalid switch, e.g. | |
35 | \fBmlton \-z\fP. In the explanation below and in the usage message, | |
36 | for flags that take a number of choices | |
37 | (e.g. \fI{\fBtrue\fP|\fBfalse\fP}\fR), the first value listed is the | |
38 | default. | |
39 | ||
40 | .SH Compile-time options | |
41 | .TP | |
42 | \fB\-align \fIn\fP\fR | |
43 | Aligns objects in memory by the specified alignment (\fB4\fP or \fB8\fP). | |
44 | The default varies depending on architecture. | |
45 | ||
46 | .TP | |
47 | \fB\-as\-opt \fIoption\fP\fR | |
48 | Pass \fIoption\fP to \fBgcc\fP when compiling assembler code. If you | |
49 | wish to pass an option to the assembler, you must use \fBgcc\fP's | |
50 | \fB\-Wa,\fP syntax. | |
51 | ||
52 | .TP | |
53 | \fB\-cc\-opt \fIoption\fP\fR | |
54 | Pass \fIoption\fP to \fBgcc\fP when compiling C code. | |
55 | ||
56 | .TP | |
57 | \fB\-codegen \fI{\fBnative\fP|\fBx86\fP|\fBamd64\fP|\fBc\fP|\fBllvm\fP}\fP\fR | |
58 | Generate native object code via amd64 assembly, C code, LLVM code, or | |
59 | x86 assembly. With \fB\-codegen native\fP (\fB\-codegen amd64\fP or | |
60 | \fB\-codegen x86\fP), \fBMLton\fP typically compiles more quickly and | |
61 | generates better code. | |
62 | ||
63 | .TP | |
64 | \fB\-const '\fIname value\fP'\fR | |
65 | Set the value of a compile-time constant. Here is a list of available | |
66 | constants, their default values, and what they control. | |
67 | ||
68 | \fBExn.keepHistory \fI{\fBfalse\fP|\fBtrue\fP}\fP\fR | |
69 | .in +.5i | |
70 | Enable \fBMLton.Exn.history\fP. There is a performance cost to setting this | |
71 | to \fBtrue\fP, both in memory usage of exceptions and in run time, | |
72 | because of additional work that must be performed at each exception | |
73 | construction, raise, and handle. | |
74 | .in -.5i | |
75 | ||
76 | .TP | |
77 | \fB\-default\-ann \fIann\fP\fR | |
78 | Specify default ML Basis annotations. For | |
79 | example, \fB\-default\-ann 'warnUnused true'\fP | |
80 | causes unused variable warnings to be enabled by default. | |
81 | Defaults may be overridden by an annotation in an ML Basis file. | |
82 | ||
83 | .TP | |
84 | \fB\-default\-type \fItype\fP\fR | |
85 | Specify the default binding for a primitive type. For example, | |
86 | \fB\-default\-type word64\fP causes the top-level type \fBword\fP and | |
87 | the top-level structure \fBWord\fP in the Basis Library to be equal to | |
88 | \fBWord64.word\fP and \fBWord64:WORD\fP, respectively. Similarly, | |
89 | \fB\-default\-type intinf\fP causes the top-level type \fBint\fP and | |
90 | the top-level structure \fBInt\fP in the Basis Library to be equal to | |
91 | \fBIntInf.int\fP and \fBIntInf:INTEGER\fP, respectively. | |
92 | ||
93 | .TP | |
94 | \fB\-disable\-ann \fIann\fP\fR | |
95 | Ignore the specified ML Basis annotation in every ML Basis File. For example, | |
96 | to see \fIall\fP match and unused warnings, compile with | |
97 | \fB\-default\-ann 'warnUnused true'\fP, | |
98 | \fB\-disable\-ann forceUsed\fP, | |
99 | \fB\-disable\-ann nonexhaustiveMatch\fP, | |
100 | \fB\-disable\-ann redundantMatch\fP, | |
101 | and \fB\-disable\-ann warnUnused\fP. | |
102 | ||
103 | .TP | |
104 | \fB\-export\-header \fIfile\fP\fR | |
105 | Write C prototypes to \fIfile\fP for all of the functions in the | |
106 | program exported from SML to C. | |
107 | ||
108 | .TP | |
109 | \fB\-ieee\-fp \fI{\fBfalse\fP|\fBtrue\fP}\fP\fR | |
110 | Cause the x86 native code generator to be pedantic about following the IEEE | |
111 | floating point standard. By default, it is not, because of the | |
112 | performance cost. This only has an effect with \fB\-codegen x86\fP. | |
113 | ||
114 | .TP | |
115 | \fB\-inline \fIn\fP\fR | |
116 | Set the inlining threshold used in the optimizer. The threshold is an | |
117 | approximate measure of code size of a procedure. The default is 320. | |
118 | ||
119 | .TP | |
120 | \fB\-keep \fI{\fBg\fP|\fBo\fP}\fP\fR | |
121 | Save intermediate files. If no \fB\-keep\fP argument is given, then | |
122 | only the output file is saved. | |
123 | .in +.5i | |
124 | \fBg\fP generated \fB.c\fP and \fB.s\fP files passed to \fBgcc\fP and generated \fB.ll\fP files passed to \fBllvm-as\fP | |
125 | .br | |
126 | \fBo\fP object (\fB.o\fP) files | |
127 | .in -.5i | |
128 | ||
129 | .TP | |
130 | \fB\-llvm\-as\-opt \fIoption\fP\fR | |
131 | Pass \fIoption\fP to \fBllvm-as\fP when assembling (\fB.ll\fP to \fB.bc\fP) LLVM code. | |
132 | ||
133 | .TP | |
134 | \fB\-llvm\-llc\-opt \fIoption\fP\fR | |
135 | Pass \fIoption\fP to \fBllc\fP when compiling (\fB.bc\fP to \fB.o\fP) LLVM code. | |
136 | ||
137 | .TP | |
138 | \fB\-llvm\-opt\-opt \fIoption\fP\fR | |
139 | Pass \fIoption\fP to \fBopt\fP when optimizing (\fB.bc\fP to \fB.bc\fP) LLVM code. | |
140 | ||
141 | .TP | |
142 | \fB\-link\-opt \fIoption\fP\fR | |
143 | Pass \fIoption\fP to \fBgcc\fP when linking. You can use this to | |
144 | specify library search paths, e.g. \fB\-link\-opt \-Lpath\fP, and | |
145 | libraries to link with, e.g. \fB\-link\-opt \-lfoo\fP, or even both at | |
146 | the same time, e.g. \fB\-link\-opt '\-Lpath \-lfoo'\fP. If you wish to | |
147 | pass an option to the linker, you must use \fBgcc\fP's \fB\-Wl,\fP | |
148 | syntax, e.g., \fB\-link\-opt '\-Wl,\-\-export\-dynamic'\fP. | |
149 | ||
150 | .TP | |
151 | \fB\-mlb\-path\-map \fIfile\fP\fR | |
152 | Use \fIfile\fP as an ML Basis path map to define additional MLB path variables. | |
153 | Multiple uses of \fB\-mlb\-path\-map\fP and \fB\-mlb\-path\-var\fP are | |
154 | allowed, with variable definitions in later path maps taking | |
155 | precedence over earlier ones. | |
156 | ||
157 | .TP | |
158 | \fB\-mlb\-path\-var '\fIname value\fP'\fR | |
159 | Define an additional MLB path variable. | |
160 | Multiple uses of \fB\-mlb\-path\-map\fP and \fB\-mlb\-path\-var\fP are | |
161 | allowed, with variable definitions in later path maps taking | |
162 | precedence over earlier ones. | |
163 | ||
164 | .TP | |
165 | \fB\-output \fIfile\fP\fR | |
166 | Specify the name of the final output file. | |
167 | The default name is the input file name with its suffix removed and an | |
168 | appropriate, possibly empty, suffix added. | |
169 | ||
170 | .TP | |
171 | \fB\-profile \fI{\fBno\fP|\fBalloc\fP|\fBcount\fP|\fBtime\fP}\fP\fR | |
172 | Produce an executable that gathers profiling data. When | |
173 | such an executable is run, it will produce an \fBmlmon.out\fP file. | |
174 | The man page on \fBmlprof\fP describes how to extract information from | |
175 | this file. | |
176 | ||
177 | .TP | |
178 | \fB\-profile\-branch \fI{\fBfalse\fP|\fBtrue\fP}\fP\fR | |
179 | If true, the profiler will separately gather profiling data | |
180 | for each branch of a function definition, \fBcase\fP | |
181 | expression, and \fBif\fP expression. | |
182 | ||
183 | .TP | |
184 | \fB\-profile\-stack \fI{\fBfalse\fP|\fBtrue\fP}\fP\fR | |
185 | If true, the profiler will gather profiling data for all | |
186 | functions on the stack, not just the currently executing function. | |
187 | ||
188 | .TP | |
189 | \fB\-profile\-val \fI{\fBfalse\fP|\fBtrue\fP}\fP\fR | |
190 | If true, the profiler will separately gather profiling data | |
191 | for each (expansive) \fBval\fP declaration. | |
192 | ||
193 | .TP | |
194 | \fB\-runtime \fIarg\fP\fR | |
195 | Pass argument to the runtime system via \fB@MLton\fP. The argument | |
196 | will be processed before other \fB@MLton\fP command line switches. | |
197 | Multiple uses of \fB\-runtime\fP are allowed, and will pass all the | |
198 | arguments in order. If the same runtime switch occurs more than once, | |
199 | then the last setting will take effect. There is no need to supply the | |
200 | leading \fB@MLton\fP or the trailing \fB\-\-\fP; these will be | |
201 | supplied automatically. | |
202 | ||
203 | An argument to \fB\-runtime\fP may contain spaces, which will cause the | |
204 | argument to be treated as a sequence of words by the runtime. For | |
205 | example, the command line: | |
206 | .in +.5i | |
207 | \fBmlton \-runtime 'ram\-slop 0.4' foo.sml\fP | |
208 | .in -.5i | |
209 | will cause foo to run as if it had been called like | |
210 | .in +.5i | |
211 | \fBfoo @MLton ram\-slop 0.4 \-\-\fP | |
212 | .in -.5i | |
213 | ||
214 | An executable created with \fB\-runtime stop\fP doesn't process any | |
215 | \fB@MLton\fP arguments. This is useful to create an executable, | |
216 | e.g. \fBecho\fP, that must treat \fB@MLton\fP like any other | |
217 | command-line argument. | |
218 | .in +.5i | |
219 | \fB% mlton \-runtime stop echo.sml\fP | |
220 | .in -.5i | |
221 | .in +.5i | |
222 | \fB% echo @MLton \-\-\fP | |
223 | .in -.5i | |
224 | .in +.5i | |
225 | \fB@MLton \-\-\fP | |
226 | .in -.5i | |
227 | ||
228 | .TP | |
229 | \fB\-show\-basis \fIfile\fP\fR | |
230 | Pretty print to \fIfile\fP the basis defined by the input program. | |
231 | ||
232 | .TP | |
233 | \fB\-show\-def\-use \fIfile\fP\fR | |
234 | Output def-use information to \fIfile\fP. Each identifier that is | |
235 | defined appears on a line, followed on subsequent lines by the position | |
236 | of each use. | |
237 | ||
238 | .TP | |
239 | \fB\-stop \fI{\fBf\fP|\fBg\fP|\fBo\fP|\fBtc\fP}\fP\fR | |
240 | Specify when to stop. | |
241 | .in +.5i | |
242 | \fBf\fP list of files on stdout (only makes sense when input is \fBfoo.mlb\fP) | |
243 | .br | |
244 | \fBg\fP generated \fB.c\fP and \fB.s\fP files | |
245 | .br | |
246 | \fBo\fP object (\fB.o\fP) files | |
247 | .br | |
248 | \fBtc\fP after type checking | |
249 | .in -.5i | |
250 | If you compile \fB\-stop g\fP or \fB\-stop o\fP, you can resume | |
251 | compilation by running \fBMLton\fP on the generated \fB.c\fP and \fB.s\fP | |
252 | or \fB.o\fP files. | |
253 | ||
254 | .TP | |
255 | \fB\-target \fI{\fBself\fP|...}\fP\fR | |
256 | Generate an executable that runs on the specified platform. The | |
257 | default is \fBself\fP, which means to compile for the machine that | |
258 | \fBMLton\fP is running on. To use any other target, you must first | |
259 | install a cross compiler. See the \fBMLton Guide\fP for | |
260 | details. | |
261 | ||
262 | .TP | |
263 | \fB\-target\-as\-opt \fItarget\fP \fIoption\fP\fR | |
264 | Like \fB\-as\-opt\fP, this passes \fIoption\fP to \fBgcc\fP when assembling, | |
265 | except it only passes \fIoption\fP when the target architecture or | |
266 | operating system is \fItarget\fP. | |
267 | ||
268 | .TP | |
269 | \fB\-target\-cc\-opt \fItarget\fP \fIoption\fP\fR | |
270 | Like \fB\-cc\-opt\fP, this passes \fIoption\fP to \fBgcc\fP when compiling | |
271 | C code, except it only passes \fIoption\fP when the target architecture | |
272 | or operating system is \fItarget\fP. | |
273 | ||
274 | .TP | |
275 | \fB\-target\-link\-opt \fItarget\fP \fIoption\fP\fR | |
276 | Like \fB\-link\-opt\fP, this passes \fIoption\fP to \fBgcc\fP when linking, | |
277 | except it only passes \fIoption\fP when the target architecture or | |
278 | operating system is \fItarget\fP. | |
279 | ||
280 | .TP | |
281 | \fB\-verbose \fI{\fB0\fP|\fB1\fP|\fB2\fP|\fB3\fP}\fP\fR | |
282 | How verbose to be about what passes are running. The default is 0. | |
283 | .in +.5i | |
284 | \fB0\fP silent | |
285 | .br | |
286 | \fB1\fP calls to compiler, assembler, and linker | |
287 | .br | |
288 | \fB2\fP 1, plus intermediate compiler passes | |
289 | .br | |
290 | \fB3\fP 2, plus some data structure sizes | |
291 | .in -.5i | |
292 | ||
293 | .SH Runtime system options | |
294 | Executables produced by \fBMLton\fP take command line arguments that control | |
295 | the runtime system. These arguments are optional, and occur before | |
296 | the executable's usual arguments. To use these options, the first | |
297 | argument to the executable must be \fB@MLton\fP. The optional | |
298 | arguments then follow, must be terminated by \fB\-\-\fP, and are | |
299 | followed by any arguments to the program. The optional arguments are | |
300 | \fInot\fP made available to the SML program via | |
301 | \fBCommandLine.arguments\fP. For example, a valid call to | |
302 | \fBhello-world\fP is: | |
303 | .in +.5i | |
304 | \fBhello-world @MLton gc\-summary fixed\-heap 10k \-\- a b c\fP | |
305 | .in -.5i | |
306 | In the above example, | |
307 | \fBCommandLine.arguments () = ["a", "b", "c"]\fP. | |
308 | ||
309 | It is allowed to have a sequence of \fB@MLton\fP arguments, as in: | |
310 | .in +.5i | |
311 | \fBhello-world @MLton gc\-summary \-\- @MLton fixed\-heap 10k \-\- a b c\fP | |
312 | .in -.5i | |
313 | ||
314 | Run-time options can also control \fBMLton\fP, as in | |
315 | .in +.5i | |
316 | \fBmlton @MLton fixed\-heap 0.5g \-\- foo.sml\fP | |
317 | .in -.5i | |
318 | ||
319 | .TP | |
320 | \fBfixed\-heap \fIx{\fBk\fP|\fBK\fP|\fBm\fP|\fBM\fP|\fBg\fP|\fBG\fP}\fP\fR | |
321 | Use a fixed size heap of size \fIx\fP, where \fIx\fP is a real number | |
322 | and the trailing letter indicates its units. | |
323 | .in +.5i | |
324 | \fBk\fP or \fBK\fP 1024 | |
325 | .br | |
326 | \fPm\fP or \fBM\fP 1,048,576 | |
327 | .br | |
328 | \fBg\fP or \fBG\fP 1,073,741,824 | |
329 | .in -.5i | |
330 | A value of \fB0\fP means to use almost all the RAM present on the machine. | |
331 | ||
332 | The heap size used by \fBfixed\-heap\fP includes all memory | |
333 | allocated by SML code, including memory for the stack (or stacks, | |
334 | if there are multiple threads). It does not, however, include any | |
335 | memory used for code itself or memory used by C globals, the C | |
336 | stack, or malloc. | |
337 | ||
338 | .TP | |
339 | \fBgc\-messages\fP | |
340 | Print a message at the start and end of every garbage collection. | |
341 | ||
342 | .TP | |
343 | \fBgc\-summary\fP | |
344 | Print a summary of garbage collection statistics upon program | |
345 | termination. | |
346 | ||
347 | .TP | |
348 | \fBgc\-summary\-file \fIfile\fP\fP | |
349 | Print a summary of garbage collection statistics upon program | |
350 | termination to the file specified by \fIfile\fP. | |
351 | ||
352 | .TP | |
353 | \fBload\-world \fIworld\fP\fR | |
354 | Restart the computation with the file specified by \fIworld\fP, which must have | |
355 | been created by a call to \fBMLton.World.save\fP by the same | |
356 | executable. See the \fBMLton Guide\fP for details. | |
357 | ||
358 | .TP | |
359 | \fBmax\-heap \fIx{\fBk\fP|\fBK\fP|\fBm\fP|\fBM\fP|\fBg\fP|\fBG\fP}\fP\fR | |
360 | Run the computation with an automatically resized heap that is never | |
361 | larger than \fIx\fP, where \fIx\fP is a real number and the trailing | |
362 | letter indicates the units as with \fBfixed\-heap\fP. The | |
363 | heap size for \fBmax\-heap\fP is accounted for as with | |
364 | \fBfixed\-heap\fP. | |
365 | ||
366 | .TP | |
367 | \fBmay\-page\-heap \fI{\fBfalse\fP|\fBtrue\fP}\fP\fR | |
368 | Enable paging the heap to disk when unable to grow the heap to a | |
369 | desired size. | |
370 | ||
371 | .TP | |
372 | \fBno\-load\-world\fP | |
373 | Disable \fBload\-world\fP. This can be used as an argument to the | |
374 | compiler via \fB\-runtime no\-load\-world\fP to create executables that | |
375 | will not load a world. This may be useful to ensure that set-uid | |
376 | executables do not load some strange world. | |
377 | ||
378 | .TP | |
379 | \fBram\-slop \fIx\fP\fR | |
380 | Multiply \fBx\fP by the amount of RAM on the machine to obtain what | |
381 | the runtime views as the amount of RAM it can use. Typically \fBx\fP | |
382 | is less than 1, and is used to account for space used by other | |
383 | programs running on the same machine. | |
384 | ||
385 | .TP | |
386 | \fBstop\fP | |
387 | Causes the runtime to stop processing \fB@MLton\fP arguments once the | |
388 | next \fB\-\-\fP is reached. This can be used as an argument to the | |
389 | compiler via \fB\-runtime stop\fP to create executables that don't | |
390 | process any \fB@MLton\fP arguments. | |
391 | ||
392 | .SH DIAGNOSTICS | |
393 | MLton's type error messages are not in a form suitable for processing | |
394 | by Emacs. For details on how to fix this, see | |
395 | http://mlton.org/Emacs. | |
396 | ||
397 | .SH "SEE ALSO" | |
398 | .BR mlprof (1) | |
399 | and the \fBMLton Guide\fP. |