[MLton-commit] r4269
Matthew Fluet
MLton@mlton.org
Wed, 30 Nov 2005 20:34:18 -0800
Catching up with wiki changes.
----------------------------------------------------------------------
U mlton/trunk/man/mlton.1
----------------------------------------------------------------------
Modified: mlton/trunk/man/mlton.1
===================================================================
--- mlton/trunk/man/mlton.1 2005-12-01 03:27:06 UTC (rev 4268)
+++ mlton/trunk/man/mlton.1 2005-12-01 04:34:17 UTC (rev 4269)
@@ -28,37 +28,46 @@
\fBMLton\fP's options allow you to control the name of the output
file, the verbosity of compile-time messages, and whether or not
-certain optimizations are performed. They also allow you to specify
-which intermediate files are saved and to stop the compilation process
+certain optimizations are performed. They also can specify
+which intermediate files are saved and can stop the compilation process
early, at some intermediate pass, in which case compilation can be
resumed by passing the resulting files to \fBMLton\fP. \fBMLton\fP
uses the input file suffix to determine the type of input program.
-The possibilities are \fB.c\fP, \fB.cm\fR, \fB.o\fR, and \fB.sml\fR.
+The possibilities are \fB.c\fP, \fB.cm\fP, \fB.mlb\fP, \fB.o\fP, and \fB.sml\fP.
With no arguments, \fBMLton\fP prints the version number and exits.
-For a usage message, run \fBMLton\fP with an invalid switch, e.g.,
-\fBmlton -\fP. In the explanation below and in the usage message,
-for flags that take a boolean argument
-(\fI{\fBtrue\fI|\fBfalse\fI}\fR), the first value listed is the
+For a usage message, run \fBMLton\fP with an invalid switch, e.g.
+\fBmlton -z\fP. In the explanation below and in the usage message,
+for flags that take a number of choices
+(e.g. \fI{\fBtrue\fP|\fBfalse\fP}\fR), the first value listed is the
default.
+plain \fB bold \fP plain
+
+plain \fI italic \fR plain
+
+plain \fI italic \fB bold \fP italic \fR plain
+
+plain \fB bold \fI italic \fP bold \fR plain
+
+plain \fB bold \fI italic \fB bold \fP italic \fP bold \fR plain
+
.SH Compile-time options
.TP
-\fB-align \fI{\fB4\fP|\fB8\fP}\fP
+\fB-align \fI{\fB4\fP|\fB8\fP}\fP\fR
Aligns object sizes and doubles in memory by the specified alignment.
-On x86, the default is \fB4\fP and on Sparc the default is
-\fB8\fP.
+The default varies depending on architecture.
.TP
-\fB-as-opt \fIopt\fR
-Pass the option to \fBgcc\fP when assembling.
+\fB-as-opt \fIoption\fP\fR
+Pass \fIoption\fP to \fBgcc\fP when assembling.
.TP
-\fB-cc-opt \fIoption\fP\fP
-Pass the option to \fBgcc\fP when compiling C code.
+\fB-cc-opt \fIoption\fP\fR
+Pass \fIoption\fP to \fBgcc\fP when compiling C code.
.TP
-\fB-codegen \fI{\fBnative\fI|\fBbytecode|\fBc\fI}\fR
+\fB-codegen \fI{\fBnative\fP|\fBbytecode\fP|\fBc\fP}\fP\fR
Generate native code, byte code, or C code. With \fB-codegen
native\fP, \fBMLton\fP typically compiles more quickly and generates
better code.
@@ -68,60 +77,59 @@
Set the value of a compile-time constant. Here is a list of available
constants, their default values, and what they control.
-\fBExn.keepHistory \fI{\fBfalse\fP|\fBtrue\fP}\fR
+\fBExn.keepHistory \fI{\fBfalse\fP|\fBtrue\fP}\fP\fR
.in +.5i
-Enable \fBExn.history\fP. There is a performance cost to setting this
+Enable \fBMLton.Exn.history\fP. There is a performance cost to setting this
to \fBtrue\fP, both in memory usage of exceptions and in run time,
because of additional work that must be performed at each exception
construction, raise, and handle.
.in -.5i
.TP
-\fB-default-ann \fIann\fR
-Specify the default annotation values for \fBmlb\fP files. For
+\fB-default-ann \fIann\fP\fR
+Specify default ML Basis annotations. For
example, \fB-default-ann 'warnUnused true'\fP
causes unused variable warnings to be enabled by default.
-Defaults may be overridden by an annotation in an \fBmlb\fP file.
+Defaults may be overridden by an annotation in an ML Basis file.
.TP
-\fB-disable-ann \fIann\fR
-Ignore the specified annotation in every \fBmlb\fP file. For example,
-to see \fIall\fP match and unused warnings, use \fB-disable-ann
-'warnMatch' -disable-ann 'warnUnused' -disable-ann 'forceUsed'
--default-ann 'warnUnused true'\fP.
+\fB-disable-ann \fIann\fP\fR
+Ignore the specified ML Basis annotation in every ML Basis File. For example,
+to see \fIall\fP match and unused warnings, compile with \fB-default-ann 'warnUnused true'
+-disable-ann forceUsed -disable-ann nonexhaustiveMatch -disable-ann redundantMatch
+-disable-ann warnUnused\fP.
.TP
-\fB-export-header \fIfile\fR
+\fB-export-header \fIfile\fP\fR
Write to \fIfile\fP C prototypes for all of the functions exported
-from SML to C. This flag is useful for programs that use
-\fB_export\fP expressions.
+from SML to C.
.TP
-\fB-ieee-fp \fI{\fBfalse\fP|\fBtrue\fP}\fR
-Cause the code generator to be pedantic about following the IEEE
+\fB-ieee-fp \fI{\fBfalse\fP|\fBtrue\fP}\fP\fR
+Cause the native code generator to be pedantic about following the IEEE
floating point standard. By default, it is not, because of the
-performance cost. This has no effect with \fB-codegen c\fP.
+performance cost. This only has an effect with h\fB-codegen native\fP.
.TP
-\fB-inline \fIn\fR
+\fB-inline \fIn\fP\fR
Set the inlining threshold used in the optimizer. The threshold is an
approximate measure of code size of a procedure. The default is 320.
.TP
-\fB-keep \fI{\fBg\fP|\fBo\fP|\fBsml\fP}\fR
+\fB-keep \fI{\fBg\fP|\fBo\fP|\fBsml\fP}\fP\fR
Save intermediate files. If no \fB-keep\fP argument is given, then
only the output file is saved.
.in +.5i
-\fBg\fP generated \fB.S\fP and \fB.c\fP files passed to gcc
+\fBg\fP generated \fB.S\fP and \fB.c\fP files passed to gcc and the assembler
.br
-\fBo\fP object (\fB.o\fR) files
+\fBo\fP object (\fB.o\fP) files
.br
\fBsml\fP SML file
.in -.5i
.TP
-\fB-link-opt \fIopt\fR
-Pass the option to \fBgcc\fP when linking. You can use this to
+\fB-link-opt \fIoption\fP\fR
+Pass \fIoption\fP to \fBgcc\fP when linking. You can use this to
specify library search paths, e.g. \fB-link-opt -Lpath\fP, and
libraries to link with, e.g. \fB-link-opt -lfoo\fP, or even both at
the same time, e.g. \fB-link-opt '-Lpath -lfoo'\fP. If you wish to
@@ -129,62 +137,80 @@
syntax, e.g., \fB-link-opt '-Wl,--export-dynamic'\fP.
.TP
-\fB-mlb-path-map \fIfile\fR
-Use file as an MLB path map to define additional MLB path variables.
+\fB-mlb-path-map \fIfile\fP\fR
+Use \fIfile\fP as an ML Basis path map to define additional MLB path variables.
Multiple uses of \fB-mlb-path-map\fP are allowed, with variable
definitions in later path maps taking precendence over earlier ones.
.TP
-\fB-output \fIfile\fR
+\fB-output \fIfile\fP\fR
Specify the name of the final output file.
The default name is the input file name with its suffix removed and an
appropriate, possibly empty, suffix added.
.TP
-\fB-profile \fI{\fBno\fP|\fBalloc\fP|\fBcount\fP|\fBtime\fP}\fR
-Produce an executable that will gather profiling information. When
+\fB-profile \fI{\fBno\fP|\fBalloc\fP|\fBcount\fP|\fBtime\fP}\fP\fR
+Produce an executable that gathers profiling data. When
such an executable is run, it will produce an \fBmlmon.out\fP file.
The man page on \fBmlprof\fP describes how to extract information from
this file.
.TP
-\fB-profile-branch \fI{\fBfalse\fP|\fBtrue\fP}\fR
-If true, the profiler will separately count the time spent (or bytes
-allocated) in each branch of a function definition, \fBcase\fP
+\fB-profile-branch \fI{\fBfalse\fP|\fBtrue\fP}\fP\fR
+If true, the profiler will separately gather profiling data
+for each branch of a function definition, \fBcase\fP
expression, and \fBif\fP expression.
.TP
-\fB-profile-stack \fI{\fBfalse\fP|\fBtrue\fP}\fR
-If true, the profiler will count the time spent (or bytes allocated)
-while a function is on the stack.
+\fB-profile-stack \fI{\fBfalse\fP|\fBtrue\fP}\fP\fR
+If true, the profiler will gather profiling data for each
+function on the stack, not just the topmost one.
.TP
-\fB-runtime \fIarg\fP\fP
+\fB-runtime \fIarg\fP\fR
Pass argument to the runtime system via \fB@MLton\fP. The argument
will be processed before other \fB@MLton\fP command line switches.
Multiple uses of \fB-runtime\fP are allowed, and will pass all the
arguments in order. If the same runtime switch occurs more than once,
-then the last setting will dominate, except for \fBno-load-world\fP.
+then the last setting will take effect. There is no need to supply the
+leading \fB@MLton\fP or the trailing \fB--\fP; these will be
+supplied automatically.
+An argument to \fB-runtime\fP may contain spaces, which will cause the
+argument to be treated as a sequence of words by the runtime. For
+example, the command line:
+.in +.5i
+mlton -runtime 'ram-slop 0.4' foo.sml
+.in -.5i
+will cause foo to run as if it had been called like
+.in +.5i
+foo @MLton ram-slop 0.4 --
+.in -.5i
+
+An executable created with \fB-runtime stop\fP doesn't proces any
+\fB@MLton\fP arguments. This is useful to create an executable,
+e.g. \fBecho\fP, that must treat \fB@MLton\fP like any other
+command-line argument.
+
.TP
-\fB-show-basis \fIfile\fR
+\fB-show-basis \fIfile\fP\fR
Pretty print to \fIfile\fP the basis defined by the input program.
.TP
-\fB-show-def-use \fIfile\fR
+\fB-show-def-use \fIfile\fP\fR
Output def-use information to \fIfile\fP. Each identifier that is
defined appears on a line, follwed on subequent lines by the position
of each use.
.TP
-\fB-stop \fI{\fBf\fP|\fBg\fP|\fBo\fP|\fBsml\fP|\fBtc\fP}\fR
+\fB-stop \fI{\fBf\fP|\fBg\fP|\fBo\fP|\fBsml\fP|\fBtc\fP}\fP\fR
Specify pass to stop at.
.in +.5i
\fBf\fP list of files on stdout (only makes sense when input is \fBfoo.cm\fP or \fBfoo.mlb\fP)
.br
\fBg\fP generated \fB.S\fP and \fB.c\fP files
.br
-\fBo\fP object file (\fI*\fB.o\fR).
+\fBo\fP object (\fB.o\fP) files
.br
\fBsml\fP SML file (only makes sense when input is \fBfoo.cm\fP or \fBfoo.mlb\fP)
.br
@@ -195,7 +221,7 @@
or \fB.o\fP files.
.TP
-\fB-target \fI{\fBself\fP|\fI...}\fR
+\fB-target \fI{\fBself\fP|...}\fP\fR
Generate an executable that runs on the specified platform. The
default is \fBself\fP, which means to compile for the machine that
\fBMLton\fP is running on. To use any other target, you must first
@@ -203,58 +229,42 @@
details.
.TP
-\fB-target-as-opt \fItarget\fP \fIopt\fR
-Like \fB-as-opt\fP, this passes \fIopt\fP to \fBgcc\fP when assembling,
-except it only passes \fIopt\fP when the target architecture or
+\fB-target-as-opt \fItarget\fP \fIoption\fP\fR
+Like \fB-as-opt\fP, this passes \fIoption\fP to \fBgcc\fP when assembling,
+except it only passes \fIoption\fP when the target architecture or
operating system is \fItarget\fP.
-Valid values for \fItarget\fP are as for \fB-target-cc-opt\fP.
+Valid values for \fItarget\fP are:
+\fBhppa\fP, \fBpowerpc\fP, \fBsparc\fP, \fBx86\fP,
+\fBcygwin\fP, \fBdarwin\fP, \fBfreebsd\fP, \fBlinux\fP,
+\fBmingw\fP, \fBnetbsd\fP, \fBopenbsd\fP, \fBsolaris\fP.
.TP
-\fB-target-cc-opt \fItarget\fP \fIopt\fR
-Like \fB-cc-opt\fP, this passes \fIopt\fP to \fBgcc\fP when compiling
-C code, except it only passes \fIopt\fP when the target architecture
-or operating system is \fItarget\fP.
-Valid values for \fItarget\fP are:
-\fBpowerpc\fP,
-\fBsparc\fP,
-\fBx86\fP,
-\fBcygwin\fP,
-\fBdarwin\fP,
-\fBfreebsd\fP,
-\fBlinux\fP,
-\fBmingw\fP,
-\fBnetbsd\fP,
-\fBopenbsd\fP,
-and \fBsolaris\fP.
+\fB-target-cc-opt \fItarget\fP \fIoption\fP\fR
+Like \fB-cc-opt\fP, this passes \fIoption\fP to \fBgcc\fP when compiling
+C code, except it only passes \fIoption\fP when the target architecture
+or operating system is \fItarget\fP. Valid values for \fItarget\fR
+are as for \fB-target-as-opt\fP.
.TP
-\fB-target-link-opt \fItarget\fP \fIopt\fR
-Like \fB-link-opt\fP, this passes \fIopt\fP to \fBgcc\fP when linking,
-except it only passes \fIopt\fP when the target architecture or
+\fB-target-link-opt \fItarget\fP \fIoption\fP\fR
+Like \fB-link-opt\fP, this passes \fIoption\fP to \fBgcc\fP when linking,
+except it only passes \fIoption\fP when the target architecture or
operating system is \fItarget\fP.
-Valid values for \fItarget\fP are as for \fB-target-cc-opt\fP.
+Valid values for \fItarget\fP are as for \fB-target-as-opt\fP.
.TP
-\fB-verbose\fP \fI{\fB0\fP|\fB1\fP|\fB2\fP|\fB3\fP}\fP
-Be verbose about what passes are running. The default is 0.
+\fB-verbose \fI{\fB0\fP|\fB1\fP|\fB2\fP|\fB3\fP}\fP\fR
+How verbose to be about what passes are running. The default is 0.
.in +.5i
\fB0\fP silent
.br
\fB1\fP calls to compiler, assembler, and linker
.br
-\fB2\fP 1 + intermediate compiler passes
+\fB2\fP 1, plus intermediate compiler passes
.br
-\fB3\fP 2 + some data structure sizes
+\fB3\fP 2, plus some data structure sizes
.in -.5i
-.TP
-\fB-warn-match \fI{\fBtrue\fP|\fBfalse\fP}\fR
-Report nonexhaustive and redundant matches.
-
-.TP
-\fB-warn-unused \fI{\fBfalse\fP|\fBtrue\fP}\fR
-Report unused identifiers.
-
.SH Runtime system options
To control the runtime system, executables produced by \fBMLton\fP take
several optional command line arguments before their usual arguments.