MLton is run from the command line with a collection of options followed by a file name.
mlton [options] file.{sml|c|s|o}
The common case is no options with an input file foo.sml
,
in which case MLton produces an executable called
foo
that resides in the same directory as foo.sml
.
MLton's options allow you to control the name of the output file, the verbosity of compile-time messages, and the size of the heap used by the executable.
-h heapSize[km]
The resulting executable will use a fixed size heap of
heapSize
size. A value of 0 means that the heapSize
should be chosen almost as large as the amount of RAM in the machine.
A trailing k means that heapSize
is in units of 1024 bytes.
A trailing m means that heapSize
is in megabytes. If neither
appear, then heapSize
is in bytes. By default the executable
will use an automatically resized heap. This option only makes sense
when the input file suffix is .sml
-o file
Specify the output file. The default file name is the input file with the initial suffix removed and an appropriate one added.
-p
Produce an executable that will gather profiling information. The default is no profiling information. See section profiling for details.
-v
Be verbose about what passes are running. The default is to be
silent. With no other arguments, -v
prints out the version
number and terminates.
While compiling, MLton produces many intermediate files. These
options allow you to control which intermediate files are
saved as well as to stop the compilation process early, at some
intermediate pass. If you stop MLton at the production of C code
(-C
), assembly code (-S
), or an object file
(-c
), you can later resume the compilation process with that
intermediate file by passing it as an argument to MLton.
-c
Stop after producing object code (*.o).
-C
Stop after producing C code (*.c).
-d
Defunctorize (i.e. eliminate modules) the input and produce a core SML
program. This option only makes sense when the input file suffix is
.sml
-k{acso}*
If no -k argument is given, then only the final file is saved. Any of the letters appearing after the k cause the corresponding type of intermediate file to be preserved (a = MLton intermediate files, c = C file, s = assembler file, o = object file).
-S
Stop after producing assembler code (*.s).
gcc
-DDEFINE
Pass along -DDEFINE
to gcc. At present, three options are
recognized by MLton. If you compile with -DDETECT_OVERFLOW
,
then MLton will compile so that arithmetic overflow causes an error
message and the program to abort. If you compile with
-DINSTRUMENT
then various dynamic counts will be measured and
an informative message will be printed on program termination. If you
compile with -DGC_EVERY_CHECK
, then MLton will perform a
garbage collection at every limit check point. This is used for
debugging the garbage collector. All of these options have a
significant performance cost.
-g
Add debugging information for gdb. Link with a version of the runtime system that has asserts turned on (and runs about half as fast). The default is not to produce debugging information.
-iinclude
Specify an additional .h
file to be included in the
.c
file generated by MLton.
-Idir
Specify an additional directory to be searched for include files.
This switch is passed unchanged to gcc
.
-llib
Specify an additional library to link with.
This switch is passed unchanged to gcc
.
-Ldir
Specify an additional directory to be searched for libraries.
This switch is passed unchanged to gcc
.
-Odigit
Run gcc with optimization set to digit. The default is -O1
.
To turn off optimization, use -O0
. This is useful if the C
compiler takes too much time or memory with -O1
or
-O2
. Using -O0
will causes a significant
performance loss.
The following options are intended only for expert users and may change or disappear entirely in subsequent versions.
-flatten n
Set the number of rounds of the flattener to n. The default is 2.
-inline n
Specify the inlining threshold used in Cps simplifier. The default is 50.
-no-polyvariance
Turn off polyvariance. The default is for polyvariance to be on.
-no-type-check
Do not type check intermediate passes in MLton. This will make the
compiler run faster, but it will make it less likely to detect bugs in
MLton. The default is to type check. This option only makes sense
when the input file suffix is .sml
-unsafe
Produce unsafe C code. This eliminates overflow checks, bounds
checks, division for zero checks, and any other checks that depend on
the value of MLton.safe
. This changes the semantics of some
programs and does not conform to the basis library specification. The
default is to be safe. This option only makes sense when the input
file suffix is .sml
To control the runtime system, executables produced by MLton take
several optional command line arguments before their usual arguments.
To use these options, the first argument to the executable must be
"@MLton
". The optional arguments then follow, and must be
terminated by "--
" (before any of the program's arguments).
These optional arguments are not made available to the SML
program via CommandLine.arguments
. For example, a valid call
to hello-world
is:
hello-world @MLton gc-summary fixed-heap 10k --
These options can also be used to control the behavior of MLton by
passing them in the bin/mlton
script.
fixed-heap n[km]
Use a fixed size heap of n bytes. A trailing k means that n is in units of 1024 bytes. A trailing m means that n is in megabytes. If neither appear, then n is in bytes. A value of 0 means to use the maximum amount of RAM available.
gc-messages
Print out messages at the start and end of every garbage collection, as well as when resizing the stack.
gc-summary
Prints a summary of garbage collection statistics (including time spent in GC) upon program termination.
load-world world
Restart the computation with the file specified by world
.
The world file must have been created by a call to
MLton.saveWorld
by the same executable. See section
MLton for details.
max-heap n[km]
Run the computation with an automatically resized heap that is never
larger than n. The meaning of [km]
is the same as with the
fixed-heap
option.