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|cm|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 also supports a limited subset of SML/NJ Compilation Manager (CM)
28 files. For example, mlton foo.cm will compile the complete SML program
29 consisting of the concatenation of all the SML files referred to
30 (either directly or indirectly) by foo.cm.
31 MLton's compile-time options control the name of the output file, the
33 verbosity of compile-time messages, and whether or not certain opti‐
34 mizations are performed. They also can specify which intermediate
35 files are saved and can stop the compilation process early, at some
36 intermediate pass, in which case compilation can be resumed by passing
37 the generated files to MLton. MLton uses the input file suffix to
38 determine the type of input program. The possibilities are .c, .cm,
39 .mlb, .o, .S, and .sml.
40 With no arguments, MLton prints the version number and exits. For a
42 usage message, run MLton with an invalid switch, e.g. mlton -z. In
43 the explanation below and in the usage message, for flags that take a
44 number of choices (e.g. {true|false}), the first value listed is the
45 default.
46
49 -align {4|8}
50 Aligns object sizes and doubles in memory by the specified
51 alignment. The default varies depending on architecture.
52 -as-opt option
55 Pass option to gcc when assembling.
56 -cc-opt option
59 Pass option to gcc when compiling C code.
60 -codegen {native|x86|amd64|c|bytecode}
63 Generate native code, C code, or byte code. With -codegen
64 native (-codegen x86 or -codegen amd64), MLton typically com‐
65 piles more quickly and generates better code.
66 -const 'name value'
69 Set the value of a compile-time constant. Here is a list of
70 available constants, their default values, and what they con‐
71 trol.
72 Exn.keepHistory {false|true}
74 Enable MLton.Exn.history. There is a performance cost to
75 setting this to true, both in memory usage of exceptions
76 and in run time, because of additional work that must be
77 performed at each exception construction, raise, and han‐
78 dle.
79 -default-ann ann
82 Specify default ML Basis annotations. For example, -default-ann
83 'warnUnused true' causes unused variable warnings to be enabled
84 by default. Defaults may be overridden by an annotation in an
85 ML Basis file.
86 -default-type type
89 Specify the default binding for a primitive type. For example,
90 -default-type word64 causes the top-level type word and the top-
91 level structure Word in the Basis Library to be equal to
92 Word64.word and Word64:WORD, respectively. Similarly, -default-
93 type intinf causes the top-level type int and the top-level
94 structure Int in the Basis Library to be equal to IntInf.int and
95 IntInf:INTEGER, respectively.
96 -disable-ann ann
99 Ignore the specified ML Basis annotation in every ML Basis File.
100 For example, to see all match and unused warnings, compile with
101 -default-ann 'warnUnused true', -disable-ann forceUsed, -dis‐
102 able-ann nonexhaustiveMatch, -disable-ann redundantMatch, and
103 -disable-ann warnUnused.
104 -export-header file
107 Write C prototypes to file for all of the functions in the pro‐
108 gram exported from SML to C.
109 -ieee-fp {false|true}
112 Cause the x86 native code generator to be pedantic about follow‐
113 ing the IEEE floating point standard. By default, it is not,
114 because of the performance cost. This only has an effect with
115 -codegen x86.
116 -inline n
119 Set the inlining threshold used in the optimizer. The threshold
120 is an approximate measure of code size of a procedure. The
121 default is 320.
122 -keep {g|o|sml}
125 Save intermediate files. If no -keep argument is given, then
126 only the output file is saved.
127 g generated .S and .c files passed to gcc and the assem‐
128 bler
129 o object (.o) files
130 sml SML file
131 -link-opt option
134 Pass option to gcc when linking. You can use this to specify
135 library search paths, e.g. -link-opt -Lpath, and libraries to
136 link with, e.g. -link-opt -lfoo, or even both at the same time,
137 e.g. -link-opt '-Lpath -lfoo'. If you wish to pass an option to
138 the linker, you must use gcc's -Wl, syntax, e.g., -link-opt
139 '-Wl,--export-dynamic'.
140 -mlb-path-map file
143 Use file as an ML Basis path map to define additional MLB path
144 variables. Multiple uses of -mlb-path-map are allowed, with
145 variable definitions in later path maps taking precendence over
146 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 proces 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, follwed on subequent lines by the
210 position of each use.
211 -stop {f|g|o|sml|tc}
214 Specify when to stop.
215 f list of files on stdout (only makes sense when input
216 is foo.cm or foo.mlb)
217 g generated .S and .c files
218 o object (.o) files
219 sml SML file (only makes sense when input is foo.cm or
220 foo.mlb)
221 tc after type checking
222 If you compile -stop g or -stop o, you can resume compilation by
223 running MLton on the generated .c and .S or .o files.
224 -target {self|...}
227 Generate an executable that runs on the specified platform. The
228 default is self, which means to compile for the machine that
229 MLton is running on. To use any other target, you must first
230 install a cross compiler. See the MLton Guide for details.
231 -target-as-opt target option
234 Like -as-opt, this passes option to gcc when assembling, except
235 it only passes option when the target architecture or operating
236 system is target. Valid values for target are: amd64, hppa,
237 powerpc, sparc, x86, aix, cygwin, darwin, freebsd, hpuxP, linux,
238 mingw, netbsd, openbsd, solaris.
239 -target-cc-opt target option
242 Like -cc-opt, this passes option to gcc when compiling C code,
243 except it only passes option when the target architecture or
244 operating system is target. Valid values for target are as for
245 -target-as-opt.
246 -target-link-opt target option
249 Like -link-opt, this passes option to gcc when linking, except
250 it only passes option when the target architecture or operating
251 system is target. Valid values for target are as for -target-
252 as-opt.
253 -verbose {0|1|2|3}
256 How verbose to be about what passes are running. The default is
257 0.
258 0 silent
259 1 calls to compiler, assembler, and linker
260 2 1, plus intermediate compiler passes
261 3 2, plus some data structure sizes
262
265 Executables produced by MLton take command line arguments that control
266 the runtime system. These arguments are optional, and occur before the
267 executable's usual arguments. To use these options, the first argument
268 to the executable must be @MLton. The optional arguments then follow,
269 must be terminated by --, and are followed by any arguments to the pro‐
270 gram. The optional arguments are not made available to the SML program
271 via CommandLine.arguments. For example, a valid call to hello-world
272 is:
273 hello-world @MLton gc-summary fixed-heap 10k -- a b c
274 In the above example, CommandLine.arguments () = ["a", "b", "c"].
275 It is allowed to have a sequence of @MLton arguments, as in:
277 hello-world @MLton gc-summary -- @MLton fixed-heap 10k -- a b c
278 Run-time options can also control MLton, as in
280 mlton @MLton fixed-heap 0.5g -- foo.sml
281 fixed-heap x{k|K|m|M|g|G}
284 Use a fixed size heap of size x, where x is a real number and
285 the trailing letter indicates its units.
286 k or K 1024
287 m or M 1,048,576
288 g or G 1,073,741,824
289 A value of 0 means to use almost all the RAM present on the
290 machine.
291 The heap size used by fixed-heap includes all memory allocated
293 by SML code, including memory for the stack (or stacks, if there
294 are multiple threads). It does not, however, include any memory
295 used for code itself or memory used by C globals, the C stack,
296 or malloc.
297 gc-messages
300 Print a message at the start and end of every garbage collec‐
301 tion.
302 gc-summary
305 Print a summary of garbage collection statistics upon program
306 termination.
307 load-world world
310 Restart the computation with the file specified by world, which
311 must have been created by a call to MLton.World.save by the same
312 executable. See the MLton Guide for details.
313 max-heap x{k|K|m|M|g|G}
316 Run the computation with an automatically resized heap that is
317 never larger than x, where x is a real number and the trailing
318 letter indicates the units as with fixed-heap. The heap size
319 for max-heap is accounted for as with fixed-heap.
320 no-load-world
323 Disable load-world. This can be used as an argument to the com‐
324 piler via -runtime no-load-world to create executables that will
325 not load a world. This may be useful to ensure that set-uid
326 executables do not load some strange world.
327 ram-slop x
330 Multiply x by the amount of RAM on the machine to obtain what
331 the runtime views as the amount of RAM it can use. Typically x
332 is less than 1, and is used to account for space used by other
333 programs running on the same machine.
334 stop Causes the runtime to stop processing @MLton arguments once the
337 next -- is reached. This can be used as an argument to the com‐
338 piler via -runtime stop to create executables that don't process
339 any @MLton arguments.
340
343 MLton's type error messages are not in a form suitable for processing
344 by Emacs. For details on how to fix this, see http://mlton.org/Emacs.
345
348 mlprof(1) and the MLton Guide.
349 August 21, 2007 mlton(1)