4 Executables produced by MLton take command line arguments that control
5 the runtime system. These arguments are optional, and occur before
6 the executable's usual arguments. To use these options, the first
7 argument to the executable must be `@MLton`. The optional arguments
8 then follow, must be terminated by `--`, and are followed by any
9 arguments to the program. The optional arguments are _not_ made
10 available to the SML program via `CommandLine.arguments`. For
11 example, a valid call to `hello-world` is:
14 hello-world @MLton gc-summary fixed-heap 10k -- a b c
18 `CommandLine.arguments () = ["a", "b", "c"]`.
20 It is allowed to have a sequence of `@MLton` arguments, as in:
23 hello-world @MLton gc-summary -- @MLton fixed-heap 10k -- a b c
26 Run-time options can also control MLton, as in
29 mlton @MLton fixed-heap 0.5g -- foo.sml
35 * ++fixed-heap __x__{k|K|m|M|g|G}++
37 Use a fixed size heap of size _x_, where _x_ is a real number and the
38 trailing letter indicates its units.
43 | `m` or `M` | 1,048,576
44 | `g` or `G` | 1,073,741,824
47 A value of `0` means to use almost all the RAM present on the machine.
49 The heap size used by `fixed-heap` includes all memory allocated by
50 SML code, including memory for the stack (or stacks, if there are
51 multiple threads). It does not, however, include any memory used for
52 code itself or memory used by C globals, the C stack, or malloc.
56 Print a message at the start and end of every garbage collection.
60 Print a summary of garbage collection statistics upon program
61 termination to standard error.
63 * ++gc-summary-file __file__++
65 Print a summary of garbage collection statistics upon program
66 termination to the file specified by _file_.
68 * ++load-world __world__++
70 Restart the computation with the file specified by _world_, which must
71 have been created by a call to `MLton.World.save` by the same
72 executable. See <:MLtonWorld:>.
74 * ++max-heap __x__{k|K|m|M|g|G}++
76 Run the computation with an automatically resized heap that is never
77 larger than _x_, where _x_ is a real number and the trailing letter
78 indicates the units as with `fixed-heap`. The heap size for
79 `max-heap` is accounted for as with `fixed-heap`.
81 * ++may-page-heap {false|true}++
83 Enable paging the heap to disk when unable to grow the heap to a
88 Disable `load-world`. This can be used as an argument to the compiler
89 via `-runtime no-load-world` to create executables that will not load
90 a world. This may be useful to ensure that set-uid executables do not
91 load some strange world.
95 Multiply _x_ by the amount of RAM on the machine to obtain what the
96 runtime views as the amount of RAM it can use. Typically _x_ is less
97 than 1, and is used to account for space used by other programs
98 running on the same machine.
102 Causes the runtime to stop processing `@MLton` arguments once the next
103 `--` is reached. This can be used as an argument to the compiler via
104 `-runtime stop` to create executables that don't process any `@MLton`