doc/running.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
   2 <html>
   3 <head>
   4 <title>Running LuaJIT</title>
   5 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   6 <meta name="Author" content="Mike Pall">
   7 <meta name="Copyright" content="Copyright (C) 2005-2010, Mike Pall">
   8 <meta name="Language" content="en">
   9 <link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
  10 <link rel="stylesheet" type="text/css" href="bluequad-print.css" media="print">
  11 <style type="text/css">
  12 table.opt {
  13   line-height: 1.2;
  14 }
  15 tr.opthead td {
  16   font-weight: bold;
  17 }
  18 td.flag_name {
  19   width: 4em;
  20 }
  21 td.flag_level {
  22   width: 2em;
  23   text-align: center;
  24 }
  25 td.param_name {
  26   width: 6em;
  27 }
  28 td.param_default {
  29   width: 4em;
  30   text-align: right;
  31 }
  32 </style>
  33 </head>
  34 <body>
  35 <div id="site">
  36 <a href="http://luajit.org"><span>Lua<span id="logo">JIT</span></span></a>
  37 </div>
  38 <div id="head">
  39 <h1>Running LuaJIT</h1>
  40 </div>
  41 <div id="nav">
  42 <ul><li>
  43 <a href="luajit.html">LuaJIT</a>
  44 <ul><li>
  45 <a href="install.html">Installation</a>
  46 </li><li>
  47 <a class="current" href="running.html">Running</a>
  48 </li><li>
  49 <a href="api.html">API Extensions</a>
  50 </li></ul>
  51 </li><li>
  52 <a href="status.html">Status</a>
  53 <ul><li>
  54 <a href="changes.html">Changes</a>
  55 </li></ul>
  56 </li><li>
  57 <a href="faq.html">FAQ</a>
  58 </li><li>
  59 <a href="http://luajit.org/performance.html">Performance <span class="ext">&raquo;</span></a>
  60 </li><li>
  61 <a href="http://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
  62 </li></ul>
  63 </div>
  64 <div id="main">
  65 <p>
  66 LuaJIT has only a single stand-alone executable, called <tt>luajit</tt> on
  67 POSIX systems or <tt>luajit.exe</tt> on Windows. It can be used to run simple
  68 Lua statements or whole Lua applications from the command line. It has an
  69 interactive mode, too.
  70 </p>
  71 <p class="indent" style="color: #c00000;">
  72 Note: the beta test releases only install under the versioned name on
  73 POSIX systems (to avoid overwriting a previous version). You either need
  74 to type <tt>luajit-2.0.0-beta5</tt> to start it or create a symlink
  75 with a command like this:
  76 </p>
  77 <pre class="code" style="color: #c00000;">
  78 sudo ln -sf luajit-2.0.0-beta5&nbsp;/usr/local/bin/luajit
  79 </pre>
  80 <p>
  81 Unlike previous versions <b>optimization is turned on by default</b> in
  82 LuaJIT 2.0!<br>It's no longer necessary to use <tt>luajit&nbsp;-O</tt>.
  83 </p>
  84
  85 <h2 id="options">Command Line Options</h2>
  86 <p>
  87 The <tt>luajit</tt> stand-alone executable is just a slightly modified
  88 version of the regular <tt>lua</tt> stand-alone executable.
  89 It supports the same basic options, too. <tt>luajit&nbsp;-h</tt>
  90 prints a short list of the available options. Please have a look at the
  91 <a href="http://www.lua.org/manual/5.1/manual.html#6"><span class="ext">&raquo;</span>&nbsp;Lua manual</a>
  92 for details.
  93 </p>
  94 <p>
  95 Two additional options control the behavior of LuaJIT:
  96 </p>
  97
  98 <h3 id="opt_j"><tt>-j cmd[=arg[,arg...]]</tt></h3>
  99 <p>
 100 This option performs a LuaJIT control command or activates one of the
 101 loadable extension modules. The command is first looked up in the
 102 <tt>jit.*</tt> library. If no matching function is found, a module
 103 named <tt>jit.&lt;cmd&gt;</tt> is loaded and the <tt>start()</tt>
 104 function of the module is called with the specified arguments (if
 105 any). The space between <tt>-j</tt> and <tt>cmd</tt> is optional.
 106 </p>
 107 <p>
 108 Here are the available LuaJIT control commands:
 109 </p>
 110 <ul>
 111 <li id="j_on"><tt>-jon</tt> &mdash; Turns the JIT compiler on (default).</li>
 112 <li id="j_off"><tt>-joff</tt> &mdash; Turns the JIT compiler off (only use the interpreter).</li>
 113 <li id="j_flush"><tt>-jflush</tt> &mdash; Flushes the whole cache of compiled code.</li>
 114 <li id="j_v"><tt>-jv</tt> &mdash; Shows verbose information about the progress of the JIT compiler.</li>
 115 <li id="j_dump"><tt>-jdump</tt> &mdash; Dumps the code and structures used in various compiler stages.</li>
 116 </ul>
 117 <p>
 118 The <tt>-jv</tt> and <tt>-jdump</tt> commands are extension modules
 119 written in Lua. They are mainly used for debugging the JIT compiler
 120 itself. For a description of their options and output format, please
 121 read the comment block at the start of their source.
 122 They can be found in the <tt>lib</tt> directory of the source
 123 distribution or installed under the <tt>jit</tt> directory. By default
 124 this is <tt>/usr/local/share/luajit-2.0.0-beta5/jit</tt> on POSIX
 125 systems.
 126 </p>
 127
 128 <h3 id="opt_O"><tt>-O[level]</tt><br>
 129 <tt>-O[+]flag</tt> <tt>-O-flag</tt><br>
 130 <tt>-Oparam=value</tt></h3>
 131 <p>
 132 This options allows fine-tuned control of the optimizations used by
 133 the JIT compiler. This is mainly intended for debugging LuaJIT itself.
 134 Please note that the JIT compiler is extremely fast (we are talking
 135 about the microsecond to millisecond range). Disabling optimizations
 136 doesn't have any visible impact on its overhead, but usually generates
 137 code that runs slower.
 138 </p>
 139 <p>
 140 The first form sets an optimization level &mdash; this enables a
 141 specific mix of optimization flags. <tt>-O0</tt> turns off all
 142 optimizations and higher numbers enable more optimizations. Omitting
 143 the level (i.e. just <tt>-O</tt>) sets the default optimization level,
 144 which is <tt>-O3</tt> in the current version.
 145 </p>
 146 <p>
 147 The second form adds or removes individual optimization flags.
 148 The third form sets a parameter for the VM or the JIT compiler
 149 to a specific value.
 150 </p>
 151 <p>
 152 You can either use this option multiple times (like <tt>-Ocse
 153 -O-dce -Ohotloop=10</tt>) or separate several settings with a comma
 154 (like <tt>-O+cse,-dce,hotloop=10</tt>). The settings are applied from
 155 left to right and later settings override earlier ones. You can freely
 156 mix the three forms, but note that setting an optimization level
 157 overrides all earlier flags.
 158 </p>
 159 <p>
 160 Here are the available flags and at what optimization levels they
 161 are enabled:
 162 </p>
 163 <table class="opt">
 164 <tr class="opthead">
 165 <td class="flag_name">Flag</td>
 166 <td class="flag_level">-O1</td>
 167 <td class="flag_level">-O2</td>
 168 <td class="flag_level">-O3</td>
 169 <td class="flag_desc">&nbsp;</td>
 170 </tr>
 171 <tr class="odd separate">
 172 <td class="flag_name">fold</td><td class="flag_level">&bull;</td><td class="flag_level">&bull;</td><td class="flag_level">&bull;</td><td class="flag_desc">Constant Folding, Simplifications and Reassociation</td></tr>
 173 <tr class="even">
 174 <td class="flag_name">cse</td><td class="flag_level">&bull;</td><td class="flag_level">&bull;</td><td class="flag_level">&bull;</td><td class="flag_desc">Common-Subexpression Elimination</td></tr>
 175 <tr class="odd">
 176 <td class="flag_name">dce</td><td class="flag_level">&bull;</td><td class="flag_level">&bull;</td><td class="flag_level">&bull;</td><td class="flag_desc">Dead-Code Elimination</td></tr>
 177 <tr class="even">
 178 <td class="flag_name">narrow</td><td class="flag_level">&nbsp;</td><td class="flag_level">&bull;</td><td class="flag_level">&bull;</td><td class="flag_desc">Narrowing of numbers to integers</td></tr>
 179 <tr class="odd">
 180 <td class="flag_name">loop</td><td class="flag_level">&nbsp;</td><td class="flag_level">&bull;</td><td class="flag_level">&bull;</td><td class="flag_desc">Loop Optimizations (code hoisting)</td></tr>
 181 <tr class="even">
 182 <td class="flag_name">fwd</td><td class="flag_level">&nbsp;</td><td class="flag_level">&nbsp;</td><td class="flag_level">&bull;</td><td class="flag_desc">Load Forwarding (L2L) and Store Forwarding (S2L)</td></tr>
 183 <tr class="odd">
 184 <td class="flag_name">dse</td><td class="flag_level">&nbsp;</td><td class="flag_level">&nbsp;</td><td class="flag_level">&bull;</td><td class="flag_desc">Dead-Store Elimination</td></tr>
 185 <tr class="even">
 186 <td class="flag_name">abc</td><td class="flag_level">&nbsp;</td><td class="flag_level">&nbsp;</td><td class="flag_level">&bull;</td><td class="flag_desc">Array Bounds Check Elimination</td></tr>
 187 <tr class="odd">
 188 <td class="flag_name">fuse</td><td class="flag_level">&nbsp;</td><td class="flag_level">&nbsp;</td><td class="flag_level">&bull;</td><td class="flag_desc">Fusion of operands into instructions</td></tr>
 189 </table>
 190 <p>
 191 Here are the parameters and their default settings:
 192 </p>
 193 <table class="opt">
 194 <tr class="opthead">
 195 <td class="param_name">Parameter</td>
 196 <td class="param_default">Default</td>
 197 <td class="param_desc">&nbsp;</td>
 198 </tr>
 199 <tr class="odd separate">
 200 <td class="param_name">maxtrace</td><td class="param_default">1000</td><td class="param_desc">Max. number of traces in the cache</td></tr>
 201 <tr class="even">
 202 <td class="param_name">maxrecord</td><td class="param_default">2000</td><td class="param_desc">Max. number of recorded IR instructions</td></tr>
 203 <tr class="odd">
 204 <td class="param_name">maxirconst</td><td class="param_default">500</td><td class="param_desc">Max. number of IR constants of a trace</td></tr>
 205 <tr class="even">
 206 <td class="param_name">maxside</td><td class="param_default">100</td><td class="param_desc">Max. number of side traces of a root trace</td></tr>
 207 <tr class="odd">
 208 <td class="param_name">maxsnap</td><td class="param_default">100</td><td class="param_desc">Max. number of snapshots for a trace</td></tr>
 209 <tr class="even separate">
 210 <td class="param_name">hotloop</td><td class="param_default">56</td><td class="param_desc">Number of iterations to detect a hot loop or hot call</td></tr>
 211 <tr class="odd">
 212 <td class="param_name">hotexit</td><td class="param_default">10</td><td class="param_desc">Number of taken exits to start a side trace</td></tr>
 213 <tr class="even">
 214 <td class="param_name">tryside</td><td class="param_default">4</td><td class="param_desc">Number of attempts to compile a side trace</td></tr>
 215 <tr class="odd separate">
 216 <td class="param_name">instunroll</td><td class="param_default">4</td><td class="param_desc">Max. unroll factor for instable loops</td></tr>
 217 <tr class="even">
 218 <td class="param_name">loopunroll</td><td class="param_default">7</td><td class="param_desc">Max. unroll factor for loop ops in side traces</td></tr>
 219 <tr class="odd">
 220 <td class="param_name">callunroll</td><td class="param_default">3</td><td class="param_desc">Max. unroll factor for pseudo-recursive calls</td></tr>
 221 <tr class="even">
 222 <td class="param_name">recunroll</td><td class="param_default">2</td><td class="param_desc">Min. unroll factor for true recursion</td></tr>
 223 <tr class="odd separate">
 224 <td class="param_name">sizemcode</td><td class="param_default">32</td><td class="param_desc">Size of each machine code area in KBytes (Windows: 64K)</td></tr>
 225 <tr class="even">
 226 <td class="param_name">maxmcode</td><td class="param_default">512</td><td class="param_desc">Max. total size of all machine code areas in KBytes</td></tr>
 227 </table>
 228 <br class="flush">
 229 </div>
 230 <div id="foot">
 231 <hr class="hide">
 232 Copyright &copy; 2005-2010 Mike Pall
 233 <span class="noprint">
 234 &middot;
 235 <a href="contact.html">Contact</a>
 236 </span>
 237 </div>
 238 </body>
 239 </html>