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 {4|8}
45 Aligns object sizes and doubles in memory by the specified
46 alignment. The default varies depending on architecture.
47 -as-opt option
50 Pass option to gcc when assembling.
51 -cc-opt option
54 Pass option to gcc when compiling C code.
55 -codegen {native|x86|amd64|c}
58 Generate native code or C code. With -codegen native (-codegen
59 x86 or -codegen amd64), MLton typically compiles more quickly
60 and generates better code.
61 -const 'name value'
64 Set the value of a compile-time constant. Here is a list of
65 available constants, their default values, and what they con‐
66 trol.
67 Exn.keepHistory {false|true}
69 Enable MLton.Exn.history. There is a performance cost to
70 setting this to true, both in memory usage of exceptions
71 and in run time, because of additional work that must be
72 performed at each exception construction, raise, and han‐
73 dle.
74 -default-ann ann
77 Specify default ML Basis annotations. For example, -default-ann
78 'warnUnused true' causes unused variable warnings to be enabled
79 by default. Defaults may be overridden by an annotation in an
80 ML Basis file.
81 -default-type type
84 Specify the default binding for a primitive type. For example,
85 -default-type word64 causes the top-level type word and the top-
86 level structure Word in the Basis Library to be equal to
87 Word64.word and Word64:WORD, respectively. Similarly,
88 -default-type intinf causes the top-level type int and the top-
89 level structure Int in the Basis Library to be equal to
90 IntInf.int and IntInf:INTEGER, respectively.
91 -disable-ann ann
94 Ignore the specified ML Basis annotation in every ML Basis File.
95 For example, to see all match and unused warnings, compile with
96 -default-ann 'warnUnused true', -disable-ann forceUsed, -dis‐
97 able-ann nonexhaustiveMatch, -disable-ann redundantMatch, and
98 -disable-ann warnUnused.
99 -export-header file
102 Write C prototypes to file for all of the functions in the pro‐
103 gram exported from SML to C.
104 -ieee-fp {false|true}
107 Cause the x86 native code generator to be pedantic about follow‐
108 ing the IEEE floating point standard. By default, it is not,
109 because of the performance cost. This only has an effect with
110 -codegen x86.
111 -inline n
114 Set the inlining threshold used in the optimizer. The threshold
115 is an approximate measure of code size of a procedure. The
116 default is 320.
117 -keep {g|o}
120 Save intermediate files. If no -keep argument is given, then
121 only the output file is saved.
122 g generated .c and .s files passed to gcc and the assem‐
123 bler
124 o object (.o) files
125 -link-opt option
128 Pass option to gcc when linking. You can use this to specify
129 library search paths, e.g. -link-opt -Lpath, and libraries to
130 link with, e.g. -link-opt -lfoo, or even both at the same time,
131 e.g. -link-opt '-Lpath -lfoo'. If you wish to pass an option to
132 the linker, you must use gcc's -Wl, syntax, e.g., -link-opt
133 '-Wl,--export-dynamic'.
134 -mlb-path-map file
137 Use file as an ML Basis path map to define additional MLB path
138 variables. Multiple uses of -mlb-path-map and -mlb-path-var are
139 allowed, with variable definitions in later path maps taking
140 precedence over earlier ones.
141 -mlb-path-var 'name value'
144 Define an additional MLB path variable. Multiple uses of
145 -mlb-path-map and -mlb-path-var are allowed, with variable defi‐
146 nitions in later path maps taking precedence over earlier ones.
147 -output file
150 Specify the name of the final output file. The default name is
151 the input file name with its suffix removed and an appropriate,
152 possibly empty, suffix added.
153 -profile {no|alloc|count|time}
156 Produce an executable that gathers profiling data. When such an
157 executable is run, it will produce an mlmon.out file. The man
158 page on mlprof describes how to extract information from this
159 file.
160 -profile-branch {false|true}
163 If true, the profiler will separately gather profiling data for
164 each branch of a function definition, case expression, and if
165 expression.
166 -profile-stack {false|true}
169 If true, the profiler will gather profiling data for all func‐
170 tions on the stack, not just the currently executing function.
171 -profile-val {false|true}
174 If true, the profiler will separately gather profiling data for
175 each (expansive) val declaration.
176 -runtime arg
179 Pass argument to the runtime system via @MLton. The argument
180 will be processed before other @MLton command line switches.
181 Multiple uses of -runtime are allowed, and will pass all the
182 arguments in order. If the same runtime switch occurs more than
183 once, then the last setting will take effect. There is no need
184 to supply the leading @MLton or the trailing --; these will be
185 supplied automatically.
186 An argument to -runtime may contain spaces, which will cause the
188 argument to be treated as a sequence of words by the runtime.
189 For example, the command line:
190 mlton -runtime 'ram-slop 0.4' foo.sml
191 will cause foo to run as if it had been called like
192 foo @MLton ram-slop 0.4 --
193 An executable created with -runtime stop doesn't process any
195 @MLton arguments. This is useful to create an executable, e.g.
196 echo, that must treat @MLton like any other command-line argu‐
197 ment.
198 % mlton -runtime stop echo.sml
199 % echo @MLton --
200 @MLton --
201 -show-basis file
204 Pretty print to file the basis defined by the input program.
205 -show-def-use file
208 Output def-use information to file. Each identifier that is
209 defined appears on a line, followed on subsequent lines by the
210 position of each use.
211 -stop {f|g|o|tc}
214 Specify when to stop.
215 f list of files on stdout (only makes sense when input
216 is foo.mlb)
217 g generated .c and .s files
218 o object (.o) files
219 tc after type checking
220 If you compile -stop g or -stop o, you can resume compilation by
221 running MLton on the generated .c and .s or .o files.
222 -target {self|...}
225 Generate an executable that runs on the specified platform. The
226 default is self, which means to compile for the machine that
227 MLton is running on. To use any other target, you must first
228 install a cross compiler. See the MLton Guide for details.
229 -target-as-opt target option
232 Like -as-opt, this passes option to gcc when assembling, except
233 it only passes option when the target architecture or operating
234 system is target. Valid values for target are: alpha, amd64,
235 arm,, hppa, ia64, m68k, mips, powerpc, powerpc64, s390, sparc,
236 x86, aix, cygwin, darwin, freebsd, hurd, hpux, linux, mingw,
237 netbsd, openbsd, solaris.
238 -target-cc-opt target option
241 Like -cc-opt, this passes option to gcc when compiling C code,
242 except it only passes option when the target architecture or
243 operating system is target. Valid values for target are as for
244 -target-as-opt.
245 -target-link-opt target option
248 Like -link-opt, this passes option to gcc when linking, except
249 it only passes option when the target architecture or operating
250 system is target. Valid values for target are as for -tar‐
251 get-as-opt.
252 -verbose {0|1|2|3}
255 How verbose to be about what passes are running. The default is
256 0.
257 0 silent
258 1 calls to compiler, assembler, and linker
259 2 1, plus intermediate compiler passes
260 3 2, plus some data structure sizes
261
264 Executables produced by MLton take command line arguments that control
265 the runtime system. These arguments are optional, and occur before the
266 executable's usual arguments. To use these options, the first argument
267 to the executable must be @MLton. The optional arguments then follow,
268 must be terminated by --, and are followed by any arguments to the pro‐
269 gram. The optional arguments are not made available to the SML program
270 via CommandLine.arguments. For example, a valid call to hello-world
271 is:
272 hello-world @MLton gc-summary fixed-heap 10k -- a b c
273 In the above example, CommandLine.arguments () = ["a", "b", "c"].
274 It is allowed to have a sequence of @MLton arguments, as in:
276 hello-world @MLton gc-summary -- @MLton fixed-heap 10k -- a b c
277 Run-time options can also control MLton, as in
279 mlton @MLton fixed-heap 0.5g -- foo.sml
280 fixed-heap x{k|K|m|M|g|G}
283 Use a fixed size heap of size x, where x is a real number and
284 the trailing letter indicates its units.
285 k or K 1024
286 m or M 1,048,576
287 g or G 1,073,741,824
288 A value of 0 means to use almost all the RAM present on the
289 machine.
290 The heap size used by fixed-heap includes all memory allocated
292 by SML code, including memory for the stack (or stacks, if there
293 are multiple threads). It does not, however, include any memory
294 used for code itself or memory used by C globals, the C stack,
295 or malloc.
296 gc-messages
299 Print a message at the start and end of every garbage collec‐
300 tion.
301 gc-summary
304 Print a summary of garbage collection statistics upon program
305 termination.
306 load-world world
309 Restart the computation with the file specified by world, which
310 must have been created by a call to MLton.World.save by the same
311 executable. See the MLton Guide for details.
312 max-heap x{k|K|m|M|g|G}
315 Run the computation with an automatically resized heap that is
316 never larger than x, where x is a real number and the trailing
317 letter indicates the units as with fixed-heap. The heap size
318 for max-heap is accounted for as with fixed-heap.
319 may-page-heap {false|true}
322 Enable paging the heap to disk when unable to grow the heap to a
323 desired size.
324 no-load-world
327 Disable load-world. This can be used as an argument to the com‐
328 piler via -runtime no-load-world to create executables that will
329 not load a world. This may be useful to ensure that set-uid
330 executables do not load some strange world.
331 ram-slop x
334 Multiply x by the amount of RAM on the machine to obtain what
335 the runtime views as the amount of RAM it can use. Typically x
336 is less than 1, and is used to account for space used by other
337 programs running on the same machine.
338 stop Causes the runtime to stop processing @MLton arguments once the
341 next -- is reached. This can be used as an argument to the com‐
342 piler via -runtime stop to create executables that don't process
343 any @MLton arguments.
344
347 MLton's type error messages are not in a form suitable for processing
348 by Emacs. For details on how to fix this, see http://mlton.org/Emacs.
349
352 mlprof(1) and the MLton Guide.
353 June 8, 2010 mlton(1)