summaryrefslogtreecommitdiff
path: root/doc/running.html
diff options
context:
space:
mode:
Diffstat (limited to 'doc/running.html')
-rw-r--r--doc/running.html233
1 files changed, 233 insertions, 0 deletions
diff --git a/doc/running.html b/doc/running.html
new file mode 100644
index 00000000..db69578c
--- /dev/null
+++ b/doc/running.html
@@ -0,0 +1,233 @@
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-2009, 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">
12table.opt {
13 line-height: 1.2;
14}
15tr.opthead td {
16 font-weight: bold;
17}
18td.flag_name {
19 width: 4em;
20}
21td.flag_level {
22 width: 2em;
23 text-align: center;
24}
25td.param_name {
26 width: 6em;
27}
28td.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/download.html">Download <span class="ext">&raquo;</span></a>
60</li></ul>
61</div>
62<div id="main">
63<p>
64LuaJIT has only a single stand-alone executable, called <tt>luajit</tt> on
65POSIX systems or <tt>luajit.exe</tt> on Windows. It can be used to run simple
66Lua statements or whole Lua applications from the command line. It has an
67interactive mode, too.
68</p>
69<p class="indent" style="color: #c00000;">
70Note: the beta test releases only install under the versioned name on
71POSIX systems (to avoid overwriting a previous version). You either need
72to type <tt>luajit-2.0.0-beta1</tt> to start it or create a symlink
73with a command like this:
74</p>
75<pre class="code" style="color: #c00000;">
76sudo ln -sf luajit-2.0.0-beta1 /usr/local/bin/luajit
77</pre>
78<p>
79Unlike previous versions <b>optimization is turned on by default</b> in
80LuaJIT 2.0!<br>It's no longer necessary to use <tt>luajit&nbsp;-O</tt>.
81</p>
82
83<h2 id="options">Command Line Options</h2>
84<p>
85The <tt>luajit</tt> stand-alone executable is just a slightly modified
86version of the regular <tt>lua</tt> stand-alone executable.
87It supports the same basic options, too. <tt>luajit&nbsp;-h</tt>
88prints a short list of the available options. Please have a look at the
89<a href="http://www.lua.org/manual/5.1/manual.html#6"><span class="ext">&raquo;</span>&nbsp;Lua manual</a>
90for details.
91</p>
92<p>
93Two additional options control the behavior of LuaJIT:
94</p>
95
96<h3 id="opt_j"><tt>-j cmd[=arg[,arg...]]</tt></h3>
97<p>
98This option performs a LuaJIT control command or activates one of the
99loadable extension modules. The command is first looked up in the
100<tt>jit.*</tt> library. If no matching function is found, a module
101named <tt>jit.&lt;cmd&gt;</tt> is loaded and the <tt>start()</tt>
102function of the module is called with the specified arguments (if
103any). The space between <tt>-j</tt> and <tt>cmd</tt> is optional.
104</p>
105<p>
106Here are the available LuaJIT control commands:
107</p>
108<ul>
109<li id="j_on"><tt>-jon</tt> &mdash; Turns the JIT compiler on (default).</li>
110<li id="j_off"><tt>-joff</tt> &mdash; Turns the JIT compiler off (only use the interpreter).</li>
111<li id="j_flush"><tt>-jflush</tt> &mdash; Flushes the whole cache of compiled code.</li>
112<li id="j_v"><tt>-jv</tt> &mdash; Shows verbose information about the progress of the JIT compiler.</li>
113<li id="j_dump"><tt>-jdump</tt> &mdash; Dumps the code and structures used in various compiler stages.</li>
114</ul>
115<p>
116The <tt>-jv</tt> and <tt>-jdump</tt> commands are extension modules
117written in Lua. They are mainly used for debugging the JIT compiler
118itself. For a description of their options and output format, please
119read the comment block at the start of their source.
120They can be found in the <tt>lib</tt> directory of the source
121distribution or installed under the <tt>jit</tt> directory. By default
122this is <tt>/usr/local/share/luajit-2.0.0-beta1/jit</tt> on POSIX
123systems.
124</p>
125
126<h3 id="opt_O"><tt>-O[level]</tt><br>
127<tt>-O[+]flag</tt> <tt>-O-flag</tt><br>
128<tt>-Oparam=value</tt></h3>
129<p>
130This options allows fine-tuned control of the optimizations used by
131the JIT compiler. This is mainly intended for debugging LuaJIT itself.
132Please note that the JIT compiler is extremly fast (we are talking
133about the microsecond to millisecond range). Disabling optimizations
134doesn't have any visible impact on its overhead, but usually generates
135code that runs slower.
136</p>
137<p>
138The first form sets an optimization level &mdash; this enables a
139specific mix of optimization flags. <tt>-O0</tt> turns off all
140optimizations and higher numbers enable more optimizations. Omitting
141the level (i.e. just <tt>-O</tt>) sets the default optimization level,
142which is <tt>-O3</tt> in the current version.
143</p>
144<p>
145The second form adds or removes individual optimization flags.
146The third form sets a parameter for the VM or the JIT compiler
147to a specific value.
148</p>
149<p>
150You can either use this option multiple times (like <tt>-Ocse
151-O-dce -Ohotloop=10</tt>) or separate several settings with a comma
152(like <tt>-O+cse,-dce,hotloop=10</tt>). The settings are applied from
153left to right and later settings override earlier ones. You can freely
154mix the three forms, but note that setting an optimization level
155overrides all earlier flags.
156</p>
157<p>
158Here are the available flags and at what optimization levels they
159are enabled:
160</p>
161<table class="opt">
162<tr class="opthead">
163<td class="flag_name">Flag</td>
164<td class="flag_level">-O1</td>
165<td class="flag_level">-O2</td>
166<td class="flag_level">-O3</td>
167<td class="flag_desc">&nbsp;</td>
168</tr>
169<tr class="odd separate">
170<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>
171<tr class="even">
172<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>
173<tr class="odd">
174<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>
175<tr class="even">
176<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>
177<tr class="odd">
178<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>
179<tr class="even">
180<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>
181<tr class="odd">
182<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>
183<tr class="even">
184<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>
185</table>
186<p>
187Here are the parameters and their default settings:
188</p>
189<table class="opt">
190<tr class="opthead">
191<td class="param_name">Parameter</td>
192<td class="param_default">Default</td>
193<td class="param_desc">&nbsp;</td>
194</tr>
195<tr class="odd separate">
196<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>
197<tr class="even">
198<td class="param_name">maxrecord</td><td class="param_default">2000</td><td class="param_desc">Max. number of recorded IR instructions</td></tr>
199<tr class="odd">
200<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>
201<tr class="even">
202<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>
203<tr class="odd">
204<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>
205<tr class="even separate">
206<td class="param_name">hotloop</td><td class="param_default">57</td><td class="param_desc">Number of iterations to detect a hot loop</td></tr>
207<tr class="odd">
208<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>
209<tr class="even">
210<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>
211<tr class="odd separate">
212<td class="param_name">instunroll</td><td class="param_default">4</td><td class="param_desc">Max. unroll factor for instable loops</td></tr>
213<tr class="even">
214<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>
215<tr class="odd">
216<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>
217<tr class="even separate">
218<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>
219<tr class="odd">
220<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>
221</table>
222<br class="flush">
223</div>
224<div id="foot">
225<hr class="hide">
226Copyright &copy; 2005-2009 Mike Pall
227<span class="noprint">
228&middot;
229<a href="contact.html">Contact</a>
230</span>
231</div>
232</body>
233</html>
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-03-16 21:58:06 +0000