Commit | Line | Data |
---|---|---|
7f918cf1 CE |
1 | CompileTimeOptions |
2 | ================== | |
3 | ||
4 | MLton's compile-time options control the name of the output file, the | |
5 | verbosity of compile-time messages, and whether or not certain | |
6 | optimizations are performed. They also can specify which intermediate | |
7 | files are saved and can stop the compilation process early, at some | |
8 | intermediate pass, in which case compilation can be resumed by passing | |
9 | the generated files to MLton. MLton uses the input file suffix to | |
10 | determine the type of input program. The possibilities are `.c`, | |
11 | `.mlb`, `.o`, `.s`, and `.sml`. | |
12 | ||
13 | With no arguments, MLton prints the version number and exits. For a | |
14 | usage message, run MLton with an invalid switch, e.g. `mlton -z`. In | |
15 | the explanation below and in the usage message, for flags that take a | |
16 | number of choices (e.g. `{true|false}`), the first value listed is the | |
17 | default. | |
18 | ||
19 | ||
20 | == Options == | |
21 | ||
22 | * ++-align __n__++ | |
23 | + | |
24 | Aligns object in memory by the specified alignment (+4+ or +8+). | |
25 | The default varies depending on architecture. | |
26 | ||
27 | * ++-as-opt __option__++ | |
28 | + | |
29 | Pass _option_ to `gcc` when compiling assembler code. If you wish to | |
30 | pass an option to the assembler, you must use `gcc`'s `-Wa,` syntax. | |
31 | ||
32 | * ++-cc-opt __option__++ | |
33 | + | |
34 | Pass _option_ to `gcc` when compiling C code. | |
35 | ||
36 | * ++-codegen {native|amd64|c|llvm|x86}++ | |
37 | + | |
38 | Generate native object code via amd64 assembly, C code, LLVM code, or | |
39 | x86 code or C code. With `-codegen native` (`-codegen amd64` or | |
40 | `-codegen x86`), MLton typically compiles more quickly and generates | |
41 | better code. | |
42 | ||
43 | * ++-const __name__ __value__++ | |
44 | + | |
45 | Set the value of a compile-time constant. Here is a list of | |
46 | available constants, their default values, and what they control. | |
47 | + | |
48 | ** ++Exn.keepHistory {false|true}++ | |
49 | + | |
50 | Enable `MLton.Exn.history`. See <:MLtonExn:> for details. There is a | |
51 | performance cost to setting this to `true`, both in memory usage of | |
52 | exceptions and in run time, because of additional work that must be | |
53 | performed at each exception construction, raise, and handle. | |
54 | ||
55 | * ++-default-ann __ann__++ | |
56 | + | |
57 | Specify default <:MLBasisAnnotations:ML Basis annotations>. For | |
58 | example, `-default-ann 'warnUnused true'` causes unused variable | |
59 | warnings to be enabled by default. A default is overridden by the | |
60 | corresponding annotation in an ML Basis file. | |
61 | ||
62 | * ++-default-type __type__++ | |
63 | + | |
64 | Specify the default binding for a primitive type. For example, | |
65 | `-default-type word64` causes the top-level type `word` and the | |
66 | top-level structure `Word` in the <:BasisLibrary:Basis Library> to be | |
67 | equal to `Word64.word` and `Word64:WORD`, respectively. Similarly, | |
68 | `-default-type intinf` causes the top-level type `int` and the | |
69 | top-level structure `Int` in the <:BasisLibrary:Basis Library> to be | |
70 | equal to `IntInf.int` and `IntInf:INTEGER`, respectively. | |
71 | ||
72 | * ++-disable-ann __ann__++ | |
73 | + | |
74 | Ignore the specified <:MLBasisAnnotations:ML Basis annotation> in | |
75 | every ML Basis file. For example, to see _all_ match and unused | |
76 | warnings, compile with | |
77 | + | |
78 | ---- | |
79 | -default-ann 'warnUnused true' | |
80 | -disable-ann forceUsed | |
81 | -disable-ann nonexhaustiveMatch | |
82 | -disable-ann redundantMatch | |
83 | -disable-ann warnUnused | |
84 | ---- | |
85 | ||
86 | * ++-export-header __file__++ | |
87 | + | |
88 | Write C prototypes to _file_ for all of the functions in the program | |
89 | <:CallingFromCToSML:exported from SML to C>. | |
90 | ||
91 | * ++-ieee-fp {false|true}++ | |
92 | + | |
93 | Cause the x86 native code generator to be pedantic about following the | |
94 | IEEE floating point standard. By default, it is not, because of the | |
95 | performance cost. This only has an effect with `-codegen x86`. | |
96 | ||
97 | * ++-inline __n__++ | |
98 | + | |
99 | Set the inlining threshold used in the optimizer. The threshold is an | |
100 | approximate measure of code size of a procedure. The default is | |
101 | `320`. | |
102 | ||
103 | * ++-keep {g|o}++ | |
104 | + | |
105 | Save intermediate files. If no `-keep` argument is given, then only | |
106 | the output file is saved. | |
107 | + | |
108 | [cols="^25%,<75%"] | |
109 | |==== | |
110 | | `g` | generated `.c` and `.s` files passed to `gcc` and generated `.ll` files passed to `llvm-as` | |
111 | | `o` | object (`.o`) files | |
112 | |==== | |
113 | ||
114 | * ++-link-opt __option__++ | |
115 | + | |
116 | Pass _option_ to `gcc` when linking. You can use this to specify | |
117 | library search paths, e.g. `-link-opt -Lpath`, and libraries to link | |
118 | with, e.g., `-link-opt -lfoo`, or even both at the same time, | |
119 | e.g. `-link-opt '-Lpath -lfoo'`. If you wish to pass an option to the | |
120 | linker, you must use `gcc`'s `-Wl,` syntax, e.g., | |
121 | `-link-opt '-Wl,--export-dynamic'`. | |
122 | ||
123 | * ++-llvm-as-opt __option__++ | |
124 | + | |
125 | Pass _option_ to `llvm-as` when assembling (`.ll` to `.bc`) LLVM code. | |
126 | ||
127 | * ++-llvm-llc-opt __option__++ | |
128 | + | |
129 | Pass _option_ to `llc` when compiling (`.bc` to `.o`) LLVM code. | |
130 | ||
131 | * ++-llvm-opt-opt __option__++ | |
132 | + | |
133 | Pass _option_ to `opt` when optimizing (`.bc` to `.bc`) LLVM code. | |
134 | ||
135 | * ++-mlb-path-map __file__++ | |
136 | + | |
137 | Use _file_ as an <:MLBasisPathMap:ML Basis path map> to define | |
138 | additional MLB path variables. Multiple uses of `-mlb-path-map` and | |
139 | `-mlb-path-var` are allowed, with variable definitions in later path | |
140 | maps taking precedence over earlier ones. | |
141 | ||
142 | * ++-mlb-path-var __name__ __value__++ | |
143 | + | |
144 | Define an additional MLB path variable. Multiple uses of | |
145 | `-mlb-path-map` and `-mlb-path-var` are allowed, with variable | |
146 | definitions in later path maps taking precedence over earlier ones. | |
147 | ||
148 | * ++-output __file__++ | |
149 | + | |
150 | Specify the name of the final output file. The default name is the | |
151 | input file name with its suffix removed and an appropriate, possibly | |
152 | empty, suffix added. | |
153 | ||
154 | * ++-profile {no|alloc|count|time}++ | |
155 | + | |
156 | Produce an executable that gathers <:Profiling: profiling> data. When | |
157 | such an executable is run, it produces an `mlmon.out` file. | |
158 | ||
159 | * ++-profile-branch {false|true}++ | |
160 | + | |
161 | If true, the profiler will separately gather profiling data for each | |
162 | branch of a function definition, `case` expression, and `if` | |
163 | expression. | |
164 | ||
165 | * ++-profile-stack {false|true}++ | |
166 | + | |
167 | If `true`, the executable will gather profiling data for all functions | |
168 | on the stack, not just the currently executing function. See | |
169 | <:ProfilingTheStack:>. | |
170 | ||
171 | * ++-profile-val {false|true}++ | |
172 | + | |
173 | If `true`, the profiler will separately gather profiling data for each | |
174 | (expansive) `val` declaration. | |
175 | ||
176 | * ++-runtime __arg__++ | |
177 | + | |
178 | Pass argument to the runtime system via `@MLton`. See | |
179 | <:RunTimeOptions:>. The argument will be processed before other | |
180 | `@MLton` command line switches. Multiple uses of `-runtime` are | |
181 | allowed, and will pass all the arguments in order. If the same | |
182 | runtime switch occurs more than once, then the last setting will take | |
183 | effect. There is no need to supply the leading `@MLton` or the | |
184 | trailing `--`; these will be supplied automatically. | |
185 | + | |
186 | An argument to `-runtime` may contain spaces, which will cause the | |
187 | argument to be treated as a sequence of words by the runtime. For | |
188 | example the command line: | |
189 | + | |
190 | ---- | |
191 | mlton -runtime 'ram-slop 0.4' foo.sml | |
192 | ---- | |
193 | + | |
194 | will cause `foo` to run as if it had been called like: | |
195 | + | |
196 | ---- | |
197 | foo @MLton ram-slop 0.4 -- | |
198 | ---- | |
199 | + | |
200 | An executable created with `-runtime stop` doesn't process any | |
201 | `@MLton` arguments. This is useful to create an executable, e.g., | |
202 | `echo`, that must treat `@MLton` like any other command-line argument. | |
203 | + | |
204 | ---- | |
205 | % mlton -runtime stop echo.sml | |
206 | % echo @MLton -- | |
207 | @MLton -- | |
208 | ---- | |
209 | ||
210 | * ++-show-basis __file__++ | |
211 | + | |
212 | Pretty print to _file_ the basis defined by the input program. See | |
213 | <:ShowBasis:>. | |
214 | ||
215 | * ++-show-def-use __file__++ | |
216 | + | |
217 | Output def-use information to _file_. Each identifier that is defined | |
218 | appears on a line, followed on subsequent lines by the position of | |
219 | each use. | |
220 | ||
221 | * ++-stop {f|g|o|tc}++ | |
222 | + | |
223 | Specify when to stop. | |
224 | + | |
225 | [cols="^25%,<75%"] | |
226 | |==== | |
227 | | `f` | list of files on stdout (only makes sense when input is `foo.mlb`) | |
228 | | `g` | generated `.c` and `.s` files | |
229 | | `o` | object (`.o`) files | |
230 | | `tc` | after type checking | |
231 | |==== | |
232 | + | |
233 | If you compile with `-stop g` or `-stop o`, you can resume compilation | |
234 | by running MLton on the generated `.c` and `.s` or `.o` files. | |
235 | ||
236 | * ++-target {self|__...__}++ | |
237 | + | |
238 | Generate an executable that runs on the specified platform. The | |
239 | default is `self`, which means to compile for the machine that MLton | |
240 | is running on. To use any other target, you must first install a | |
241 | <:CrossCompiling: cross compiler>. | |
242 | ||
243 | * ++-target-as-opt __target__ __option__++ | |
244 | + | |
245 | Like `-as-opt`, this passes _option_ to `gcc` when compliling | |
246 | assembler code, except it only passes _option_ when the target | |
247 | architecture, operating system, or arch-os pair is _target_. | |
248 | ||
249 | * ++-target-cc-opt __target__ __option__++ | |
250 | + | |
251 | Like `-cc-opt`, this passes _option_ to `gcc` when compiling C code, | |
252 | except it only passes _option_ when the target architecture, operating | |
253 | system, or arch-os pair is _target_. | |
254 | ||
255 | * ++-target-link-opt __target__ __option__++ | |
256 | + | |
257 | Like `-link-opt`, this passes _option_ to `gcc` when linking, except | |
258 | it only passes _option_ when the target architecture, operating | |
259 | system, or arch-os pair is _target_. | |
260 | ||
261 | * ++-verbose {0|1|2|3}++ | |
262 | + | |
263 | How verbose to be about what passes are running. The default is `0`. | |
264 | + | |
265 | [cols="^25%,<75%"] | |
266 | |==== | |
267 | | `0` | silent | |
268 | | `1` | calls to compiler, assembler, and linker | |
269 | | `2` | 1, plus intermediate compiler passes | |
270 | | `3` | 2, plus some data structure sizes | |
271 | |==== |