Commit | Line | Data |
---|---|---|
7f918cf1 CE |
1 | RunTimeOptions |
2 | ============== | |
3 | ||
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: | |
12 | ||
13 | ---- | |
14 | hello-world @MLton gc-summary fixed-heap 10k -- a b c | |
15 | ---- | |
16 | ||
17 | In the above example, | |
18 | `CommandLine.arguments () = ["a", "b", "c"]`. | |
19 | ||
20 | It is allowed to have a sequence of `@MLton` arguments, as in: | |
21 | ||
22 | ---- | |
23 | hello-world @MLton gc-summary -- @MLton fixed-heap 10k -- a b c | |
24 | ---- | |
25 | ||
26 | Run-time options can also control MLton, as in | |
27 | ||
28 | ---- | |
29 | mlton @MLton fixed-heap 0.5g -- foo.sml | |
30 | ---- | |
31 | ||
32 | ||
33 | == Options == | |
34 | ||
35 | * ++fixed-heap __x__{k|K|m|M|g|G}++ | |
36 | + | |
37 | Use a fixed size heap of size _x_, where _x_ is a real number and the | |
38 | trailing letter indicates its units. | |
39 | + | |
40 | [cols="^25%,<75%"] | |
41 | |==== | |
42 | | `k` or `K` | 1024 | |
43 | | `m` or `M` | 1,048,576 | |
44 | | `g` or `G` | 1,073,741,824 | |
45 | |==== | |
46 | + | |
47 | A value of `0` means to use almost all the RAM present on the machine. | |
48 | + | |
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. | |
53 | ||
54 | * ++gc-messages++ | |
55 | + | |
56 | Print a message at the start and end of every garbage collection. | |
57 | ||
58 | * ++gc-summary++ | |
59 | + | |
60 | Print a summary of garbage collection statistics upon program | |
61 | termination to standard error. | |
62 | ||
63 | * ++gc-summary-file __file__++ | |
64 | + | |
65 | Print a summary of garbage collection statistics upon program | |
66 | termination to the file specified by _file_. | |
67 | ||
68 | * ++load-world __world__++ | |
69 | + | |
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:>. | |
73 | ||
74 | * ++max-heap __x__{k|K|m|M|g|G}++ | |
75 | + | |
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`. | |
80 | ||
81 | * ++may-page-heap {false|true}++ | |
82 | + | |
83 | Enable paging the heap to disk when unable to grow the heap to a | |
84 | desired size. | |
85 | ||
86 | * ++no-load-world++ | |
87 | + | |
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. | |
92 | ||
93 | * ++ram-slop __x__++ | |
94 | + | |
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. | |
99 | ||
100 | * ++stop++ | |
101 | + | |
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` | |
105 | arguments. |