| 1 | .TH mlton 1 "February 6, 2018" |
| 2 | .SH NAME |
| 3 | \fBmlton\fP \- whole-program compiler for the Standard ML (SML) programming |
| 4 | language |
| 5 | .SH SYNOPSIS |
| 6 | \fBmlton\fP \fI[option ...] file\fB.\fP{\fBc\fP|\fBmlb\fP|\fBo\fP|\fBsml\fP} [file\fB.\fP{\fBc\fP|\fBo\fP|\fBs\fP|\fBS\fP} ...]\fR |
| 7 | .SH DESCRIPTION |
| 8 | .PP |
| 9 | \fBMLton\fP is run from the command line with a collection of options |
| 10 | followed by a file name and a list of files with which to compile, assemble, and |
| 11 | link with. The simplest case is to run \fBmlton foo.sml\fP, where |
| 12 | \fBfoo.sml\fP contains a valid SML program, in which case MLton |
| 13 | compiles the program to produce an executable \fBfoo\fP. Since |
| 14 | \fBMLton\fP does not support separate compilation, the program must be |
| 15 | the entire program you wish to compile. However, the program may |
| 16 | refer to signatures and structures defined in the Basis Library. |
| 17 | |
| 18 | Larger programs, spanning many files, may be compiled with the ML |
| 19 | Basis system. In this case, \fBmlton foo.mlb\fP will compile |
| 20 | the complete SML program described by the basis \fBfoo.mlb\fP, which |
| 21 | may specify both SML files and additional bases. See the \fBMLton |
| 22 | Guide\fP for details. |
| 23 | |
| 24 | \fBMLton\fP's compile-time options control the name of the output |
| 25 | file, the verbosity of compile-time messages, and whether or not |
| 26 | certain optimizations are performed. They also can specify |
| 27 | which intermediate files are saved and can stop the compilation process |
| 28 | early, at some intermediate pass, in which case compilation can be |
| 29 | resumed by passing the generated files to \fBMLton\fP. \fBMLton\fP |
| 30 | uses the input file suffix to determine the type of input program. |
| 31 | The possibilities are \fB.c\fP, \fB.mlb\fP, \fB.o\fP, \fB.s\fP, and \fB.sml\fP. |
| 32 | |
| 33 | With no arguments, \fBMLton\fP prints the version number and exits. |
| 34 | For a usage message, run \fBMLton\fP with an invalid switch, e.g. |
| 35 | \fBmlton \-z\fP. In the explanation below and in the usage message, |
| 36 | for flags that take a number of choices |
| 37 | (e.g. \fI{\fBtrue\fP|\fBfalse\fP}\fR), the first value listed is the |
| 38 | default. |
| 39 | |
| 40 | .SH Compile-time options |
| 41 | .TP |
| 42 | \fB\-align \fIn\fP\fR |
| 43 | Aligns objects in memory by the specified alignment (\fB4\fP or \fB8\fP). |
| 44 | The default varies depending on architecture. |
| 45 | |
| 46 | .TP |
| 47 | \fB\-as\-opt \fIoption\fP\fR |
| 48 | Pass \fIoption\fP to \fBgcc\fP when compiling assembler code. If you |
| 49 | wish to pass an option to the assembler, you must use \fBgcc\fP's |
| 50 | \fB\-Wa,\fP syntax. |
| 51 | |
| 52 | .TP |
| 53 | \fB\-cc\-opt \fIoption\fP\fR |
| 54 | Pass \fIoption\fP to \fBgcc\fP when compiling C code. |
| 55 | |
| 56 | .TP |
| 57 | \fB\-codegen \fI{\fBnative\fP|\fBx86\fP|\fBamd64\fP|\fBc\fP|\fBllvm\fP}\fP\fR |
| 58 | Generate native object code via amd64 assembly, C code, LLVM code, or |
| 59 | x86 assembly. With \fB\-codegen native\fP (\fB\-codegen amd64\fP or |
| 60 | \fB\-codegen x86\fP), \fBMLton\fP typically compiles more quickly and |
| 61 | generates better code. |
| 62 | |
| 63 | .TP |
| 64 | \fB\-const '\fIname value\fP'\fR |
| 65 | Set the value of a compile-time constant. Here is a list of available |
| 66 | constants, their default values, and what they control. |
| 67 | |
| 68 | \fBExn.keepHistory \fI{\fBfalse\fP|\fBtrue\fP}\fP\fR |
| 69 | .in +.5i |
| 70 | Enable \fBMLton.Exn.history\fP. There is a performance cost to setting this |
| 71 | to \fBtrue\fP, both in memory usage of exceptions and in run time, |
| 72 | because of additional work that must be performed at each exception |
| 73 | construction, raise, and handle. |
| 74 | .in -.5i |
| 75 | |
| 76 | .TP |
| 77 | \fB\-default\-ann \fIann\fP\fR |
| 78 | Specify default ML Basis annotations. For |
| 79 | example, \fB\-default\-ann 'warnUnused true'\fP |
| 80 | causes unused variable warnings to be enabled by default. |
| 81 | Defaults may be overridden by an annotation in an ML Basis file. |
| 82 | |
| 83 | .TP |
| 84 | \fB\-default\-type \fItype\fP\fR |
| 85 | Specify the default binding for a primitive type. For example, |
| 86 | \fB\-default\-type word64\fP causes the top-level type \fBword\fP and |
| 87 | the top-level structure \fBWord\fP in the Basis Library to be equal to |
| 88 | \fBWord64.word\fP and \fBWord64:WORD\fP, respectively. Similarly, |
| 89 | \fB\-default\-type intinf\fP causes the top-level type \fBint\fP and |
| 90 | the top-level structure \fBInt\fP in the Basis Library to be equal to |
| 91 | \fBIntInf.int\fP and \fBIntInf:INTEGER\fP, respectively. |
| 92 | |
| 93 | .TP |
| 94 | \fB\-disable\-ann \fIann\fP\fR |
| 95 | Ignore the specified ML Basis annotation in every ML Basis File. For example, |
| 96 | to see \fIall\fP match and unused warnings, compile with |
| 97 | \fB\-default\-ann 'warnUnused true'\fP, |
| 98 | \fB\-disable\-ann forceUsed\fP, |
| 99 | \fB\-disable\-ann nonexhaustiveMatch\fP, |
| 100 | \fB\-disable\-ann redundantMatch\fP, |
| 101 | and \fB\-disable\-ann warnUnused\fP. |
| 102 | |
| 103 | .TP |
| 104 | \fB\-export\-header \fIfile\fP\fR |
| 105 | Write C prototypes to \fIfile\fP for all of the functions in the |
| 106 | program exported from SML to C. |
| 107 | |
| 108 | .TP |
| 109 | \fB\-ieee\-fp \fI{\fBfalse\fP|\fBtrue\fP}\fP\fR |
| 110 | Cause the x86 native code generator to be pedantic about following the IEEE |
| 111 | floating point standard. By default, it is not, because of the |
| 112 | performance cost. This only has an effect with \fB\-codegen x86\fP. |
| 113 | |
| 114 | .TP |
| 115 | \fB\-inline \fIn\fP\fR |
| 116 | Set the inlining threshold used in the optimizer. The threshold is an |
| 117 | approximate measure of code size of a procedure. The default is 320. |
| 118 | |
| 119 | .TP |
| 120 | \fB\-keep \fI{\fBg\fP|\fBo\fP}\fP\fR |
| 121 | Save intermediate files. If no \fB\-keep\fP argument is given, then |
| 122 | only the output file is saved. |
| 123 | .in +.5i |
| 124 | \fBg\fP generated \fB.c\fP and \fB.s\fP files passed to \fBgcc\fP and generated \fB.ll\fP files passed to \fBllvm-as\fP |
| 125 | .br |
| 126 | \fBo\fP object (\fB.o\fP) files |
| 127 | .in -.5i |
| 128 | |
| 129 | .TP |
| 130 | \fB\-llvm\-as\-opt \fIoption\fP\fR |
| 131 | Pass \fIoption\fP to \fBllvm-as\fP when assembling (\fB.ll\fP to \fB.bc\fP) LLVM code. |
| 132 | |
| 133 | .TP |
| 134 | \fB\-llvm\-llc\-opt \fIoption\fP\fR |
| 135 | Pass \fIoption\fP to \fBllc\fP when compiling (\fB.bc\fP to \fB.o\fP) LLVM code. |
| 136 | |
| 137 | .TP |
| 138 | \fB\-llvm\-opt\-opt \fIoption\fP\fR |
| 139 | Pass \fIoption\fP to \fBopt\fP when optimizing (\fB.bc\fP to \fB.bc\fP) LLVM code. |
| 140 | |
| 141 | .TP |
| 142 | \fB\-link\-opt \fIoption\fP\fR |
| 143 | Pass \fIoption\fP to \fBgcc\fP when linking. You can use this to |
| 144 | specify library search paths, e.g. \fB\-link\-opt \-Lpath\fP, and |
| 145 | libraries to link with, e.g. \fB\-link\-opt \-lfoo\fP, or even both at |
| 146 | the same time, e.g. \fB\-link\-opt '\-Lpath \-lfoo'\fP. If you wish to |
| 147 | pass an option to the linker, you must use \fBgcc\fP's \fB\-Wl,\fP |
| 148 | syntax, e.g., \fB\-link\-opt '\-Wl,\-\-export\-dynamic'\fP. |
| 149 | |
| 150 | .TP |
| 151 | \fB\-mlb\-path\-map \fIfile\fP\fR |
| 152 | Use \fIfile\fP as an ML Basis path map to define additional MLB path variables. |
| 153 | Multiple uses of \fB\-mlb\-path\-map\fP and \fB\-mlb\-path\-var\fP are |
| 154 | allowed, with variable definitions in later path maps taking |
| 155 | precedence over earlier ones. |
| 156 | |
| 157 | .TP |
| 158 | \fB\-mlb\-path\-var '\fIname value\fP'\fR |
| 159 | Define an additional MLB path variable. |
| 160 | Multiple uses of \fB\-mlb\-path\-map\fP and \fB\-mlb\-path\-var\fP are |
| 161 | allowed, with variable definitions in later path maps taking |
| 162 | precedence over earlier ones. |
| 163 | |
| 164 | .TP |
| 165 | \fB\-output \fIfile\fP\fR |
| 166 | Specify the name of the final output file. |
| 167 | The default name is the input file name with its suffix removed and an |
| 168 | appropriate, possibly empty, suffix added. |
| 169 | |
| 170 | .TP |
| 171 | \fB\-profile \fI{\fBno\fP|\fBalloc\fP|\fBcount\fP|\fBtime\fP}\fP\fR |
| 172 | Produce an executable that gathers profiling data. When |
| 173 | such an executable is run, it will produce an \fBmlmon.out\fP file. |
| 174 | The man page on \fBmlprof\fP describes how to extract information from |
| 175 | this file. |
| 176 | |
| 177 | .TP |
| 178 | \fB\-profile\-branch \fI{\fBfalse\fP|\fBtrue\fP}\fP\fR |
| 179 | If true, the profiler will separately gather profiling data |
| 180 | for each branch of a function definition, \fBcase\fP |
| 181 | expression, and \fBif\fP expression. |
| 182 | |
| 183 | .TP |
| 184 | \fB\-profile\-stack \fI{\fBfalse\fP|\fBtrue\fP}\fP\fR |
| 185 | If true, the profiler will gather profiling data for all |
| 186 | functions on the stack, not just the currently executing function. |
| 187 | |
| 188 | .TP |
| 189 | \fB\-profile\-val \fI{\fBfalse\fP|\fBtrue\fP}\fP\fR |
| 190 | If true, the profiler will separately gather profiling data |
| 191 | for each (expansive) \fBval\fP declaration. |
| 192 | |
| 193 | .TP |
| 194 | \fB\-runtime \fIarg\fP\fR |
| 195 | Pass argument to the runtime system via \fB@MLton\fP. The argument |
| 196 | will be processed before other \fB@MLton\fP command line switches. |
| 197 | Multiple uses of \fB\-runtime\fP are allowed, and will pass all the |
| 198 | arguments in order. If the same runtime switch occurs more than once, |
| 199 | then the last setting will take effect. There is no need to supply the |
| 200 | leading \fB@MLton\fP or the trailing \fB\-\-\fP; these will be |
| 201 | supplied automatically. |
| 202 | |
| 203 | An argument to \fB\-runtime\fP may contain spaces, which will cause the |
| 204 | argument to be treated as a sequence of words by the runtime. For |
| 205 | example, the command line: |
| 206 | .in +.5i |
| 207 | \fBmlton \-runtime 'ram\-slop 0.4' foo.sml\fP |
| 208 | .in -.5i |
| 209 | will cause foo to run as if it had been called like |
| 210 | .in +.5i |
| 211 | \fBfoo @MLton ram\-slop 0.4 \-\-\fP |
| 212 | .in -.5i |
| 213 | |
| 214 | An executable created with \fB\-runtime stop\fP doesn't process any |
| 215 | \fB@MLton\fP arguments. This is useful to create an executable, |
| 216 | e.g. \fBecho\fP, that must treat \fB@MLton\fP like any other |
| 217 | command-line argument. |
| 218 | .in +.5i |
| 219 | \fB% mlton \-runtime stop echo.sml\fP |
| 220 | .in -.5i |
| 221 | .in +.5i |
| 222 | \fB% echo @MLton \-\-\fP |
| 223 | .in -.5i |
| 224 | .in +.5i |
| 225 | \fB@MLton \-\-\fP |
| 226 | .in -.5i |
| 227 | |
| 228 | .TP |
| 229 | \fB\-show\-basis \fIfile\fP\fR |
| 230 | Pretty print to \fIfile\fP the basis defined by the input program. |
| 231 | |
| 232 | .TP |
| 233 | \fB\-show\-def\-use \fIfile\fP\fR |
| 234 | Output def-use information to \fIfile\fP. Each identifier that is |
| 235 | defined appears on a line, followed on subsequent lines by the position |
| 236 | of each use. |
| 237 | |
| 238 | .TP |
| 239 | \fB\-stop \fI{\fBf\fP|\fBg\fP|\fBo\fP|\fBtc\fP}\fP\fR |
| 240 | Specify when to stop. |
| 241 | .in +.5i |
| 242 | \fBf\fP list of files on stdout (only makes sense when input is \fBfoo.mlb\fP) |
| 243 | .br |
| 244 | \fBg\fP generated \fB.c\fP and \fB.s\fP files |
| 245 | .br |
| 246 | \fBo\fP object (\fB.o\fP) files |
| 247 | .br |
| 248 | \fBtc\fP after type checking |
| 249 | .in -.5i |
| 250 | If you compile \fB\-stop g\fP or \fB\-stop o\fP, you can resume |
| 251 | compilation by running \fBMLton\fP on the generated \fB.c\fP and \fB.s\fP |
| 252 | or \fB.o\fP files. |
| 253 | |
| 254 | .TP |
| 255 | \fB\-target \fI{\fBself\fP|...}\fP\fR |
| 256 | Generate an executable that runs on the specified platform. The |
| 257 | default is \fBself\fP, which means to compile for the machine that |
| 258 | \fBMLton\fP is running on. To use any other target, you must first |
| 259 | install a cross compiler. See the \fBMLton Guide\fP for |
| 260 | details. |
| 261 | |
| 262 | .TP |
| 263 | \fB\-target\-as\-opt \fItarget\fP \fIoption\fP\fR |
| 264 | Like \fB\-as\-opt\fP, this passes \fIoption\fP to \fBgcc\fP when assembling, |
| 265 | except it only passes \fIoption\fP when the target architecture or |
| 266 | operating system is \fItarget\fP. |
| 267 | |
| 268 | .TP |
| 269 | \fB\-target\-cc\-opt \fItarget\fP \fIoption\fP\fR |
| 270 | Like \fB\-cc\-opt\fP, this passes \fIoption\fP to \fBgcc\fP when compiling |
| 271 | C code, except it only passes \fIoption\fP when the target architecture |
| 272 | or operating system is \fItarget\fP. |
| 273 | |
| 274 | .TP |
| 275 | \fB\-target\-link\-opt \fItarget\fP \fIoption\fP\fR |
| 276 | Like \fB\-link\-opt\fP, this passes \fIoption\fP to \fBgcc\fP when linking, |
| 277 | except it only passes \fIoption\fP when the target architecture or |
| 278 | operating system is \fItarget\fP. |
| 279 | |
| 280 | .TP |
| 281 | \fB\-verbose \fI{\fB0\fP|\fB1\fP|\fB2\fP|\fB3\fP}\fP\fR |
| 282 | How verbose to be about what passes are running. The default is 0. |
| 283 | .in +.5i |
| 284 | \fB0\fP silent |
| 285 | .br |
| 286 | \fB1\fP calls to compiler, assembler, and linker |
| 287 | .br |
| 288 | \fB2\fP 1, plus intermediate compiler passes |
| 289 | .br |
| 290 | \fB3\fP 2, plus some data structure sizes |
| 291 | .in -.5i |
| 292 | |
| 293 | .SH Runtime system options |
| 294 | Executables produced by \fBMLton\fP take command line arguments that control |
| 295 | the runtime system. These arguments are optional, and occur before |
| 296 | the executable's usual arguments. To use these options, the first |
| 297 | argument to the executable must be \fB@MLton\fP. The optional |
| 298 | arguments then follow, must be terminated by \fB\-\-\fP, and are |
| 299 | followed by any arguments to the program. The optional arguments are |
| 300 | \fInot\fP made available to the SML program via |
| 301 | \fBCommandLine.arguments\fP. For example, a valid call to |
| 302 | \fBhello-world\fP is: |
| 303 | .in +.5i |
| 304 | \fBhello-world @MLton gc\-summary fixed\-heap 10k \-\- a b c\fP |
| 305 | .in -.5i |
| 306 | In the above example, |
| 307 | \fBCommandLine.arguments () = ["a", "b", "c"]\fP. |
| 308 | |
| 309 | It is allowed to have a sequence of \fB@MLton\fP arguments, as in: |
| 310 | .in +.5i |
| 311 | \fBhello-world @MLton gc\-summary \-\- @MLton fixed\-heap 10k \-\- a b c\fP |
| 312 | .in -.5i |
| 313 | |
| 314 | Run-time options can also control \fBMLton\fP, as in |
| 315 | .in +.5i |
| 316 | \fBmlton @MLton fixed\-heap 0.5g \-\- foo.sml\fP |
| 317 | .in -.5i |
| 318 | |
| 319 | .TP |
| 320 | \fBfixed\-heap \fIx{\fBk\fP|\fBK\fP|\fBm\fP|\fBM\fP|\fBg\fP|\fBG\fP}\fP\fR |
| 321 | Use a fixed size heap of size \fIx\fP, where \fIx\fP is a real number |
| 322 | and the trailing letter indicates its units. |
| 323 | .in +.5i |
| 324 | \fBk\fP or \fBK\fP 1024 |
| 325 | .br |
| 326 | \fPm\fP or \fBM\fP 1,048,576 |
| 327 | .br |
| 328 | \fBg\fP or \fBG\fP 1,073,741,824 |
| 329 | .in -.5i |
| 330 | A value of \fB0\fP means to use almost all the RAM present on the machine. |
| 331 | |
| 332 | The heap size used by \fBfixed\-heap\fP includes all memory |
| 333 | allocated by SML code, including memory for the stack (or stacks, |
| 334 | if there are multiple threads). It does not, however, include any |
| 335 | memory used for code itself or memory used by C globals, the C |
| 336 | stack, or malloc. |
| 337 | |
| 338 | .TP |
| 339 | \fBgc\-messages\fP |
| 340 | Print a message at the start and end of every garbage collection. |
| 341 | |
| 342 | .TP |
| 343 | \fBgc\-summary\fP |
| 344 | Print a summary of garbage collection statistics upon program |
| 345 | termination. |
| 346 | |
| 347 | .TP |
| 348 | \fBgc\-summary\-file \fIfile\fP\fP |
| 349 | Print a summary of garbage collection statistics upon program |
| 350 | termination to the file specified by \fIfile\fP. |
| 351 | |
| 352 | .TP |
| 353 | \fBload\-world \fIworld\fP\fR |
| 354 | Restart the computation with the file specified by \fIworld\fP, which must have |
| 355 | been created by a call to \fBMLton.World.save\fP by the same |
| 356 | executable. See the \fBMLton Guide\fP for details. |
| 357 | |
| 358 | .TP |
| 359 | \fBmax\-heap \fIx{\fBk\fP|\fBK\fP|\fBm\fP|\fBM\fP|\fBg\fP|\fBG\fP}\fP\fR |
| 360 | Run the computation with an automatically resized heap that is never |
| 361 | larger than \fIx\fP, where \fIx\fP is a real number and the trailing |
| 362 | letter indicates the units as with \fBfixed\-heap\fP. The |
| 363 | heap size for \fBmax\-heap\fP is accounted for as with |
| 364 | \fBfixed\-heap\fP. |
| 365 | |
| 366 | .TP |
| 367 | \fBmay\-page\-heap \fI{\fBfalse\fP|\fBtrue\fP}\fP\fR |
| 368 | Enable paging the heap to disk when unable to grow the heap to a |
| 369 | desired size. |
| 370 | |
| 371 | .TP |
| 372 | \fBno\-load\-world\fP |
| 373 | Disable \fBload\-world\fP. This can be used as an argument to the |
| 374 | compiler via \fB\-runtime no\-load\-world\fP to create executables that |
| 375 | will not load a world. This may be useful to ensure that set-uid |
| 376 | executables do not load some strange world. |
| 377 | |
| 378 | .TP |
| 379 | \fBram\-slop \fIx\fP\fR |
| 380 | Multiply \fBx\fP by the amount of RAM on the machine to obtain what |
| 381 | the runtime views as the amount of RAM it can use. Typically \fBx\fP |
| 382 | is less than 1, and is used to account for space used by other |
| 383 | programs running on the same machine. |
| 384 | |
| 385 | .TP |
| 386 | \fBstop\fP |
| 387 | Causes the runtime to stop processing \fB@MLton\fP arguments once the |
| 388 | next \fB\-\-\fP is reached. This can be used as an argument to the |
| 389 | compiler via \fB\-runtime stop\fP to create executables that don't |
| 390 | process any \fB@MLton\fP arguments. |
| 391 | |
| 392 | .SH DIAGNOSTICS |
| 393 | MLton's type error messages are not in a form suitable for processing |
| 394 | by Emacs. For details on how to fix this, see |
| 395 | http://mlton.org/Emacs. |
| 396 | |
| 397 | .SH "SEE ALSO" |
| 398 | .BR mlprof (1) |
| 399 | and the \fBMLton Guide\fP. |