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-2011, 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></ul>
  49 </li><li>
  50 <a href="extensions.html">Extensions</a>
  51 <ul><li>
  52 <a href="ext_ffi.html">FFI Library</a>
  53 <ul><li>
  54 <a href="ext_ffi_tutorial.html">FFI Tutorial</a>
  55 </li><li>
  56 <a href="ext_ffi_api.html">ffi.* API</a>
  57 </li><li>
  58 <a href="ext_ffi_semantics.html">FFI Semantics</a>
  59 </li></ul>
  60 </li><li>
  61 <a href="ext_jit.html">jit.* Library</a>
  62 </li><li>
  63 <a href="ext_c_api.html">Lua/C API</a>
  64 </li></ul>
  65 </li><li>
  66 <a href="status.html">Status</a>
  67 <ul><li>
  68 <a href="changes.html">Changes</a>
  69 </li></ul>
  70 </li><li>
  71 <a href="faq.html">FAQ</a>
  72 </li><li>
  73 <a href="http://luajit.org/performance.html">Performance <span class="ext">&raquo;</span></a>
  74 </li><li>
  75 <a href="http://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
  76 </li></ul>
  77 </div>
  78 <div id="main">
  79 <p>
  80 LuaJIT has only a single stand-alone executable, called <tt>luajit</tt> on
  81 POSIX systems or <tt>luajit.exe</tt> on Windows. It can be used to run simple
  82 Lua statements or whole Lua applications from the command line. It has an
  83 interactive mode, too.
  84 </p>
  85 <p class="indent" style="color: #c00000;">
  86 Note: the beta test releases only install under the versioned name on
  87 POSIX systems (to avoid overwriting a previous version). You either need
  88 to type <tt>luajit-2.0.0-beta8</tt> to start it or create a symlink
  89 with a command like this:
  90 </p>
  91 <pre class="code" style="color: #c00000;">
  92 sudo ln -sf luajit-2.0.0-beta8&nbsp;/usr/local/bin/luajit
  93 </pre>
  94 <p>
  95 Unlike previous versions <b>optimization is turned on by default</b> in
  96 LuaJIT 2.0!<br>It's no longer necessary to use <tt>luajit&nbsp;-O</tt>.
  97 </p>
  98
  99 <h2 id="options">Command Line Options</h2>
 100 <p>
 101 The <tt>luajit</tt> stand-alone executable is just a slightly modified
 102 version of the regular <tt>lua</tt> stand-alone executable.
 103 It supports the same basic options, too. <tt>luajit&nbsp;-h</tt>
 104 prints a short list of the available options. Please have a look at the
 105 <a href="http://www.lua.org/manual/5.1/manual.html#6"><span class="ext">&raquo;</span>&nbsp;Lua manual</a>
 106 for details.
 107 </p>
 108 <p>
 109 LuaJIT has some additional options:
 110 </p>
 111
 112 <h3 id="opt_b"><tt>-b[options] input output</tt></h3>
 113 <p>
 114 This option saves or lists bytecode. The following additional options
 115 are accepted:
 116 </p>
 117 <ul>
 118 <li><tt>-l</tt> &mdash; Only list bytecode.</li>
 119 <li><tt>-s</tt> &mdash; Strip debug info (this is the default).</li>
 120 <li><tt>-g</tt> &mdash; Keep debug info.</li>
 121 <li><tt>-e chunk</tt> &mdash; Use chunk string as input.</li>
 122 <li><tt>-</tt> (a single minus sign) &mdash; Use stdin as input and/or stdout as output.</li>
 123 </ul>
 124 <p>
 125 Typical usage examples:
 126 </p>
 127 <pre class="code">
 128 luajit -b test.lua test.out                     # Save to test.out
 129 luajit -bg test.lua test.out                    # Keep debug info
 130 luajit -be "print('hello world') end" test.out  # Save cmdline script
 131
 132 luajit -bl test.lua                             # List to stdout
 133 luajit -bl test.lua test.txt                    # List to test.txt
 134 luajit -ble "print('hello world') end"          # List cmdline script
 135 </pre>
 136 <p>
 137 Note: A file in bytecode format is auto-detected and can be loaded like
 138 any Lua source file. E.g. directly from the command line or with
 139 <tt>loadfile()</tt>, <tt>dofile()</tt> etc. See also
 140 <a href="extensions.html#string_dump">string.dump()</a> for information
 141 on bytecode portability and compatibility.
 142 </p>
 143
 144 <h3 id="opt_j"><tt>-j cmd[=arg[,arg...]]</tt></h3>
 145 <p>
 146 This option performs a LuaJIT control command or activates one of the
 147 loadable extension modules. The command is first looked up in the
 148 <tt>jit.*</tt> library. If no matching function is found, a module
 149 named <tt>jit.&lt;cmd&gt;</tt> is loaded and the <tt>start()</tt>
 150 function of the module is called with the specified arguments (if
 151 any). The space between <tt>-j</tt> and <tt>cmd</tt> is optional.
 152 </p>
 153 <p>
 154 Here are the available LuaJIT control commands:
 155 </p>
 156 <ul>
 157 <li id="j_on"><tt>-jon</tt> &mdash; Turns the JIT compiler on (default).</li>
 158 <li id="j_off"><tt>-joff</tt> &mdash; Turns the JIT compiler off (only use the interpreter).</li>
 159 <li id="j_flush"><tt>-jflush</tt> &mdash; Flushes the whole cache of compiled code.</li>
 160 <li id="j_v"><tt>-jv</tt> &mdash; Shows verbose information about the progress of the JIT compiler.</li>
 161 <li id="j_dump"><tt>-jdump</tt> &mdash; Dumps the code and structures used in various compiler stages.</li>
 162 </ul>
 163 <p>
 164 The <tt>-jv</tt> and <tt>-jdump</tt> commands are extension modules
 165 written in Lua. They are mainly used for debugging the JIT compiler
 166 itself. For a description of their options and output format, please
 167 read the comment block at the start of their source.
 168 They can be found in the <tt>lib</tt> directory of the source
 169 distribution or installed under the <tt>jit</tt> directory. By default
 170 this is <tt>/usr/local/share/luajit-2.0.0-beta8/jit</tt> on POSIX
 171 systems.
 172 </p>
 173
 174 <h3 id="opt_O"><tt>-O[level]</tt><br>
 175 <tt>-O[+]flag</tt>&nbsp;&nbsp;&nbsp;<tt>-O-flag</tt><br>
 176 <tt>-Oparam=value</tt></h3>
 177 <p>
 178 This options allows fine-tuned control of the optimizations used by
 179 the JIT compiler. This is mainly intended for debugging LuaJIT itself.
 180 Please note that the JIT compiler is extremely fast (we are talking
 181 about the microsecond to millisecond range). Disabling optimizations
 182 doesn't have any visible impact on its overhead, but usually generates
 183 code that runs slower.
 184 </p>
 185 <p>
 186 The first form sets an optimization level &mdash; this enables a
 187 specific mix of optimization flags. <tt>-O0</tt> turns off all
 188 optimizations and higher numbers enable more optimizations. Omitting
 189 the level (i.e. just <tt>-O</tt>) sets the default optimization level,
 190 which is <tt>-O3</tt> in the current version.
 191 </p>
 192 <p>
 193 The second form adds or removes individual optimization flags.
 194 The third form sets a parameter for the VM or the JIT compiler
 195 to a specific value.
 196 </p>
 197 <p>
 198 You can either use this option multiple times (like <tt>-Ocse
 199 -O-dce -Ohotloop=10</tt>) or separate several settings with a comma
 200 (like <tt>-O+cse,-dce,hotloop=10</tt>). The settings are applied from
 201 left to right and later settings override earlier ones. You can freely
 202 mix the three forms, but note that setting an optimization level
 203 overrides all earlier flags.
 204 </p>
 205 <p>
 206 Here are the available flags and at what optimization levels they
 207 are enabled:
 208 </p>
 209 <table class="opt">
 210 <tr class="opthead">
 211 <td class="flag_name">Flag</td>
 212 <td class="flag_level">-O1</td>
 213 <td class="flag_level">-O2</td>
 214 <td class="flag_level">-O3</td>
 215 <td class="flag_desc">&nbsp;</td>
 216 </tr>
 217 <tr class="odd separate">
 218 <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>
 219 <tr class="even">
 220 <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>
 221 <tr class="odd">
 222 <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>
 223 <tr class="even">
 224 <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>
 225 <tr class="odd">
 226 <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>
 227 <tr class="even">
 228 <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>
 229 <tr class="odd">
 230 <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>
 231 <tr class="even">
 232 <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>
 233 <tr class="odd">
 234 <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>
 235 </table>
 236 <p>
 237 Here are the parameters and their default settings:
 238 </p>
 239 <table class="opt">
 240 <tr class="opthead">
 241 <td class="param_name">Parameter</td>
 242 <td class="param_default">Default</td>
 243 <td class="param_desc">&nbsp;</td>
 244 </tr>
 245 <tr class="odd separate">
 246 <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>
 247 <tr class="even">
 248 <td class="param_name">maxrecord</td><td class="param_default">4000</td><td class="param_desc">Max. number of recorded IR instructions</td></tr>
 249 <tr class="odd">
 250 <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>
 251 <tr class="even">
 252 <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>
 253 <tr class="odd">
 254 <td class="param_name">maxsnap</td><td class="param_default">500</td><td class="param_desc">Max. number of snapshots for a trace</td></tr>
 255 <tr class="even separate">
 256 <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>
 257 <tr class="odd">
 258 <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>
 259 <tr class="even">
 260 <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>
 261 <tr class="odd separate">
 262 <td class="param_name">instunroll</td><td class="param_default">4</td><td class="param_desc">Max. unroll factor for instable loops</td></tr>
 263 <tr class="even">
 264 <td class="param_name">loopunroll</td><td class="param_default">15</td><td class="param_desc">Max. unroll factor for loop ops in side traces</td></tr>
 265 <tr class="odd">
 266 <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>
 267 <tr class="even">
 268 <td class="param_name">recunroll</td><td class="param_default">2</td><td class="param_desc">Min. unroll factor for true recursion</td></tr>
 269 <tr class="odd separate">
 270 <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>
 271 <tr class="even">
 272 <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>
 273 </table>
 274 <br class="flush">
 275 </div>
 276 <div id="foot">
 277 <hr class="hide">
 278 Copyright &copy; 2005-2011 Mike Pall
 279 <span class="noprint">
 280 &middot;
 281 <a href="contact.html">Contact</a>
 282 </span>
 283 </div>
 284 </body>
 285 </html>