Next Previous Contents

3. Manual page

3.1 Running MLton

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.

3.2 Compile-time options

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.

3.3 Compile-time options controlling intermediate files.

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).

3.4 Options controlling 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.

3.5 Compile-time options for experts

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

3.6 Runtime system options

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.


Next Previous Contents