<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 2.0.23">
<title>RunTimeOptions</title>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700">
<link rel="stylesheet" href="./asciidoctor.css">
<link rel="stylesheet" href="./mlton.css">

</head>
<body class="article">
<div id="mlton-header">
<div id="mlton-header-text">
<h2>
<a href="./Home">
MLton
20241230
</a>
</h2>
</div>
</div>
<div id="header">
<h1>RunTimeOptions</h1>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p>Executables produced by MLton take command line arguments that control
the runtime system.  These arguments are optional, and occur before
the executable&#8217;s usual arguments.  To use these options, the first
argument to the executable must be <code>@MLton</code>.  The optional arguments
then follow, must be terminated by <code>--</code>, and are followed by any
arguments to the program.  The optional arguments are <em>not</em> made
available to the SML program via <code>CommandLine.arguments</code>.  For
example, a valid call to <code>hello-world</code> is:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>hello-world @MLton gc-summary fixed-heap 10k -- a b c</pre>
</div>
</div>
<div class="paragraph">
<p>In the above example,
<code>CommandLine.arguments () = ["a", "b", "c"]</code>.</p>
</div>
<div class="paragraph">
<p>It is allowed to have a sequence of <code>@MLton</code> arguments, as in:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>hello-world @MLton gc-summary -- @MLton fixed-heap 10k -- a b c</pre>
</div>
</div>
<div class="paragraph">
<p>Run-time options can also control MLton, as in</p>
</div>
<div class="listingblock">
<div class="content">
<pre>mlton @MLton fixed-heap 0.5g -- foo.sml</pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_options">Options</h2>
<div class="sectionbody">
<div class="ulist">
<ul>
<li>
<p><code>fixed-heap <em>x</em>{k|K|m|M|g|G}</code></p>
<div class="paragraph">
<p>Use a fixed size heap of size <em>x</em>, where <em>x</em> is a real number and the
trailing letter indicates its units.</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 25%;">
<col style="width: 75%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock"><code>k</code> or <code>K</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">1024</p></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock"><code>m</code> or <code>M</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">1,048,576</p></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock"><code>g</code> or <code>G</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">1,073,741,824</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>A value of <code>0</code> means to use almost all the RAM present on the machine.</p>
</div>
<div class="paragraph">
<p>The heap size used by <code>fixed-heap</code> 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.</p>
</div>
</li>
<li>
<p><code>gc-messages</code></p>
<div class="paragraph">
<p>Print a message at the start and end of every garbage collection.</p>
</div>
</li>
<li>
<p><code>gc-summary</code></p>
<div class="paragraph">
<p>Print a summary of garbage collection statistics upon program
termination to standard error.</p>
</div>
</li>
<li>
<p><code>gc-summary-file <em>file</em></code></p>
<div class="paragraph">
<p>Print a summary of garbage collection statistics upon program
termination to the file specified by <em>file</em>.</p>
</div>
</li>
<li>
<p><code>load-world <em>world</em></code></p>
<div class="paragraph">
<p>Restart the computation with the file specified by <em>world</em>, which must
have been created by a call to <code>MLton.World.save</code> by the same
executable.  See <a href="MLtonWorld">MLtonWorld</a>.</p>
</div>
</li>
<li>
<p><code>max-heap <em>x</em>{k|K|m|M|g|G}</code></p>
<div class="paragraph">
<p>Run the computation with an automatically resized heap that is never
larger than <em>x</em>, where <em>x</em> is a real number and the trailing letter
indicates the units as with <code>fixed-heap</code>.  The heap size for
<code>max-heap</code> is accounted for as with <code>fixed-heap</code>.</p>
</div>
</li>
<li>
<p><code>may-page-heap {false|true}</code></p>
<div class="paragraph">
<p>Enable paging the heap to disk when unable to grow the heap to a
desired size.</p>
</div>
</li>
<li>
<p><code>no-load-world</code></p>
<div class="paragraph">
<p>Disable <code>load-world</code>.  This can be used as an argument to the compiler
via <code>-runtime no-load-world</code> to create executables that will not load
a world.  This may be useful to ensure that set-uid executables do not
load some strange world.</p>
</div>
</li>
<li>
<p><code>ram-slop <em>x</em></code></p>
<div class="paragraph">
<p>Multiply <em>x</em> by the amount of RAM on the machine to obtain what the
runtime views as the amount of RAM it can use.  Typically <em>x</em> is less
than 1, and is used to account for space used by other programs
running on the same machine.</p>
</div>
</li>
<li>
<p><code>stop</code></p>
<div class="paragraph">
<p>Causes the runtime to stop processing <code>@MLton</code> arguments once the next
<code>--</code> is reached.  This can be used as an argument to the compiler via
<code>-runtime stop</code> to create executables that don&#8217;t process any <code>@MLton</code>
arguments.</p>
</div>
</li>
</ul>
</div>
</div>
</div>
</div>
<div id="mlton-footer">
<div id="mlton-footer-text">
<div>
Last updated Thu Oct 21 15:53:06 2021 -0400 by Matthew Fluet.
<a href="https://github.com/MLton/mlton/commits/master/doc/guide/src/RunTimeOptions.adoc">Log</a>
<a href="https://github.com/MLton/mlton/edit/master/doc/guide/src/RunTimeOptions.adoc">Edit</a>
</div>
</div>
</body>
</html>