Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
mlton(1)		    General Commands Manual		      mlton(1)

       mlton  -	 whole-program	compiler for the Standard ML (SML) programming

       mlton [option ...] file.{c|mlb|o|sml} [file.{c|o|s|S} ...]

       MLton is	run from the command line with a collection  of	 options  fol-
       lowed  by a file	name and a list	of files with which to compile,	assem-
       ble, and	link with.  The	simplest case is to run	mlton  foo.sml,	 where
       foo.sml	contains a valid SML program, in which case MLton compiles the
       program to produce an executable	foo.  Since  MLton  does  not  support
       separate	 compilation,  the program must	be the entire program you wish
       to compile.  However, the program may refer to  signatures  and	struc-
       tures defined in	the Basis Library.

       Larger programs,	spanning many files, may be compiled with the ML Basis
       system.	In this	case, mlton will compile the complete SML pro-
       gram  described	by the basis, which may	specify	both SML files
       and additional bases.  See the MLton Guide for details.

       MLton's compile-time options control the	name of	the output  file,  the
       verbosity  of  compile-time  messages, and whether or not certain opti-
       mizations are performed.	 They  also  can  specify  which  intermediate
       files are saved and can stop the	compilation process early, at some in-
       termediate pass,	in which case compilation can be  resumed  by  passing
       the  generated files to MLton.  MLton uses the input file suffix	to de-
       termine the type	of input program.  The possibilities are .c, .mlb, .o,
       .s, and .sml.

       With  no	 arguments,  MLton prints the version number and exits.	 For a
       usage message, run MLton	with an	invalid	switch,	e.g.   mlton  -z.   In
       the  explanation	 below and in the usage	message, for flags that	take a
       number of choices (e.g. {true|false}), the first	value  listed  is  the

Compile-time options
       -align {4|8}
	      Aligns  object  sizes  and  doubles  in  memory by the specified
	      alignment.  The default varies depending on architecture.

       -as-opt option
	      Pass option to gcc when assembling.

       -cc-opt option
	      Pass option to gcc when compiling	C code.

       -codegen	{native|x86|amd64|c}
	      Generate native code or C	code.  With -codegen native  (-codegen
	      x86  or  -codegen	 amd64), MLton typically compiles more quickly
	      and generates better code.

       -const 'name value'
	      Set the value of a compile-time constant.	 Here  is  a  list  of
	      available	 constants,  their  default values, and	what they con-

	      Exn.keepHistory {false|true}
		   Enable MLton.Exn.history.  There is a performance  cost  to
		   setting  this  to  true, both in memory usage of exceptions
		   and in run time, because of additional work	that  must  be
		   performed  at  each exception construction, raise, and han-

       -default-ann ann
	      Specify default ML Basis annotations.  For example, -default-ann
	      'warnUnused  true' causes	unused variable	warnings to be enabled
	      by default.  Defaults may	be overridden by an annotation	in  an
	      ML Basis file.

       -default-type type
	      Specify  the default binding for a primitive type.  For example,
	      -default-type word64 causes the top-level	type word and the top-
	      level  structure	Word  in  the  Basis  Library  to  be equal to
	      Word64.word  and	Word64:WORD,  respectively.   Similarly,  -de-
	      fault-type  intinf  causes  the  top-level type int and the top-
	      level structure  Int  in	the  Basis  Library  to	 be  equal  to and IntInf:INTEGER, respectively.

       -disable-ann ann
	      Ignore the specified ML Basis annotation in every	ML Basis File.
	      For example, to see all match and	unused warnings, compile  with
	      -default-ann  'warnUnused	 true',	 -disable-ann forceUsed, -dis-
	      able-ann nonexhaustiveMatch,  -disable-ann  redundantMatch,  and
	      -disable-ann warnUnused.

       -export-header file
	      Write  C prototypes to file for all of the functions in the pro-
	      gram exported from SML to	C.

       -ieee-fp	{false|true}
	      Cause the	x86 native code	generator to be	pedantic about follow-
	      ing  the	IEEE  floating point standard.	By default, it is not,
	      because of the performance cost.	This only has an  effect  with
	      -codegen x86.

       -inline n
	      Set the inlining threshold used in the optimizer.	 The threshold
	      is an approximate	measure	of code	size of	a procedure.  The  de-
	      fault is 320.

       -keep {g|o}
	      Save  intermediate  files.   If no -keep argument	is given, then
	      only the output file is saved.
		   g	generated .c and .s files passed to gcc	and the	assem-
		   o	object (.o) files

       -link-opt option
	      Pass  option  to	gcc when linking.  You can use this to specify
	      library search paths, e.g. -link-opt -Lpath,  and	 libraries  to
	      link  with, e.g. -link-opt -lfoo,	or even	both at	the same time,
	      e.g. -link-opt '-Lpath -lfoo'.  If you wish to pass an option to
	      the  linker,  you	 must  use  gcc's -Wl, syntax, e.g., -link-opt

       -mlb-path-map file
	      Use file as an ML	Basis path map to define additional  MLB  path
	      variables.  Multiple uses	of -mlb-path-map and -mlb-path-var are
	      allowed, with variable definitions in  later  path  maps	taking
	      precedence over earlier ones.

       -mlb-path-var 'name value'
	      Define  an  additional  MLB  path	 variable.   Multiple  uses of
	      -mlb-path-map and	-mlb-path-var are allowed, with	variable defi-
	      nitions in later path maps taking	precedence over	earlier	ones.

       -output file
	      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.

       -profile	{no|alloc|count|time}
	      Produce an executable that gathers profiling data.  When such an
	      executable is run, it will produce an mlmon.out file.   The  man
	      page  on	mlprof	describes how to extract information from this

       -profile-branch {false|true}
	      If true, the profiler will separately gather profiling data  for
	      each  branch  of	a function definition, case expression,	and if

       -profile-stack {false|true}
	      If true, the profiler will gather	profiling data for  all	 func-
	      tions on the stack, not just the currently executing function.

       -profile-val {false|true}
	      If  true,	the profiler will separately gather profiling data for
	      each (expansive) val declaration.

       -runtime	arg
	      Pass argument to the runtime system via  @MLton.	 The  argument
	      will  be	processed  before  other @MLton	command	line switches.
	      Multiple uses of -runtime	are allowed, and will pass all the ar-
	      guments  in  order.  If the same runtime switch occurs more than
	      once, then the last setting will take effect.  There is no  need
	      to  supply  the leading @MLton or	the trailing --; these will be
	      supplied automatically.

	      An argument to -runtime may contain spaces, which	will cause the
	      argument	to  be	treated	as a sequence of words by the runtime.
	      For example, the command line:
		   mlton -runtime 'ram-slop 0.4' foo.sml
	      will cause foo to	run as if it had been called like
		   foo @MLton ram-slop 0.4 --

	      An executable created with -runtime  stop	 doesn't  process  any
	      @MLton  arguments.  This is useful to create an executable, e.g.
	      echo, that must treat @MLton like	any other  command-line	 argu-
		   % mlton -runtime stop echo.sml
		   % echo @MLton --
		   @MLton --

       -show-basis file
	      Pretty print to file the basis defined by	the input program.

       -show-def-use file
	      Output def-use information to file.  Each	identifier that	is de-
	      fined appears on a line, followed	on subsequent lines by the po-
	      sition of	each use.

       -stop {f|g|o|tc}
	      Specify when to stop.
		   f	 list  of files	on stdout (only	makes sense when input
		   g	generated .c and .s files
		   o	object (.o) files
		   tc	after type checking
	      If you compile -stop g or	-stop o, you can resume	compilation by
	      running MLton on the generated .c	and .s or .o files.

       -target {self|...}
	      Generate an executable that runs on the specified	platform.  The
	      default is self, which means to compile for the machine that ML-
	      ton  is running on.  To use any other target, you	must first in-
	      stall a cross compiler.  See the MLton Guide for details.

       -target-as-opt target option
	      Like -as-opt, this passes	option to gcc when assembling,	except
	      it  only passes option when the target architecture or operating
	      system is	target.	 Valid values for target  are:	alpha,	amd64,
	      arm,,  hppa,  ia64, m68k,	mips, powerpc, powerpc64, s390,	sparc,
	      x86, aix,	cygwin,	darwin,	freebsd,  hurd,	 hpux,	linux,	mingw,
	      netbsd, openbsd, solaris.

       -target-cc-opt target option
	      Like  -cc-opt,  this passes option to gcc	when compiling C code,
	      except it	only passes option when	the target architecture	or op-
	      erating  system  is  target.  Valid values for target are	as for

       -target-link-opt	target option
	      Like -link-opt, this passes option to gcc	when  linking,	except
	      it  only passes option when the target architecture or operating
	      system is	target.	 Valid values for  target  are	as  for	 -tar-

       -verbose	{0|1|2|3}
	      How verbose to be	about what passes are running.	The default is
		   0  silent
		   1  calls to compiler, assembler, and	linker
		   2  1, plus intermediate compiler passes
		   3  2, plus some data	structure sizes

Runtime	system options
       Executables produced by MLton take command line arguments that  control
       the runtime system.  These arguments are	optional, and occur before the
       executable's usual arguments.  To use these options, the	first argument
       to  the executable must be @MLton.  The optional	arguments then follow,
       must be terminated by --, and are followed by any arguments to the pro-
       gram.  The optional arguments are not made available to the SML program
       via CommandLine.arguments.  For example,	a valid	 call  to  hello-world
	    hello-world	@MLton gc-summary fixed-heap 10k -- a b	c
       In the above example, CommandLine.arguments () =	["a", "b", "c"].

       It is allowed to	have a sequence	of @MLton arguments, as	in:
	    hello-world	@MLton gc-summary -- @MLton fixed-heap 10k -- a	b c

       Run-time	options	can also control MLton,	as in
	    mlton @MLton fixed-heap 0.5g -- foo.sml

       fixed-heap x{k|K|m|M|g|G}
	      Use  a  fixed  size heap of size x, where	x is a real number and
	      the trailing letter indicates its	units.
		   k or	K    1024
		   m or	M   1,048,576
		   g or	G    1,073,741,824
	      A	value of 0 means to use	almost all the RAM present on the  ma-

	      The  heap	 size used by fixed-heap includes all memory allocated
	      by SML code, including memory for	the stack (or stacks, if there
	      are multiple threads).  It does not, however, include any	memory
	      used for code itself or memory used by C globals,	the  C	stack,
	      or malloc.

	      Print  a	message	 at the	start and end of every garbage collec-

	      Print a summary of garbage collection  statistics	 upon  program

       load-world world
	      Restart  the computation with the	file specified by world, which
	      must have	been created by	a call to by the same
	      executable.  See the MLton Guide for details.

       max-heap	x{k|K|m|M|g|G}
	      Run  the	computation with an automatically resized heap that is
	      never larger than	x, where x is a	real number and	 the  trailing
	      letter  indicates	 the  units as with fixed-heap.	 The heap size
	      for max-heap is accounted	for as with fixed-heap.

       may-page-heap {false|true}
	      Enable paging the	heap to	disk when unable to grow the heap to a
	      desired size.

	      Disable load-world.  This	can be used as an argument to the com-
	      piler via	-runtime no-load-world to create executables that will
	      not load a world.	 This may be useful to ensure that set-uid ex-
	      ecutables	do not load some strange world.

       ram-slop	x
	      Multiply x by the	amount of RAM on the machine  to  obtain  what
	      the  runtime views as the	amount of RAM it can use.  Typically x
	      is less than 1, and is used to account for space used  by	 other
	      programs running on the same machine.

       stop   Causes  the runtime to stop processing @MLton arguments once the
	      next -- is reached.  This	can be used as an argument to the com-
	      piler via	-runtime stop to create	executables that don't process
	      any @MLton arguments.

       MLton's type error messages are not in a	form suitable  for  processing
       by Emacs.  For details on how to	fix this, see

       mlprof(1) and the MLton Guide.

				 June 8, 2010			      mlton(1)

NAME | SYNOPSIS | DESCRIPTION | Compile-time options | Runtime system options | DIAGNOSTICS | SEE ALSO

Want to link to this manual page? Use this URL:

home | help