1mlton(1) General Commands Manual mlton(1)
2
6 mlton - whole-program compiler for the Standard ML (SML) programming
7 language
8
10 mlton [option ...] file.{c|mlb|o|sml} [file.{c|o|s|S} ...]
11
13 MLton is run from the command line with a collection of options fol‐
14 lowed by a file name and a list of files with which to compile, assem‐
15 ble, and link with. The simplest case is to run mlton foo.sml, where
16 foo.sml contains a valid SML program, in which case MLton compiles the
17 program to produce an executable foo. Since MLton does not support
18 separate compilation, the program must be the entire program you wish
19 to compile. However, the program may refer to signatures and struc‐
20 tures defined in the Basis Library.
21 Larger programs, spanning many files, may be compiled with the ML Basis
23 system. In this case, mlton foo.mlb will compile the complete SML pro‐
24 gram described by the basis foo.mlb, which may specify both SML files
25 and additional bases. See the MLton Guide for details.
26 MLton's compile-time options control the name of the output file, the
28 verbosity of compile-time messages, and whether or not certain opti‐
29 mizations are performed. They also can specify which intermediate
30 files are saved and can stop the compilation process early, at some
31 intermediate pass, in which case compilation can be resumed by passing
32 the generated files to MLton. MLton uses the input file suffix to
33 determine the type of input program. The possibilities are .c, .mlb,
34 .o, .s, and .sml.
35 With no arguments, MLton prints the version number and exits. For a
37 usage message, run MLton with an invalid switch, e.g. mlton -z. In
38 the explanation below and in the usage message, for flags that take a
39 number of choices (e.g. {true|false}), the first value listed is the
40 default.
41
44 -align n
45 Aligns objects in memory by the specified alignment (4 or 8).
46 The default varies depending on architecture.
47 -as-opt option
50 Pass option to gcc when compiling assembler code. If you wish
51 to pass an option to the assembler, you must use gcc's -Wa, syn‐
52 tax.
53 -cc-opt option
56 Pass option to gcc when compiling C code.
57 -codegen {native|x86|amd64|c|llvm}
60 Generate native object code via amd64 assembly, C code, LLVM
61 code, or x86 assembly. With -codegen native (-codegen amd64 or
62 -codegen x86), MLton typically compiles more quickly and gener‐
63 ates better code.
64 -const 'name value'
67 Set the value of a compile-time constant. Here is a list of
68 available constants, their default values, and what they con‐
69 trol.
70 Exn.keepHistory {false|true}
72 Enable MLton.Exn.history. There is a performance cost to
73 setting this to true, both in memory usage of exceptions
74 and in run time, because of additional work that must be
75 performed at each exception construction, raise, and han‐
76 dle.
77 -default-ann ann
80 Specify default ML Basis annotations. For example, -default-ann
81 'warnUnused true' causes unused variable warnings to be enabled
82 by default. Defaults may be overridden by an annotation in an
83 ML Basis file.
84 -default-type type
87 Specify the default binding for a primitive type. For example,
88 -default-type word64 causes the top-level type word and the top-
89 level structure Word in the Basis Library to be equal to
90 Word64.word and Word64:WORD, respectively. Similarly,
91 -default-type intinf causes the top-level type int and the top-
92 level structure Int in the Basis Library to be equal to
93 IntInf.int and IntInf:INTEGER, respectively.
94 -disable-ann ann
97 Ignore the specified ML Basis annotation in every ML Basis File.
98 For example, to see all match and unused warnings, compile with
99 -default-ann 'warnUnused true', -disable-ann forceUsed, -dis‐
100 able-ann nonexhaustiveMatch, -disable-ann redundantMatch, and
101 -disable-ann warnUnused.
102 -export-header file
105 Write C prototypes to file for all of the functions in the pro‐
106 gram exported from SML to C.
107 -ieee-fp {false|true}
110 Cause the x86 native code generator to be pedantic about follow‐
111 ing the IEEE floating point standard. By default, it is not,
112 because of the performance cost. This only has an effect with
113 -codegen x86.
114 -inline n
117 Set the inlining threshold used in the optimizer. The threshold
118 is an approximate measure of code size of a procedure. The
119 default is 320.
120 -keep {g|o}
123 Save intermediate files. If no -keep argument is given, then
124 only the output file is saved.
125 g generated .c and .s files passed to gcc and generated
126 .ll files passed to llvm-as
127 o object (.o) files
128 -llvm-as-opt option
131 Pass option to llvm-as when assembling (.ll to .bc) LLVM code.
132 -llvm-llc-opt option
135 Pass option to llc when compiling (.bc to .o) LLVM code.
136 -llvm-opt-opt option
139 Pass option to opt when optimizing (.bc to .bc) LLVM code.
140 -link-opt option
143 Pass option to gcc when linking. You can use this to specify
144 library search paths, e.g. -link-opt -Lpath, and libraries to
145 link with, e.g. -link-opt -lfoo, or even both at the same time,
146 e.g. -link-opt '-Lpath -lfoo'. If you wish to pass an option to
147 the linker, you must use gcc's -Wl, syntax, e.g., -link-opt
148 '-Wl,--export-dynamic'.
149 -mlb-path-map file
152 Use file as an ML Basis path map to define additional MLB path
153 variables. Multiple uses of -mlb-path-map and -mlb-path-var are
154 allowed, with variable definitions in later path maps taking
155 precedence over earlier ones.
156 -mlb-path-var 'name value'
159 Define an additional MLB path variable. Multiple uses of
160 -mlb-path-map and -mlb-path-var are allowed, with variable defi‐
161 nitions in later path maps taking precedence over earlier ones.
162 -output file
165 Specify the name of the final output file. The default name is
166 the input file name with its suffix removed and an appropriate,
167 possibly empty, suffix added.
168 -profile {no|alloc|count|time}
171 Produce an executable that gathers profiling data. When such an
172 executable is run, it will produce an mlmon.out file. The man
173 page on mlprof describes how to extract information from this
174 file.
175 -profile-branch {false|true}
178 If true, the profiler will separately gather profiling data for
179 each branch of a function definition, case expression, and if
180 expression.
181 -profile-stack {false|true}
184 If true, the profiler will gather profiling data for all func‐
185 tions on the stack, not just the currently executing function.
186 -profile-val {false|true}
189 If true, the profiler will separately gather profiling data for
190 each (expansive) val declaration.
191 -runtime arg
194 Pass argument to the runtime system via @MLton. The argument
195 will be processed before other @MLton command line switches.
196 Multiple uses of -runtime are allowed, and will pass all the
197 arguments in order. If the same runtime switch occurs more than
198 once, then the last setting will take effect. There is no need
199 to supply the leading @MLton or the trailing --; these will be
200 supplied automatically.
201 An argument to -runtime may contain spaces, which will cause the
203 argument to be treated as a sequence of words by the runtime.
204 For example, the command line:
205 mlton -runtime 'ram-slop 0.4' foo.sml
206 will cause foo to run as if it had been called like
207 foo @MLton ram-slop 0.4 --
208 An executable created with -runtime stop doesn't process any
210 @MLton arguments. This is useful to create an executable, e.g.
211 echo, that must treat @MLton like any other command-line argu‐
212 ment.
213 % mlton -runtime stop echo.sml
214 % echo @MLton --
215 @MLton --
216 -show-basis file
219 Pretty print to file the basis defined by the input program.
220 -show-def-use file
223 Output def-use information to file. Each identifier that is
224 defined appears on a line, followed on subsequent lines by the
225 position of each use.
226 -stop {f|g|o|tc}
229 Specify when to stop.
230 f list of files on stdout (only makes sense when input
231 is foo.mlb)
232 g generated .c and .s files
233 o object (.o) files
234 tc after type checking
235 If you compile -stop g or -stop o, you can resume compilation by
236 running MLton on the generated .c and .s or .o files.
237 -target {self|...}
240 Generate an executable that runs on the specified platform. The
241 default is self, which means to compile for the machine that
242 MLton is running on. To use any other target, you must first
243 install a cross compiler. See the MLton Guide for details.
244 -target-as-opt target option
247 Like -as-opt, this passes option to gcc when assembling, except
248 it only passes option when the target architecture or operating
249 system is target.
250 -target-cc-opt target option
253 Like -cc-opt, this passes option to gcc when compiling C code,
254 except it only passes option when the target architecture or
255 operating system is target.
256 -target-link-opt target option
259 Like -link-opt, this passes option to gcc when linking, except
260 it only passes option when the target architecture or operating
261 system is target.
262 -verbose {0|1|2|3}
265 How verbose to be about what passes are running. The default is
266 0.
267 0 silent
268 1 calls to compiler, assembler, and linker
269 2 1, plus intermediate compiler passes
270 3 2, plus some data structure sizes
271
274 Executables produced by MLton take command line arguments that control
275 the runtime system. These arguments are optional, and occur before the
276 executable's usual arguments. To use these options, the first argument
277 to the executable must be @MLton. The optional arguments then follow,
278 must be terminated by --, and are followed by any arguments to the pro‐
279 gram. The optional arguments are not made available to the SML program
280 via CommandLine.arguments. For example, a valid call to hello-world
281 is:
282 hello-world @MLton gc-summary fixed-heap 10k -- a b c
283 In the above example, CommandLine.arguments () = ["a", "b", "c"].
284 It is allowed to have a sequence of @MLton arguments, as in:
286 hello-world @MLton gc-summary -- @MLton fixed-heap 10k -- a b c
287 Run-time options can also control MLton, as in
289 mlton @MLton fixed-heap 0.5g -- foo.sml
290 fixed-heap x{k|K|m|M|g|G}
293 Use a fixed size heap of size x, where x is a real number and
294 the trailing letter indicates its units.
295 k or K 1024
296 m or M 1,048,576
297 g or G 1,073,741,824
298 A value of 0 means to use almost all the RAM present on the
299 machine.
300 The heap size used by fixed-heap includes all memory allocated
302 by SML code, including memory for the stack (or stacks, if there
303 are multiple threads). It does not, however, include any memory
304 used for code itself or memory used by C globals, the C stack,
305 or malloc.
306 gc-messages
309 Print a message at the start and end of every garbage collec‐
310 tion.
311 gc-summary
314 Print a summary of garbage collection statistics upon program
315 termination.
316 gc-summary-file file
319 Print a summary of garbage collection statistics upon program
320 termination to the file specified by file.
321 load-world world
324 Restart the computation with the file specified by world, which
325 must have been created by a call to MLton.World.save by the same
326 executable. See the MLton Guide for details.
327 max-heap x{k|K|m|M|g|G}
330 Run the computation with an automatically resized heap that is
331 never larger than x, where x is a real number and the trailing
332 letter indicates the units as with fixed-heap. The heap size
333 for max-heap is accounted for as with fixed-heap.
334 may-page-heap {false|true}
337 Enable paging the heap to disk when unable to grow the heap to a
338 desired size.
339 no-load-world
342 Disable load-world. This can be used as an argument to the com‐
343 piler via -runtime no-load-world to create executables that will
344 not load a world. This may be useful to ensure that set-uid
345 executables do not load some strange world.
346 ram-slop x
349 Multiply x by the amount of RAM on the machine to obtain what
350 the runtime views as the amount of RAM it can use. Typically x
351 is less than 1, and is used to account for space used by other
352 programs running on the same machine.
353 stop Causes the runtime to stop processing @MLton arguments once the
356 next -- is reached. This can be used as an argument to the com‐
357 piler via -runtime stop to create executables that don't process
358 any @MLton arguments.
359
362 MLton's type error messages are not in a form suitable for processing
363 by Emacs. For details on how to fix this, see http://mlton.org/Emacs.
364
367 mlprof(1) and the MLton Guide.
368 February 6, 2018 mlton(1)