doc/guide/localhost/RunTimeOptions

   1 <!DOCTYPE html>
   2 <html lang="en">
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <meta name="generator" content="AsciiDoc 8.6.9">
   6 <title>RunTimeOptions</title>
   7 <link rel="stylesheet" href="./asciidoc.css" type="text/css">
   8 <link rel="stylesheet" href="./pygments.css" type="text/css">
   9
  10
  11 <script type="text/javascript" src="./asciidoc.js"></script>
  12 <script type="text/javascript">
  13 /*<![CDATA[*/
  14 asciidoc.install();
  15 /*]]>*/
  16 </script>
  17 <link rel="stylesheet" href="./mlton.css" type="text/css">
  18 </head>
  19 <body class="article">
  20 <div id="banner">
  21 <div id="banner-home">
  22 <a href="./Home">MLton 20180207</a>
  23 </div>
  24 </div>
  25 <div id="header">
  26 <h1>RunTimeOptions</h1>
  27 </div>
  28 <div id="content">
  29 <div id="preamble">
  30 <div class="sectionbody">
  31 <div class="paragraph"><p>Executables produced by MLton take command line arguments that control
  32 the runtime system.  These arguments are optional, and occur before
  33 the executable&#8217;s usual arguments.  To use these options, the first
  34 argument to the executable must be <span class="monospaced">@MLton</span>.  The optional arguments
  35 then follow, must be terminated by <span class="monospaced">--</span>, and are followed by any
  36 arguments to the program.  The optional arguments are <em>not</em> made
  37 available to the SML program via <span class="monospaced">CommandLine.arguments</span>.  For
  38 example, a valid call to <span class="monospaced">hello-world</span> is:</p></div>
  39 <div class="listingblock">
  40 <div class="content monospaced">
  41 <pre>hello-world @MLton gc-summary fixed-heap 10k -- a b c</pre>
  42 </div></div>
  43 <div class="paragraph"><p>In the above example,
  44 <span class="monospaced">CommandLine.arguments () = ["a", "b", "c"]</span>.</p></div>
  45 <div class="paragraph"><p>It is allowed to have a sequence of <span class="monospaced">@MLton</span> arguments, as in:</p></div>
  46 <div class="listingblock">
  47 <div class="content monospaced">
  48 <pre>hello-world @MLton gc-summary -- @MLton fixed-heap 10k -- a b c</pre>
  49 </div></div>
  50 <div class="paragraph"><p>Run-time options can also control MLton, as in</p></div>
  51 <div class="listingblock">
  52 <div class="content monospaced">
  53 <pre>mlton @MLton fixed-heap 0.5g -- foo.sml</pre>
  54 </div></div>
  55 </div>
  56 </div>
  57 <div class="sect1">
  58 <h2 id="_options">Options</h2>
  59 <div class="sectionbody">
  60 <div class="ulist"><ul>
  61 <li>
  62 <p>
  63 <span class="monospaced">fixed-heap <em>x</em>{k|K|m|M|g|G}</span>
  64 </p>
  65 <div class="paragraph"><p>Use a fixed size heap of size <em>x</em>, where <em>x</em> is a real number and the
  66 trailing letter indicates its units.</p></div>
  67 <table class="tableblock frame-all grid-all"
  68 style="
  69 width:100%;
  70 ">
  71 <col style="width:25%;">
  72 <col style="width:75%;">
  73 <tbody>
  74 <tr>
  75 <td class="tableblock halign-center valign-top" ><p class="tableblock"><span class="monospaced">k</span> or <span class="monospaced">K</span></p></td>
  76 <td class="tableblock halign-left valign-top" ><p class="tableblock">1024</p></td>
  77 </tr>
  78 <tr>
  79 <td class="tableblock halign-center valign-top" ><p class="tableblock"><span class="monospaced">m</span> or <span class="monospaced">M</span></p></td>
  80 <td class="tableblock halign-left valign-top" ><p class="tableblock">1,048,576</p></td>
  81 </tr>
  82 <tr>
  83 <td class="tableblock halign-center valign-top" ><p class="tableblock"><span class="monospaced">g</span> or <span class="monospaced">G</span></p></td>
  84 <td class="tableblock halign-left valign-top" ><p class="tableblock">1,073,741,824</p></td>
  85 </tr>
  86 </tbody>
  87 </table>
  88 <div class="paragraph"><p>A value of <span class="monospaced">0</span> means to use almost all the RAM present on the machine.</p></div>
  89 <div class="paragraph"><p>The heap size used by <span class="monospaced">fixed-heap</span> includes all memory allocated by
  90 SML code, including memory for the stack (or stacks, if there are
  91 multiple threads).  It does not, however, include any memory used for
  92 code itself or memory used by C globals, the C stack, or malloc.</p></div>
  93 </li>
  94 <li>
  95 <p>
  96 <span class="monospaced">gc-messages</span>
  97 </p>
  98 <div class="paragraph"><p>Print a message at the start and end of every garbage collection.</p></div>
  99 </li>
 100 <li>
 101 <p>
 102 <span class="monospaced">gc-summary</span>
 103 </p>
 104 <div class="paragraph"><p>Print a summary of garbage collection statistics upon program
 105 termination to standard error.</p></div>
 106 </li>
 107 <li>
 108 <p>
 109 <span class="monospaced">gc-summary-file <em>file</em></span>
 110 </p>
 111 <div class="paragraph"><p>Print a summary of garbage collection statistics upon program
 112 termination to the file specified by <em>file</em>.</p></div>
 113 </li>
 114 <li>
 115 <p>
 116 <span class="monospaced">load-world <em>world</em></span>
 117 </p>
 118 <div class="paragraph"><p>Restart the computation with the file specified by <em>world</em>, which must
 119 have been created by a call to <span class="monospaced">MLton.World.save</span> by the same
 120 executable.  See <a href="MLtonWorld">MLtonWorld</a>.</p></div>
 121 </li>
 122 <li>
 123 <p>
 124 <span class="monospaced">max-heap <em>x</em>{k|K|m|M|g|G}</span>
 125 </p>
 126 <div class="paragraph"><p>Run the computation with an automatically resized heap that is never
 127 larger than <em>x</em>, where <em>x</em> is a real number and the trailing letter
 128 indicates the units as with <span class="monospaced">fixed-heap</span>.  The heap size for
 129 <span class="monospaced">max-heap</span> is accounted for as with <span class="monospaced">fixed-heap</span>.</p></div>
 130 </li>
 131 <li>
 132 <p>
 133 <span class="monospaced">may-page-heap {false|true}</span>
 134 </p>
 135 <div class="paragraph"><p>Enable paging the heap to disk when unable to grow the heap to a
 136 desired size.</p></div>
 137 </li>
 138 <li>
 139 <p>
 140 <span class="monospaced">no-load-world</span>
 141 </p>
 142 <div class="paragraph"><p>Disable <span class="monospaced">load-world</span>.  This can be used as an argument to the compiler
 143 via <span class="monospaced">-runtime no-load-world</span> to create executables that will not load
 144 a world.  This may be useful to ensure that set-uid executables do not
 145 load some strange world.</p></div>
 146 </li>
 147 <li>
 148 <p>
 149 <span class="monospaced">ram-slop <em>x</em></span>
 150 </p>
 151 <div class="paragraph"><p>Multiply <em>x</em> by the amount of RAM on the machine to obtain what the
 152 runtime views as the amount of RAM it can use.  Typically <em>x</em> is less
 153 than 1, and is used to account for space used by other programs
 154 running on the same machine.</p></div>
 155 </li>
 156 <li>
 157 <p>
 158 <span class="monospaced">stop</span>
 159 </p>
 160 <div class="paragraph"><p>Causes the runtime to stop processing <span class="monospaced">@MLton</span> arguments once the next
 161 <span class="monospaced">--</span> is reached.  This can be used as an argument to the compiler via
 162 <span class="monospaced">-runtime stop</span> to create executables that don&#8217;t process any <span class="monospaced">@MLton</span>
 163 arguments.</p></div>
 164 </li>
 165 </ul></div>
 166 </div>
 167 </div>
 168 </div>
 169 <div id="footnotes"><hr></div>
 170 <div id="footer">
 171 <div id="footer-text">
 172 </div>
 173 <div id="footer-badges">
 174 </div>
 175 </div>
 176 </body>
 177 </html>