Import Upstream version 20180207
[hcoop/debian/mlton.git] / man / mlton.1
1 .TH mlton 1 "February 6, 2018"
3 \fBmlton\fP \- whole-program compiler for the Standard ML (SML) programming
4 language
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
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.
18 Larger programs, spanning many files, may be compiled with the ML
19 Basis system. In this case, \fBmlton\fP will compile
20 the complete SML program described by the basis \\fP, which
21 may specify both SML files and additional bases. See the \fBMLton
22 Guide\fP for details.
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, \\fP, \fB.o\fP, \fB.s\fP, and \fB.sml\fP.
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.
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.
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.
52 .TP
53 \fB\-cc\-opt \fIoption\fP\fR
54 Pass \fIoption\fP to \fBgcc\fP when compiling C code.
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.
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.
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
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.
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 \\fP and \fBIntInf:INTEGER\fP, respectively.
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.
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.
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.
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.
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
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
228 .TP
229 \fB\-show\-basis \fIfile\fP\fR
230 Pretty print to \fIfile\fP the basis defined by the input program.
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.
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 \\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.
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.
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.
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.
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.
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
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.
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
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
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.
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.
338 .TP
339 \fBgc\-messages\fP
340 Print a message at the start and end of every garbage collection.
342 .TP
343 \fBgc\-summary\fP
344 Print a summary of garbage collection statistics upon program
345 termination.
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.
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 \\fP by the same
356 executable. See the \fBMLton Guide\fP for details.
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.
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.
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.
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.
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.
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
397 .SH "SEE ALSO"
398 .BR mlprof (1)
399 and the \fBMLton Guide\fP.