Mercurial

comparison third_party/luajit/doc/running.html @ 186:8cf4ec5e2191 hg-web

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Fixed merge conflict.
author MrJuneJune <me@mrjunejune.com>
date Fri, 23 Jan 2026 22:38:59 -0800
parents 94705b5986b3
children
comparison
equal deleted inserted replaced
176:fed99fc04e12 186:8cf4ec5e2191
1 <!DOCTYPE html>
2 <html>
3 <head>
4 <title>Running LuaJIT</title>
5 <meta charset="utf-8">
6 <meta name="Copyright" content="Copyright (C) 2005-2023">
7 <meta name="Language" content="en">
8 <link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
9 <link rel="stylesheet" type="text/css" href="bluequad-print.css" media="print">
10 <style type="text/css">
11 table.opt {
12 line-height: 1.2;
13 }
14 tr.opthead td {
15 font-weight: bold;
16 }
17 td.flag_name {
18 width: 4em;
19 }
20 td.flag_level {
21 width: 2em;
22 text-align: center;
23 }
24 td.param_name {
25 width: 6em;
26 }
27 td.param_default {
28 width: 4em;
29 text-align: right;
30 }
31 </style>
32 </head>
33 <body>
34 <div id="site">
35 <a href="https://luajit.org"><span>Lua<span id="logo">JIT</span></span></a>
36 </div>
37 <div id="head">
38 <h1>Running LuaJIT</h1>
39 </div>
40 <div id="nav">
41 <ul><li>
42 <a href="luajit.html">LuaJIT</a>
43 <ul><li>
44 <a href="https://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
45 </li><li>
46 <a href="install.html">Installation</a>
47 </li><li>
48 <a class="current" href="running.html">Running</a>
49 </li></ul>
50 </li><li>
51 <a href="extensions.html">Extensions</a>
52 <ul><li>
53 <a href="ext_ffi.html">FFI Library</a>
54 <ul><li>
55 <a href="ext_ffi_tutorial.html">FFI Tutorial</a>
56 </li><li>
57 <a href="ext_ffi_api.html">ffi.* API</a>
58 </li><li>
59 <a href="ext_ffi_semantics.html">FFI Semantics</a>
60 </li></ul>
61 </li><li>
62 <a href="ext_buffer.html">String Buffers</a>
63 </li><li>
64 <a href="ext_jit.html">jit.* Library</a>
65 </li><li>
66 <a href="ext_c_api.html">Lua/C API</a>
67 </li><li>
68 <a href="ext_profiler.html">Profiler</a>
69 </li></ul>
70 </li><li>
71 <a href="https://luajit.org/status.html">Status <span class="ext">&raquo;</span></a>
72 </li><li>
73 <a href="https://luajit.org/faq.html">FAQ <span class="ext">&raquo;</span></a>
74 </li><li>
75 <a href="https://luajit.org/list.html">Mailing List <span class="ext">&raquo;</span></a>
76 </li></ul>
77 </div>
78 <div id="main">
79
80 <p>
81 LuaJIT has only a single stand-alone executable, called <tt>luajit</tt> on
82 POSIX systems or <tt>luajit.exe</tt> on Windows. It can be used to run simple
83 Lua statements or whole Lua applications from the command line. It has an
84 interactive mode, too.
85 </p>
86
87 <h2 id="options">Command Line Options</h2>
88 <p>
89 The <tt>luajit</tt> stand-alone executable is just a slightly modified
90 version of the regular <tt>lua</tt> stand-alone executable.
91 It supports the same basic options, too. <tt>luajit&nbsp;-h</tt>
92 prints a short list of the available options. Please have a look at the
93 <a href="https://www.lua.org/manual/5.1/manual.html#6"><span class="ext">&raquo;</span>&nbsp;Lua manual</a>
94 for details.
95 </p>
96 <p>
97 LuaJIT has some additional options:
98 </p>
99
100 <h3 id="opt_b"><tt>-b[options] input output</tt></h3>
101 <p>
102 This option saves or lists bytecode. The following additional options
103 are accepted:
104 </p>
105 <ul>
106 <li><tt>-l</tt> &mdash; Only list bytecode.</li>
107 <li><tt>-s</tt> &mdash; Strip debug info (this is the default).</li>
108 <li><tt>-g</tt> &mdash; Keep debug info.</li>
109 <li><tt>-n name</tt> &mdash; Set module name (default: auto-detect from input name)</li>
110 <li><tt>-t type</tt> &mdash; Set output file type (default: auto-detect from output name).</li>
111 <li><tt>-a arch</tt> &mdash; Override architecture for object files (default: native).</li>
112 <li><tt>-o os</tt> &mdash; Override OS for object files (default: native).</li>
113 <li><tt>-F name</tt> &mdash; Override filename (default: input filename).</li>
114 <li><tt>-e chunk</tt> &mdash; Use chunk string as input.</li>
115 <li><tt>-</tt> (a single minus sign) &mdash; Use stdin as input and/or stdout as output.</li>
116 </ul>
117 <p>
118 The output file type is auto-detected from the extension of the output
119 file name:
120 </p>
121 <ul>
122 <li><tt>c</tt> &mdash; C source file, exported bytecode data.</li>
123 <li><tt>h</tt> &mdash; C header file, static bytecode data.</li>
124 <li><tt>obj</tt> or <tt>o</tt> &mdash; Object file, exported bytecode data
125 (OS- and architecture-specific).</li>
126 <li><tt>raw</tt> or any other extension &mdash; Raw bytecode file (portable).
127 </ul>
128 <p>
129 Notes:
130 </p>
131 <ul>
132 <li>See also <a href="extensions.html#string_dump">string.dump()</a>
133 for information on bytecode portability and compatibility.</li>
134 <li>A file in raw bytecode format is auto-detected and can be loaded like
135 any Lua source file. E.g. directly from the command line or with
136 <tt>loadfile()</tt>, <tt>dofile()</tt> etc.</li>
137 <li>To statically embed the bytecode of a module in your application,
138 generate an object file and just link it with your application.</li>
139 <li>On most ELF-based systems (e.g. Linux) you need to explicitly export the
140 global symbols when linking your application, e.g. with: <tt>-Wl,-E</tt></li>
141 <li><tt>require()</tt> tries to load embedded bytecode data from exported
142 symbols (in <tt>*.exe</tt> or <tt>lua51.dll</tt> on Windows) and from
143 shared libraries in <tt>package.cpath</tt>.</li>
144 </ul>
145 <p>
146 Typical usage examples:
147 </p>
148 <pre class="code">
149 luajit -b test.lua test.out # Save bytecode to test.out
150 luajit -bg test.lua test.out # Keep debug info
151 luajit -be "print('hello world')" test.out # Save cmdline script
152
153 luajit -bl test.lua # List to stdout
154 luajit -bl test.lua test.txt # List to test.txt
155 luajit -ble "print('hello world')" # List cmdline script
156
157 luajit -b test.lua test.obj # Generate object file
158 # Link test.obj with your application and load it with require("test")
159 </pre>
160
161 <h3 id="opt_j"><tt>-j cmd[=arg[,arg...]]</tt></h3>
162 <p>
163 This option performs a LuaJIT control command or activates one of the
164 loadable extension modules. The command is first looked up in the
165 <tt>jit.*</tt> library. If no matching function is found, a module
166 named <tt>jit.&lt;cmd&gt;</tt> is loaded and the <tt>start()</tt>
167 function of the module is called with the specified arguments (if
168 any). The space between <tt>-j</tt> and <tt>cmd</tt> is optional.
169 </p>
170 <p>
171 Here are the available LuaJIT control commands:
172 </p>
173 <ul>
174 <li id="j_on"><tt>-jon</tt> &mdash; Turns the JIT compiler on (default).</li>
175 <li id="j_off"><tt>-joff</tt> &mdash; Turns the JIT compiler off (only use the interpreter).</li>
176 <li id="j_flush"><tt>-jflush</tt> &mdash; Flushes the whole cache of compiled code.</li>
177 <li id="j_v"><tt>-jv</tt> &mdash; Shows verbose information about the progress of the JIT compiler.</li>
178 <li id="j_dump"><tt>-jdump</tt> &mdash; Dumps the code and structures used in various compiler stages.</li>
179 <li id="j_p"><tt>-jp</tt> &mdash; Start the <a href="ext_profiler.html">integrated profiler</a>.</li>
180 </ul>
181 <p>
182 The <tt>-jv</tt> and <tt>-jdump</tt> commands are extension modules
183 written in Lua. They are mainly used for debugging the JIT compiler
184 itself. For a description of their options and output format, please
185 read the comment block at the start of their source.
186 They can be found in the <tt>lib</tt> directory of the source
187 distribution or installed under the <tt>jit</tt> directory. By default,
188 this is <tt>/usr/local/share/luajit-XX.YY.ZZ>/jit</tt> on POSIX
189 systems (replace XX.YY.ZZ by the installed version).
190 </p>
191
192 <h3 id="opt_O"><tt>-O[level]</tt><br>
193 <tt>-O[+]flag</tt>&nbsp;&nbsp;&nbsp;<tt>-O-flag</tt><br>
194 <tt>-Oparam=value</tt></h3>
195 <p>
196 This options allows fine-tuned control of the optimizations used by
197 the JIT compiler. This is mainly intended for debugging LuaJIT itself.
198 Please note that the JIT compiler is extremely fast (we are talking
199 about the microsecond to millisecond range). Disabling optimizations
200 doesn't have any visible impact on its overhead, but usually generates
201 code that runs slower.
202 </p>
203 <p>
204 The first form sets an optimization level &mdash; this enables a
205 specific mix of optimization flags. <tt>-O0</tt> turns off all
206 optimizations and higher numbers enable more optimizations. Omitting
207 the level (i.e. just <tt>-O</tt>) sets the default optimization level,
208 which is <tt>-O3</tt> in the current version.
209 </p>
210 <p>
211 The second form adds or removes individual optimization flags.
212 The third form sets a parameter for the VM or the JIT compiler
213 to a specific value.
214 </p>
215 <p>
216 You can either use this option multiple times (like <tt>-Ocse
217 -O-dce -Ohotloop=10</tt>) or separate several settings with a comma
218 (like <tt>-O+cse,-dce,hotloop=10</tt>). The settings are applied from
219 left to right, and later settings override earlier ones. You can freely
220 mix the three forms, but note that setting an optimization level
221 overrides all earlier flags.
222 </p>
223 <p>
224 Note that <tt>-Ofma</tt> is not enabled by default at any level,
225 because it affects floating-point result accuracy. Only enable this,
226 if you fully understand the trade-offs of FMA for performance (higher),
227 determinism (lower) and numerical accuracy (higher).
228 </p>
229 <p>
230 Here are the available flags and at what optimization levels they
231 are enabled:
232 </p>
233 <table class="opt">
234 <tr class="opthead">
235 <td class="flag_name">Flag</td>
236 <td class="flag_level">-O1</td>
237 <td class="flag_level">-O2</td>
238 <td class="flag_level">-O3</td>
239 <td class="flag_desc">&nbsp;</td>
240 </tr>
241 <tr class="odd separate">
242 <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>
243 <tr class="even">
244 <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>
245 <tr class="odd">
246 <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>
247 <tr class="even">
248 <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>
249 <tr class="odd">
250 <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>
251 <tr class="even">
252 <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>
253 <tr class="odd">
254 <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>
255 <tr class="even">
256 <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>
257 <tr class="odd">
258 <td class="flag_name">sink</td><td class="flag_level">&nbsp;</td><td class="flag_level">&nbsp;</td><td class="flag_level">&bull;</td><td class="flag_desc">Allocation/Store Sinking</td></tr>
259 <tr class="even">
260 <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>
261 <tr class="odd">
262 <td class="flag_name">fma </td><td class="flag_level">&nbsp;</td><td class="flag_level">&nbsp;</td><td class="flag_level">&nbsp;</td><td class="flag_desc">Fused multiply-add</td></tr>
263 </table>
264 <p>
265 Here are the parameters and their default settings:
266 </p>
267 <table class="opt">
268 <tr class="opthead">
269 <td class="param_name">Parameter</td>
270 <td class="param_default">Default</td>
271 <td class="param_desc">&nbsp;</td>
272 </tr>
273 <tr class="odd separate">
274 <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>
275 <tr class="even">
276 <td class="param_name">maxrecord</td><td class="param_default">4000</td><td class="param_desc">Max. number of recorded IR instructions</td></tr>
277 <tr class="odd">
278 <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>
279 <tr class="even">
280 <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>
281 <tr class="odd">
282 <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>
283 <tr class="even separate">
284 <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>
285 <tr class="odd">
286 <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>
287 <tr class="even">
288 <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>
289 <tr class="odd separate">
290 <td class="param_name">instunroll</td><td class="param_default">4</td><td class="param_desc">Max. unroll factor for instable loops</td></tr>
291 <tr class="even">
292 <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>
293 <tr class="odd">
294 <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>
295 <tr class="even">
296 <td class="param_name">recunroll</td><td class="param_default">2</td><td class="param_desc">Min. unroll factor for true recursion</td></tr>
297 <tr class="odd separate">
298 <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>
299 <tr class="even">
300 <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>
301 </table>
302 <br class="flush">
303 </div>
304 <div id="foot">
305 <hr class="hide">
306 Copyright &copy; 2005-2023
307 <span class="noprint">
308 &middot;
309 <a href="contact.html">Contact</a>
310 </span>
311 </div>
312 </body>
313 </html>