aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/contact.html8
-rw-r--r--doc/ext_buffer.html275
-rw-r--r--doc/ext_c_api.html8
-rw-r--r--doc/ext_ffi.html8
-rw-r--r--doc/ext_ffi_api.html16
-rw-r--r--doc/ext_ffi_semantics.html35
-rw-r--r--doc/ext_ffi_tutorial.html8
-rw-r--r--doc/ext_jit.html10
-rw-r--r--doc/ext_profiler.html361
-rw-r--r--doc/extensions.html112
-rw-r--r--doc/faq.html8
-rw-r--r--doc/install.html166
-rw-r--r--doc/luajit.html14
-rw-r--r--doc/running.html9
-rw-r--r--doc/status.html16
15 files changed, 934 insertions, 120 deletions
diff --git a/doc/contact.html b/doc/contact.html
index ba45a03a..c253a08b 100644
--- a/doc/contact.html
+++ b/doc/contact.html
@@ -1,8 +1,8 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> 1<!DOCTYPE html>
2<html> 2<html>
3<head> 3<head>
4<title>Contact</title> 4<title>Contact</title>
5<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> 5<meta charset="utf-8">
6<meta name="Copyright" content="Copyright (C) 2005-2021"> 6<meta name="Copyright" content="Copyright (C) 2005-2021">
7<meta name="Language" content="en"> 7<meta name="Language" content="en">
8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen"> 8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
@@ -37,9 +37,13 @@
37<a href="ext_ffi_semantics.html">FFI Semantics</a> 37<a href="ext_ffi_semantics.html">FFI Semantics</a>
38</li></ul> 38</li></ul>
39</li><li> 39</li><li>
40<a href="ext_buffer.html">String Buffers</a>
41</li><li>
40<a href="ext_jit.html">jit.* Library</a> 42<a href="ext_jit.html">jit.* Library</a>
41</li><li> 43</li><li>
42<a href="ext_c_api.html">Lua/C API</a> 44<a href="ext_c_api.html">Lua/C API</a>
45</li><li>
46<a href="ext_profiler.html">Profiler</a>
43</li></ul> 47</li></ul>
44</li><li> 48</li><li>
45<a href="status.html">Status</a> 49<a href="status.html">Status</a>
diff --git a/doc/ext_buffer.html b/doc/ext_buffer.html
new file mode 100644
index 00000000..455c298d
--- /dev/null
+++ b/doc/ext_buffer.html
@@ -0,0 +1,275 @@
1<!DOCTYPE html>
2<html>
3<head>
4<title>String Buffers</title>
5<meta charset="utf-8">
6<meta name="Copyright" content="Copyright (C) 2005-2021">
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</head>
11<body>
12<div id="site">
13<a href="https://luajit.org"><span>Lua<span id="logo">JIT</span></span></a>
14</div>
15<div id="head">
16<h1>String Buffers</h1>
17</div>
18<div id="nav">
19<ul><li>
20<a href="luajit.html">LuaJIT</a>
21<ul><li>
22<a href="https://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
23</li><li>
24<a href="install.html">Installation</a>
25</li><li>
26<a href="running.html">Running</a>
27</li></ul>
28</li><li>
29<a href="extensions.html">Extensions</a>
30<ul><li>
31<a href="ext_ffi.html">FFI Library</a>
32<ul><li>
33<a href="ext_ffi_tutorial.html">FFI Tutorial</a>
34</li><li>
35<a href="ext_ffi_api.html">ffi.* API</a>
36</li><li>
37<a href="ext_ffi_semantics.html">FFI Semantics</a>
38</li></ul>
39</li><li>
40<a class="current" href="ext_buffer.html">String Buffers</a>
41</li><li>
42<a href="ext_jit.html">jit.* Library</a>
43</li><li>
44<a href="ext_c_api.html">Lua/C API</a>
45</li><li>
46<a href="ext_profiler.html">Profiler</a>
47</li></ul>
48</li><li>
49<a href="status.html">Status</a>
50</li><li>
51<a href="faq.html">FAQ</a>
52</li><li>
53<a href="http://wiki.luajit.org/">Wiki <span class="ext">&raquo;</span></a>
54</li><li>
55<a href="https://luajit.org/list.html">Mailing List <span class="ext">&raquo;</span></a>
56</li></ul>
57</div>
58<div id="main">
59<p>
60
61The string buffer library allows <b>high-performance manipulation of
62string-like data</b>.
63
64</p>
65<p>
66
67Unlike Lua strings, which are constants, string buffers are
68<b>mutable</b> sequences of 8-bit (binary-transparent) characters. Data
69can be stored, formatted and encoded into a string buffer and later
70converted, decoded or extracted.
71
72</p>
73<p>
74
75The convenient string buffer API simplifies common string manipulation
76tasks, that would otherwise require creating many intermediate strings.
77String buffers improve performance by eliminating redundant memory
78copies, object creation, string interning and garbage collection
79overhead. In conjunction with the FFI library, they allow zero-copy
80operations.
81
82</p>
83
84<h2 id="load">Using the String Buffer Library</h2>
85<p>
86The string buffer library is built into LuaJIT by default, but it's not
87loaded by default. Add this to the start of every Lua file that needs
88one of its functions:
89</p>
90<pre class="code">
91local buffer = require("string.buffer")
92</pre>
93
94<h2 id="wip" style="color:#ff0000">Work in Progress</h2>
95
96<p>
97
98<b style="color:#ff0000">This library is a work in progress. More
99functions will be added soon.</b>
100
101</p>
102
103<h2 id="serialize">Serialization of Lua Objects</h2>
104<p>
105
106The following functions and methods allow <b>high-speed serialization</b>
107(encoding) of a Lua object into a string and decoding it back to a Lua
108object. This allows convenient storage and transport of <b>structured
109data</b>.
110
111</p>
112<p>
113
114The encoded data is in an <a href="#serialize_format">internal binary
115format</a>. The data can be stored in files, binary-transparent
116databases or transmitted to other LuaJIT instances across threads,
117processes or networks.
118
119</p>
120<p>
121
122Encoding speed can reach up to 1 Gigabyte/second on a modern desktop- or
123server-class system, even when serializing many small objects. Decoding
124speed is mostly constrained by object creation cost.
125
126</p>
127<p>
128
129The serializer handles most Lua types, common FFI number types and
130nested structures. Functions, thread objects, other FFI cdata, full
131userdata and associated metatables cannot be serialized (yet).
132
133</p>
134<p>
135
136The encoder serializes nested structures as trees. Multiple references
137to a single object will be stored separately and create distinct objects
138after decoding. Circular references cause an error.
139
140
141</p>
142
143<h3 id="buffer_encode"><tt>str = buffer.encode(obj)</tt></h3>
144<p>
145
146Serializes (encodes) the Lua object <tt>obj</tt> into the string
147<tt>str</tt>.
148
149</p>
150<p>
151
152<tt>obj</tt> can be any of the supported Lua types &mdash; it doesn't
153need to be a Lua table.
154
155</p>
156<p>
157
158This function may throw an error when attempting to serialize
159unsupported object types, circular references or deeply nested tables.
160
161</p>
162
163<h3 id="buffer_decode"><tt>obj = buffer.decode(str)</tt></h3>
164<p>
165
166De-serializes (decodes) the string <tt>str</tt> into the Lua object
167<tt>obj</tt>.
168
169</p>
170<p>
171
172The returned object may be any of the supported Lua types &mdash;
173even <tt>nil</tt>.
174
175</p>
176<p>
177
178This function may throw an error when fed with malformed or incomplete
179encoded data. The standalone function throws when there's left-over data
180after decoding a single top-level object.
181
182</p>
183
184<h2 id="serialize_format">Serialization Format Specification</h2>
185<p>
186
187This serialization format is designed for <b>internal use</b> by LuaJIT
188applications. Serialized data is upwards-compatible and portable across
189all supported LuaJIT platforms.
190
191</p>
192<p>
193
194It's an <b>8-bit binary format</b> and not human-readable. It uses e.g.
195embedded zeroes and stores embedded Lua string objects unmodified, which
196are 8-bit-clean, too. Encoded data can be safely concatenated for
197streaming and later decoded one top-level object at a time.
198
199</p>
200<p>
201
202The encoding is reasonably compact, but tuned for maximum performance,
203not for minimum space usage. It compresses well with any of the common
204byte-oriented data compression algorithms.
205
206</p>
207<p>
208
209Although documented here for reference, this format is explicitly
210<b>not</b> intended to be a 'public standard' for structured data
211interchange across computer languages (like JSON or MessagePack). Please
212do not use it as such.
213
214</p>
215<p>
216
217The specification is given below as a context-free grammar with a
218top-level <tt>object</tt> as the starting point. Alternatives are
219separated by the <tt>|</tt> symbol and <tt>*</tt> indicates repeats.
220Grouping is implicit or indicated by <tt>{…}</tt>. Terminals are
221either plain hex numbers, encoded as bytes, or have a <tt>.format</tt>
222suffix.
223
224</p>
225<pre>
226object → nil | false | true
227 | null | lightud32 | lightud64
228 | int | num | tab
229 | int64 | uint64 | complex
230 | string
231
232nil → 0x00
233false → 0x01
234true → 0x02
235
236null → 0x03 // NULL lightuserdata
237lightud32 → 0x04 data.I // 32 bit lightuserdata
238lightud64 → 0x05 data.L // 64 bit lightuserdata
239
240int → 0x06 int.I // int32_t
241num → 0x07 double.L
242
243tab → 0x08 // Empty table
244 | 0x09 h.U h*{object object} // Key/value hash
245 | 0x0a a.U a*object // 0-based array
246 | 0x0b a.U a*object h.U h*{object object} // Mixed
247 | 0x0c a.U (a-1)*object // 1-based array
248 | 0x0d a.U (a-1)*object h.U h*{object object} // Mixed
249
250int64 → 0x10 int.L // FFI int64_t
251uint64 → 0x11 uint.L // FFI uint64_t
252complex → 0x12 re.L im.L // FFI complex
253
254string → (0x20+len).U len*char.B
255
256.B = 8 bit
257.I = 32 bit little-endian
258.L = 64 bit little-endian
259.U = prefix-encoded 32 bit unsigned number n:
260 0x00..0xdf → n.B
261 0xe0..0x1fdf → (0xe0|(((n-0xe0)>>8)&0x1f)).B ((n-0xe0)&0xff).B
262 0x1fe0.. → 0xff n.I
263</pre>
264<br class="flush">
265</div>
266<div id="foot">
267<hr class="hide">
268Copyright &copy; 2005-2021
269<span class="noprint">
270&middot;
271<a href="contact.html">Contact</a>
272</span>
273</div>
274</body>
275</html>
diff --git a/doc/ext_c_api.html b/doc/ext_c_api.html
index ea33c701..9f1ad212 100644
--- a/doc/ext_c_api.html
+++ b/doc/ext_c_api.html
@@ -1,8 +1,8 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> 1<!DOCTYPE html>
2<html> 2<html>
3<head> 3<head>
4<title>Lua/C API Extensions</title> 4<title>Lua/C API Extensions</title>
5<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> 5<meta charset="utf-8">
6<meta name="Copyright" content="Copyright (C) 2005-2021"> 6<meta name="Copyright" content="Copyright (C) 2005-2021">
7<meta name="Language" content="en"> 7<meta name="Language" content="en">
8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen"> 8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
@@ -37,9 +37,13 @@
37<a href="ext_ffi_semantics.html">FFI Semantics</a> 37<a href="ext_ffi_semantics.html">FFI Semantics</a>
38</li></ul> 38</li></ul>
39</li><li> 39</li><li>
40<a href="ext_buffer.html">String Buffers</a>
41</li><li>
40<a href="ext_jit.html">jit.* Library</a> 42<a href="ext_jit.html">jit.* Library</a>
41</li><li> 43</li><li>
42<a class="current" href="ext_c_api.html">Lua/C API</a> 44<a class="current" href="ext_c_api.html">Lua/C API</a>
45</li><li>
46<a href="ext_profiler.html">Profiler</a>
43</li></ul> 47</li></ul>
44</li><li> 48</li><li>
45<a href="status.html">Status</a> 49<a href="status.html">Status</a>
diff --git a/doc/ext_ffi.html b/doc/ext_ffi.html
index 654d4980..b934dc78 100644
--- a/doc/ext_ffi.html
+++ b/doc/ext_ffi.html
@@ -1,8 +1,8 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> 1<!DOCTYPE html>
2<html> 2<html>
3<head> 3<head>
4<title>FFI Library</title> 4<title>FFI Library</title>
5<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> 5<meta charset="utf-8">
6<meta name="Copyright" content="Copyright (C) 2005-2021"> 6<meta name="Copyright" content="Copyright (C) 2005-2021">
7<meta name="Language" content="en"> 7<meta name="Language" content="en">
8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen"> 8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
@@ -37,9 +37,13 @@
37<a href="ext_ffi_semantics.html">FFI Semantics</a> 37<a href="ext_ffi_semantics.html">FFI Semantics</a>
38</li></ul> 38</li></ul>
39</li><li> 39</li><li>
40<a href="ext_buffer.html">String Buffers</a>
41</li><li>
40<a href="ext_jit.html">jit.* Library</a> 42<a href="ext_jit.html">jit.* Library</a>
41</li><li> 43</li><li>
42<a href="ext_c_api.html">Lua/C API</a> 44<a href="ext_c_api.html">Lua/C API</a>
45</li><li>
46<a href="ext_profiler.html">Profiler</a>
43</li></ul> 47</li></ul>
44</li><li> 48</li><li>
45<a href="status.html">Status</a> 49<a href="status.html">Status</a>
diff --git a/doc/ext_ffi_api.html b/doc/ext_ffi_api.html
index a2af25df..061cc42a 100644
--- a/doc/ext_ffi_api.html
+++ b/doc/ext_ffi_api.html
@@ -1,8 +1,8 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> 1<!DOCTYPE html>
2<html> 2<html>
3<head> 3<head>
4<title>ffi.* API Functions</title> 4<title>ffi.* API Functions</title>
5<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> 5<meta charset="utf-8">
6<meta name="Copyright" content="Copyright (C) 2005-2021"> 6<meta name="Copyright" content="Copyright (C) 2005-2021">
7<meta name="Language" content="en"> 7<meta name="Language" content="en">
8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen"> 8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
@@ -42,9 +42,13 @@ td.abiparam { font-weight: bold; width: 6em; }
42<a href="ext_ffi_semantics.html">FFI Semantics</a> 42<a href="ext_ffi_semantics.html">FFI Semantics</a>
43</li></ul> 43</li></ul>
44</li><li> 44</li><li>
45<a href="ext_buffer.html">String Buffers</a>
46</li><li>
45<a href="ext_jit.html">jit.* Library</a> 47<a href="ext_jit.html">jit.* Library</a>
46</li><li> 48</li><li>
47<a href="ext_c_api.html">Lua/C API</a> 49<a href="ext_c_api.html">Lua/C API</a>
50</li><li>
51<a href="ext_profiler.html">Profiler</a>
48</li></ul> 52</li></ul>
49</li><li> 53</li><li>
50<a href="status.html">Status</a> 54<a href="status.html">Status</a>
@@ -460,6 +464,10 @@ otherwise. The following parameters are currently defined:
460<td class="abiparam">eabi</td><td class="abidesc">EABI variant of the standard ABI</td></tr> 464<td class="abiparam">eabi</td><td class="abidesc">EABI variant of the standard ABI</td></tr>
461<tr class="odd"> 465<tr class="odd">
462<td class="abiparam">win</td><td class="abidesc">Windows variant of the standard ABI</td></tr> 466<td class="abiparam">win</td><td class="abidesc">Windows variant of the standard ABI</td></tr>
467<tr class="even">
468<td class="abiparam">uwp</td><td class="abidesc">Universal Windows Platform</td></tr>
469<tr class="odd">
470<td class="abiparam">gc64</td><td class="abidesc">64 bit GC references</td></tr>
463</table> 471</table>
464 472
465<h3 id="ffi_os"><tt>ffi.os</tt></h3> 473<h3 id="ffi_os"><tt>ffi.os</tt></h3>
@@ -536,8 +544,8 @@ corresponding ctype.
536The parser for Lua source code treats numeric literals with the 544The parser for Lua source code treats numeric literals with the
537suffixes <tt>LL</tt> or <tt>ULL</tt> as signed or unsigned 64&nbsp;bit 545suffixes <tt>LL</tt> or <tt>ULL</tt> as signed or unsigned 64&nbsp;bit
538integers. Case doesn't matter, but uppercase is recommended for 546integers. Case doesn't matter, but uppercase is recommended for
539readability. It handles both decimal (<tt>42LL</tt>) and hexadecimal 547readability. It handles decimal (<tt>42LL</tt>), hexadecimal
540(<tt>0x2aLL</tt>) literals. 548(<tt>0x2aLL</tt>) and binary (<tt>0b101010LL</tt>) literals.
541</p> 549</p>
542<p> 550<p>
543The imaginary part of complex numbers can be specified by suffixing 551The imaginary part of complex numbers can be specified by suffixing
diff --git a/doc/ext_ffi_semantics.html b/doc/ext_ffi_semantics.html
index e42d1a97..fef39c32 100644
--- a/doc/ext_ffi_semantics.html
+++ b/doc/ext_ffi_semantics.html
@@ -1,8 +1,8 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> 1<!DOCTYPE html>
2<html> 2<html>
3<head> 3<head>
4<title>FFI Semantics</title> 4<title>FFI Semantics</title>
5<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> 5<meta charset="utf-8">
6<meta name="Copyright" content="Copyright (C) 2005-2021"> 6<meta name="Copyright" content="Copyright (C) 2005-2021">
7<meta name="Language" content="en"> 7<meta name="Language" content="en">
8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen"> 8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
@@ -42,9 +42,13 @@ td.convop { font-style: italic; width: 40%; }
42<a class="current" href="ext_ffi_semantics.html">FFI Semantics</a> 42<a class="current" href="ext_ffi_semantics.html">FFI Semantics</a>
43</li></ul> 43</li></ul>
44</li><li> 44</li><li>
45<a href="ext_buffer.html">String Buffers</a>
46</li><li>
45<a href="ext_jit.html">jit.* Library</a> 47<a href="ext_jit.html">jit.* Library</a>
46</li><li> 48</li><li>
47<a href="ext_c_api.html">Lua/C API</a> 49<a href="ext_c_api.html">Lua/C API</a>
50</li><li>
51<a href="ext_profiler.html">Profiler</a>
48</li></ul> 52</li></ul>
49</li><li> 53</li><li>
50<a href="status.html">Status</a> 54<a href="status.html">Status</a>
@@ -177,6 +181,8 @@ a <tt>typedef</tt>, except re-declarations will be ignored):
177<tt>uint16_t</tt>, <tt>uint32_t</tt>, <tt>uint64_t</tt>, 181<tt>uint16_t</tt>, <tt>uint32_t</tt>, <tt>uint64_t</tt>,
178<tt>intptr_t</tt>, <tt>uintptr_t</tt>.</li> 182<tt>intptr_t</tt>, <tt>uintptr_t</tt>.</li>
179 183
184<li>From <tt>&lt;unistd.h&gt;</tt> (POSIX): <tt>ssize_t</tt>.</li>
185
180</ul> 186</ul>
181<p> 187<p>
182You're encouraged to use these types in preference to 188You're encouraged to use these types in preference to
@@ -724,6 +730,22 @@ You'll have to explicitly convert a 64&nbsp;bit integer to a Lua
724number (e.g. for regular floating-point calculations) with 730number (e.g. for regular floating-point calculations) with
725<tt>tonumber()</tt>. But note this may incur a precision loss.</li> 731<tt>tonumber()</tt>. But note this may incur a precision loss.</li>
726 732
733<li><b>64&nbsp;bit bitwise operations</b>: the rules for 64&nbsp;bit
734arithmetic operators apply analogously.<br>
735
736Unlike the other <tt>bit.*</tt> operations, <tt>bit.tobit()</tt>
737converts a cdata number via <tt>int64_t</tt> to <tt>int32_t</tt> and
738returns a Lua number.<br>
739
740For <tt>bit.band()</tt>, <tt>bit.bor()</tt> and <tt>bit.bxor()</tt>, the
741conversion to <tt>int64_t</tt> or <tt>uint64_t</tt> applies to
742<em>all</em> arguments, if <em>any</em> argument is a cdata number.<br>
743
744For all other operations, only the first argument is used to determine
745the output type. This implies that a cdata number as a shift count for
746shifts and rotates is accepted, but that alone does <em>not</em> cause
747a cdata number output.
748
727</ul> 749</ul>
728 750
729<h3 id="cdata_comp">Comparisons of cdata objects</h3> 751<h3 id="cdata_comp">Comparisons of cdata objects</h3>
@@ -1195,14 +1217,12 @@ The following operations are currently not compiled and may exhibit
1195suboptimal performance, especially when used in inner loops: 1217suboptimal performance, especially when used in inner loops:
1196</p> 1218</p>
1197<ul> 1219<ul>
1198<li>Bitfield accesses and initializations.</li>
1199<li>Vector operations.</li> 1220<li>Vector operations.</li>
1200<li>Table initializers.</li> 1221<li>Table initializers.</li>
1201<li>Initialization of nested <tt>struct</tt>/<tt>union</tt> types.</li> 1222<li>Initialization of nested <tt>struct</tt>/<tt>union</tt> types.</li>
1202<li>Allocations of variable-length arrays or structs.</li> 1223<li>Non-default initialization of VLA/VLS or large C&nbsp;types
1203<li>Allocations of C&nbsp;types with a size &gt; 128&nbsp;bytes or an 1224(&gt; 128&nbsp;bytes or &gt; 16 array elements).</li>
1204alignment &gt; 8&nbsp;bytes.</li> 1225<li>Bitfield initializations.</li>
1205<li>Conversions from lightuserdata to <tt>void&nbsp;*</tt>.</li>
1206<li>Pointer differences for element sizes that are not a power of 1226<li>Pointer differences for element sizes that are not a power of
1207two.</li> 1227two.</li>
1208<li>Calls to C&nbsp;functions with aggregates passed or returned by 1228<li>Calls to C&nbsp;functions with aggregates passed or returned by
@@ -1218,7 +1238,6 @@ value.</li>
1218Other missing features: 1238Other missing features:
1219</p> 1239</p>
1220<ul> 1240<ul>
1221<li>Bit operations for 64&nbsp;bit types.</li>
1222<li>Arithmetic for <tt>complex</tt> numbers.</li> 1241<li>Arithmetic for <tt>complex</tt> numbers.</li>
1223<li>Passing structs by value to vararg C&nbsp;functions.</li> 1242<li>Passing structs by value to vararg C&nbsp;functions.</li>
1224<li><a href="extensions.html#exceptions">C++ exception interoperability</a> 1243<li><a href="extensions.html#exceptions">C++ exception interoperability</a>
diff --git a/doc/ext_ffi_tutorial.html b/doc/ext_ffi_tutorial.html
index a5235186..ca71be4d 100644
--- a/doc/ext_ffi_tutorial.html
+++ b/doc/ext_ffi_tutorial.html
@@ -1,8 +1,8 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> 1<!DOCTYPE html>
2<html> 2<html>
3<head> 3<head>
4<title>FFI Tutorial</title> 4<title>FFI Tutorial</title>
5<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> 5<meta charset="utf-8">
6<meta name="Copyright" content="Copyright (C) 2005-2021"> 6<meta name="Copyright" content="Copyright (C) 2005-2021">
7<meta name="Language" content="en"> 7<meta name="Language" content="en">
8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen"> 8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
@@ -44,9 +44,13 @@ td.idiomlua b { font-weight: normal; color: #2142bf; }
44<a href="ext_ffi_semantics.html">FFI Semantics</a> 44<a href="ext_ffi_semantics.html">FFI Semantics</a>
45</li></ul> 45</li></ul>
46</li><li> 46</li><li>
47<a href="ext_buffer.html">String Buffers</a>
48</li><li>
47<a href="ext_jit.html">jit.* Library</a> 49<a href="ext_jit.html">jit.* Library</a>
48</li><li> 50</li><li>
49<a href="ext_c_api.html">Lua/C API</a> 51<a href="ext_c_api.html">Lua/C API</a>
52</li><li>
53<a href="ext_profiler.html">Profiler</a>
50</li></ul> 54</li></ul>
51</li><li> 55</li><li>
52<a href="status.html">Status</a> 56<a href="status.html">Status</a>
diff --git a/doc/ext_jit.html b/doc/ext_jit.html
index 93240fda..6dd54c70 100644
--- a/doc/ext_jit.html
+++ b/doc/ext_jit.html
@@ -1,8 +1,8 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> 1<!DOCTYPE html>
2<html> 2<html>
3<head> 3<head>
4<title>jit.* Library</title> 4<title>jit.* Library</title>
5<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> 5<meta charset="utf-8">
6<meta name="Copyright" content="Copyright (C) 2005-2021"> 6<meta name="Copyright" content="Copyright (C) 2005-2021">
7<meta name="Language" content="en"> 7<meta name="Language" content="en">
8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen"> 8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
@@ -37,9 +37,13 @@
37<a href="ext_ffi_semantics.html">FFI Semantics</a> 37<a href="ext_ffi_semantics.html">FFI Semantics</a>
38</li></ul> 38</li></ul>
39</li><li> 39</li><li>
40<a href="ext_buffer.html">String Buffers</a>
41</li><li>
40<a class="current" href="ext_jit.html">jit.* Library</a> 42<a class="current" href="ext_jit.html">jit.* Library</a>
41</li><li> 43</li><li>
42<a href="ext_c_api.html">Lua/C API</a> 44<a href="ext_c_api.html">Lua/C API</a>
45</li><li>
46<a href="ext_profiler.html">Profiler</a>
43</li></ul> 47</li></ul>
44</li><li> 48</li><li>
45<a href="status.html">Status</a> 49<a href="status.html">Status</a>
@@ -145,7 +149,7 @@ Contains the target OS name:
145<h3 id="jit_arch"><tt>jit.arch</tt></h3> 149<h3 id="jit_arch"><tt>jit.arch</tt></h3>
146<p> 150<p>
147Contains the target architecture name: 151Contains the target architecture name:
148"x86", "x64", "arm", "ppc", "ppcspe", or "mips". 152"x86", "x64", "arm", "arm64", "arm64be", "ppc", "mips", "mipsel", "mips64", "mips64el", "mips64r6", "mips64r6el".
149</p> 153</p>
150 154
151<h2 id="jit_opt"><tt>jit.opt.*</tt> &mdash; JIT compiler optimization control</h2> 155<h2 id="jit_opt"><tt>jit.opt.*</tt> &mdash; JIT compiler optimization control</h2>
diff --git a/doc/ext_profiler.html b/doc/ext_profiler.html
new file mode 100644
index 00000000..2783abdb
--- /dev/null
+++ b/doc/ext_profiler.html
@@ -0,0 +1,361 @@
1<!DOCTYPE html>
2<html>
3<head>
4<title>Profiler</title>
5<meta charset="utf-8">
6<meta name="Copyright" content="Copyright (C) 2005-2021">
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</head>
11<body>
12<div id="site">
13<a href="https://luajit.org"><span>Lua<span id="logo">JIT</span></span></a>
14</div>
15<div id="head">
16<h1>Profiler</h1>
17</div>
18<div id="nav">
19<ul><li>
20<a href="luajit.html">LuaJIT</a>
21<ul><li>
22<a href="https://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
23</li><li>
24<a href="install.html">Installation</a>
25</li><li>
26<a href="running.html">Running</a>
27</li></ul>
28</li><li>
29<a href="extensions.html">Extensions</a>
30<ul><li>
31<a href="ext_ffi.html">FFI Library</a>
32<ul><li>
33<a href="ext_ffi_tutorial.html">FFI Tutorial</a>
34</li><li>
35<a href="ext_ffi_api.html">ffi.* API</a>
36</li><li>
37<a href="ext_ffi_semantics.html">FFI Semantics</a>
38</li></ul>
39</li><li>
40<a href="ext_buffer.html">String Buffers</a>
41</li><li>
42<a href="ext_jit.html">jit.* Library</a>
43</li><li>
44<a href="ext_c_api.html">Lua/C API</a>
45</li><li>
46<a class="current" href="ext_profiler.html">Profiler</a>
47</li></ul>
48</li><li>
49<a href="status.html">Status</a>
50</li><li>
51<a href="faq.html">FAQ</a>
52</li><li>
53<a href="http://wiki.luajit.org/">Wiki <span class="ext">&raquo;</span></a>
54</li><li>
55<a href="https://luajit.org/list.html">Mailing List <span class="ext">&raquo;</span></a>
56</li></ul>
57</div>
58<div id="main">
59<p>
60LuaJIT has an integrated statistical profiler with very low overhead. It
61allows sampling the currently executing stack and other parameters in
62regular intervals.
63</p>
64<p>
65The integrated profiler can be accessed from three levels:
66</p>
67<ul>
68<li>The <a href="#hl_profiler">bundled high-level profiler</a>, invoked by the
69<a href="#j_p"><tt>-jp</tt></a> command line option.</li>
70<li>A <a href="#ll_lua_api">low-level Lua API</a> to control the profiler.</li>
71<li>A <a href="#ll_c_api">low-level C API</a> to control the profiler.</li>
72</ul>
73
74<h2 id="hl_profiler">High-Level Profiler</h2>
75<p>
76The bundled high-level profiler offers basic profiling functionality. It
77generates simple textual summaries or source code annotations. It can be
78accessed with the <a href="#j_p"><tt>-jp</tt></a> command line option
79or from Lua code by loading the underlying <tt>jit.p</tt> module.
80</p>
81<p>
82To cut to the chase &mdash; run this to get a CPU usage profile by
83function name:
84</p>
85<pre class="code">
86luajit -jp myapp.lua
87</pre>
88<p>
89It's <em>not</em> a stated goal of the bundled profiler to add every
90possible option or to cater for special profiling needs. The low-level
91profiler APIs are documented below. They may be used by third-party
92authors to implement advanced functionality, e.g. IDE integration or
93graphical profilers.
94</p>
95<p>
96Note: Sampling works for both interpreted and JIT-compiled code. The
97results for JIT-compiled code may sometimes be surprising. LuaJIT
98heavily optimizes and inlines Lua code &mdash; there's no simple
99one-to-one correspondence between source code lines and the sampled
100machine code.
101</p>
102
103<h3 id="j_p"><tt>-jp=[options[,output]]</tt></h3>
104<p>
105The <tt>-jp</tt> command line option starts the high-level profiler.
106When the application run by the command line terminates, the profiler
107stops and writes the results to <tt>stdout</tt> or to the specified
108<tt>output</tt> file.
109</p>
110<p>
111The <tt>options</tt> argument specifies how the profiling is to be
112performed:
113</p>
114<ul>
115<li><tt>f</tt> &mdash; Stack dump: function name, otherwise module:line.
116This is the default mode.</li>
117<li><tt>F</tt> &mdash; Stack dump: ditto, but dump module:name.</li>
118<li><tt>l</tt> &mdash; Stack dump: module:line.</li>
119<li><tt>&lt;number&gt;</tt> &mdash; stack dump depth (callee &larr;
120caller). Default: 1.</li>
121<li><tt>-&lt;number&gt;</tt> &mdash; Inverse stack dump depth (caller
122&rarr; callee).</li>
123<li><tt>s</tt> &mdash; Split stack dump after first stack level. Implies
124depth&nbsp;&ge;&nbsp;2 or depth&nbsp;&le;&nbsp;-2.</li>
125<li><tt>p</tt> &mdash; Show full path for module names.</li>
126<li><tt>v</tt> &mdash; Show VM states.</li>
127<li><tt>z</tt> &mdash; Show <a href="#jit_zone">zones</a>.</li>
128<li><tt>r</tt> &mdash; Show raw sample counts. Default: show percentages.</li>
129<li><tt>a</tt> &mdash; Annotate excerpts from source code files.</li>
130<li><tt>A</tt> &mdash; Annotate complete source code files.</li>
131<li><tt>G</tt> &mdash; Produce raw output suitable for graphical tools.</li>
132<li><tt>m&lt;number&gt;</tt> &mdash; Minimum sample percentage to be shown.
133Default: 3%.</li>
134<li><tt>i&lt;number&gt;</tt> &mdash; Sampling interval in milliseconds.
135Default: 10ms.<br>
136Note: The actual sampling precision is OS-dependent.</li>
137</ul>
138<p>
139The default output for <tt>-jp</tt> is a list of the most CPU consuming
140spots in the application. Increasing the stack dump depth with (say)
141<tt>-jp=2</tt> may help to point out the main callers or callees of
142hotspots. But sample aggregation is still flat per unique stack dump.
143</p>
144<p>
145To get a two-level view (split view) of callers/callees, use
146<tt>-jp=s</tt> or <tt>-jp=-s</tt>. The percentages shown for the second
147level are relative to the first level.
148</p>
149<p>
150To see how much time is spent in each line relative to a function, use
151<tt>-jp=fl</tt>.
152</p>
153<p>
154To see how much time is spent in different VM states or
155<a href="#jit_zone">zones</a>, use <tt>-jp=v</tt> or <tt>-jp=z</tt>.
156</p>
157<p>
158Combinations of <tt>v/z</tt> with <tt>f/F/l</tt> produce two-level
159views, e.g. <tt>-jp=vf</tt> or <tt>-jp=fv</tt>. This shows the time
160spent in a VM state or zone vs. hotspots. This can be used to answer
161questions like "Which time consuming functions are only interpreted?" or
162"What's the garbage collector overhead for a specific function?".
163</p>
164<p>
165Multiple options can be combined &mdash; but not all combinations make
166sense, see above. E.g. <tt>-jp=3si4m1</tt> samples three stack levels
167deep in 4ms intervals and shows a split view of the CPU consuming
168functions and their callers with a 1% threshold.
169</p>
170<p>
171Source code annotations produced by <tt>-jp=a</tt> or <tt>-jp=A</tt> are
172always flat and at the line level. Obviously, the source code files need
173to be readable by the profiler script.
174</p>
175<p>
176The high-level profiler can also be started and stopped from Lua code with:
177</p>
178<pre class="code">
179require("jit.p").start(options, output)
180...
181require("jit.p").stop()
182</pre>
183
184<h3 id="jit_zone"><tt>jit.zone</tt> &mdash; Zones</h3>
185<p>
186Zones can be used to provide information about different parts of an
187application to the high-level profiler. E.g. a game could make use of an
188<tt>"AI"</tt> zone, a <tt>"PHYS"</tt> zone, etc. Zones are hierarchical,
189organized as a stack.
190</p>
191<p>
192The <tt>jit.zone</tt> module needs to be loaded explicitly:
193</p>
194<pre class="code">
195local zone = require("jit.zone")
196</pre>
197<ul>
198<li><tt>zone("name")</tt> pushes a named zone to the zone stack.</li>
199<li><tt>zone()</tt> pops the current zone from the zone stack and
200returns its name.</li>
201<li><tt>zone:get()</tt> returns the current zone name or <tt>nil</tt>.</li>
202<li><tt>zone:flush()</tt> flushes the zone stack.</li>
203</ul>
204<p>
205To show the time spent in each zone use <tt>-jp=z</tt>. To show the time
206spent relative to hotspots use e.g. <tt>-jp=zf</tt> or <tt>-jp=fz</tt>.
207</p>
208
209<h2 id="ll_lua_api">Low-level Lua API</h2>
210<p>
211The <tt>jit.profile</tt> module gives access to the low-level API of the
212profiler from Lua code. This module needs to be loaded explicitly:
213<pre class="code">
214local profile = require("jit.profile")
215</pre>
216<p>
217This module can be used to implement your own higher-level profiler.
218A typical profiling run starts the profiler, captures stack dumps in
219the profiler callback, adds them to a hash table to aggregate the number
220of samples, stops the profiler and then analyzes all of the captured
221stack dumps. Other parameters can be sampled in the profiler callback,
222too. But it's important not to spend too much time in the callback,
223since this may skew the statistics.
224</p>
225
226<h3 id="profile_start"><tt>profile.start(mode, cb)</tt>
227&mdash; Start profiler</h3>
228<p>
229This function starts the profiler. The <tt>mode</tt> argument is a
230string holding options:
231</p>
232<ul>
233<li><tt>f</tt> &mdash; Profile with precision down to the function level.</li>
234<li><tt>l</tt> &mdash; Profile with precision down to the line level.</li>
235<li><tt>i&lt;number&gt;</tt> &mdash; Sampling interval in milliseconds (default
23610ms).</br>
237Note: The actual sampling precision is OS-dependent.
238</li>
239</ul>
240<p>
241The <tt>cb</tt> argument is a callback function which is called with
242three arguments: <tt>(thread, samples, vmstate)</tt>. The callback is
243called on a separate coroutine, the <tt>thread</tt> argument is the
244state that holds the stack to sample for profiling. Note: do
245<em>not</em> modify the stack of that state or call functions on it.
246</p>
247<p>
248<tt>samples</tt> gives the number of accumulated samples since the last
249callback (usually 1).
250</p>
251<p>
252<tt>vmstate</tt> holds the VM state at the time the profiling timer
253triggered. This may or may not correspond to the state of the VM when
254the profiling callback is called. The state is either <tt>'N'</tt>
255native (compiled) code, <tt>'I'</tt> interpreted code, <tt>'C'</tt>
256C&nbsp;code, <tt>'G'</tt> the garbage collector, or <tt>'J'</tt> the JIT
257compiler.
258</p>
259
260<h3 id="profile_stop"><tt>profile.stop()</tt>
261&mdash; Stop profiler</h3>
262<p>
263This function stops the profiler.
264</p>
265
266<h3 id="profile_dump"><tt>dump = profile.dumpstack([thread,] fmt, depth)</tt>
267&mdash; Dump stack </h3>
268<p>
269This function allows taking stack dumps in an efficient manner. It
270returns a string with a stack dump for the <tt>thread</tt> (coroutine),
271formatted according to the <tt>fmt</tt> argument:
272</p>
273<ul>
274<li><tt>p</tt> &mdash; Preserve the full path for module names. Otherwise
275only the file name is used.</li>
276<li><tt>f</tt> &mdash; Dump the function name if it can be derived. Otherwise
277use module:line.</li>
278<li><tt>F</tt> &mdash; Ditto, but dump module:name.</li>
279<li><tt>l</tt> &mdash; Dump module:line.</li>
280<li><tt>Z</tt> &mdash; Zap the following characters for the last dumped
281frame.</li>
282<li>All other characters are added verbatim to the output string.</li>
283</ul>
284<p>
285The <tt>depth</tt> argument gives the number of frames to dump, starting
286at the topmost frame of the thread. A negative number dumps the frames in
287inverse order.
288</p>
289<p>
290The first example prints a list of the current module names and line
291numbers of up to 10 frames in separate lines. The second example prints
292semicolon-separated function names for all frames (up to 100) in inverse
293order:
294</p>
295<pre class="code">
296print(profile.dumpstack(thread, "l\n", 10))
297print(profile.dumpstack(thread, "lZ;", -100))
298</pre>
299
300<h2 id="ll_c_api">Low-level C API</h2>
301<p>
302The profiler can be controlled directly from C&nbsp;code, e.g. for
303use by IDEs. The declarations are in <tt>"luajit.h"</tt> (see
304<a href="ext_c_api.html">Lua/C API</a> extensions).
305</p>
306
307<h3 id="luaJIT_profile_start"><tt>luaJIT_profile_start(L, mode, cb, data)</tt>
308&mdash; Start profiler</h3>
309<p>
310This function starts the profiler. <a href="#profile_start">See
311above</a> for a description of the <tt>mode</tt> argument.
312</p>
313<p>
314The <tt>cb</tt> argument is a callback function with the following
315declaration:
316</p>
317<pre class="code">
318typedef void (*luaJIT_profile_callback)(void *data, lua_State *L,
319 int samples, int vmstate);
320</pre>
321<p>
322<tt>data</tt> is available for use by the callback. <tt>L</tt> is the
323state that holds the stack to sample for profiling. Note: do
324<em>not</em> modify this stack or call functions on this stack &mdash;
325use a separate coroutine for this purpose. <a href="#profile_start">See
326above</a> for a description of <tt>samples</tt> and <tt>vmstate</tt>.
327</p>
328
329<h3 id="luaJIT_profile_stop"><tt>luaJIT_profile_stop(L)</tt>
330&mdash; Stop profiler</h3>
331<p>
332This function stops the profiler.
333</p>
334
335<h3 id="luaJIT_profile_dumpstack"><tt>p = luaJIT_profile_dumpstack(L, fmt, depth, len)</tt>
336&mdash; Dump stack </h3>
337<p>
338This function allows taking stack dumps in an efficient manner.
339<a href="#profile_dump">See above</a> for a description of <tt>fmt</tt>
340and <tt>depth</tt>.
341</p>
342<p>
343This function returns a <tt>const&nbsp;char&nbsp;*</tt> pointing to a
344private string buffer of the profiler. The <tt>int&nbsp;*len</tt>
345argument returns the length of the output string. The buffer is
346overwritten on the next call and deallocated when the profiler stops.
347You either need to consume the content immediately or copy it for later
348use.
349</p>
350<br class="flush">
351</div>
352<div id="foot">
353<hr class="hide">
354Copyright &copy; 2005-2021
355<span class="noprint">
356&middot;
357<a href="contact.html">Contact</a>
358</span>
359</div>
360</body>
361</html>
diff --git a/doc/extensions.html b/doc/extensions.html
index 306943b7..799679a3 100644
--- a/doc/extensions.html
+++ b/doc/extensions.html
@@ -1,8 +1,8 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> 1<!DOCTYPE html>
2<html> 2<html>
3<head> 3<head>
4<title>Extensions</title> 4<title>Extensions</title>
5<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> 5<meta charset="utf-8">
6<meta name="Copyright" content="Copyright (C) 2005-2021"> 6<meta name="Copyright" content="Copyright (C) 2005-2021">
7<meta name="Language" content="en"> 7<meta name="Language" content="en">
8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen"> 8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
@@ -54,9 +54,13 @@ td.excinterop {
54<a href="ext_ffi_semantics.html">FFI Semantics</a> 54<a href="ext_ffi_semantics.html">FFI Semantics</a>
55</li></ul> 55</li></ul>
56</li><li> 56</li><li>
57<a href="ext_buffer.html">String Buffers</a>
58</li><li>
57<a href="ext_jit.html">jit.* Library</a> 59<a href="ext_jit.html">jit.* Library</a>
58</li><li> 60</li><li>
59<a href="ext_c_api.html">Lua/C API</a> 61<a href="ext_c_api.html">Lua/C API</a>
62</li><li>
63<a href="ext_profiler.html">Profiler</a>
60</li></ul> 64</li></ul>
61</li><li> 65</li><li>
62<a href="status.html">Status</a> 66<a href="status.html">Status</a>
@@ -107,6 +111,9 @@ bit.lshift bit.rshift bit.arshift bit.rol bit.ror bit.bswap
107This module is a LuaJIT built-in &mdash; you don't need to download or 111This module is a LuaJIT built-in &mdash; you don't need to download or
108install Lua BitOp. The Lua BitOp site has full documentation for all 112install Lua BitOp. The Lua BitOp site has full documentation for all
109<a href="https://bitop.luajit.org/api.html"><span class="ext">&raquo;</span>&nbsp;Lua BitOp API functions</a>. 113<a href="https://bitop.luajit.org/api.html"><span class="ext">&raquo;</span>&nbsp;Lua BitOp API functions</a>.
114The FFI adds support for
115<a href="ext_ffi_semantics.html#cdata_arith">64&nbsp;bit bitwise operations</a>,
116using the same API functions.
110</p> 117</p>
111<p> 118<p>
112Please make sure to <tt>require</tt> the module before using any of 119Please make sure to <tt>require</tt> the module before using any of
@@ -140,6 +147,11 @@ LuaJIT adds some
140<a href="ext_c_api.html">extra functions to the Lua/C API</a>. 147<a href="ext_c_api.html">extra functions to the Lua/C API</a>.
141</p> 148</p>
142 149
150<h3 id="profiler">Profiler</h3>
151<p>
152LuaJIT has an <a href="ext_profiler.html">integrated profiler</a>.
153</p>
154
143<h2 id="library">Enhanced Standard Library Functions</h2> 155<h2 id="library">Enhanced Standard Library Functions</h2>
144 156
145<h3 id="xpcall"><tt>xpcall(f, err [,args...])</tt> passes arguments</h3> 157<h3 id="xpcall"><tt>xpcall(f, err [,args...])</tt> passes arguments</h3>
@@ -167,7 +179,7 @@ in <tt>"-inf"</tt>.
167<h3 id="tonumber"><tt>tonumber()</tt> etc. use builtin string to number conversion</h3> 179<h3 id="tonumber"><tt>tonumber()</tt> etc. use builtin string to number conversion</h3>
168<p> 180<p>
169All string-to-number conversions consistently convert integer and 181All string-to-number conversions consistently convert integer and
170floating-point inputs in decimal and hexadecimal on all platforms. 182floating-point inputs in decimal, hexadecimal and binary on all platforms.
171<tt>strtod()</tt> is <em>not</em> used anymore, which avoids numerous 183<tt>strtod()</tt> is <em>not</em> used anymore, which avoids numerous
172problems with poor C library implementations. The builtin conversion 184problems with poor C library implementations. The builtin conversion
173function provides full precision according to the IEEE-754 standard, it 185function provides full precision according to the IEEE-754 standard, it
@@ -191,6 +203,36 @@ for dot releases (x.y.0 &rarr; x.y.1), but may change with major or
191minor releases (2.0 &rarr; 2.1) or between any beta release. Foreign 203minor releases (2.0 &rarr; 2.1) or between any beta release. Foreign
192bytecode (e.g. from Lua 5.1) is incompatible and cannot be loaded. 204bytecode (e.g. from Lua 5.1) is incompatible and cannot be loaded.
193</p> 205</p>
206<p>
207Note: <tt>LJ_GC64</tt> mode requires a different frame layout, which implies
208a different, incompatible bytecode format for all 64 bit ports. This may be
209rectified in the future.
210</p>
211
212<h3 id="table_new"><tt>table.new(narray, nhash)</tt> allocates a pre-sized table</h3>
213<p>
214An extra library function <tt>table.new()</tt> can be made available via
215<tt>require("table.new")</tt>. This creates a pre-sized table, just like
216the C API equivalent <tt>lua_createtable()</tt>. This is useful for big
217tables if the final table size is known and automatic table resizing is
218too expensive.
219</p>
220
221<h3 id="table_clear"><tt>table.clear(tab)</tt> clears a table</h3>
222<p>
223An extra library function <tt>table.clear()</tt> can be made available
224via <tt>require("table.clear")</tt>. This clears all keys and values
225from a table, but preserves the allocated array/hash sizes. This is
226useful when a table, which is linked from multiple places, needs to be
227cleared and/or when recycling a table for use by the same context. This
228avoids managing backlinks, saves an allocation and the overhead of
229incremental array/hash part growth.
230</p>
231<p>
232Please note this function is meant for very specific situations. In most
233cases it's better to replace the (usually single) link with a new table
234and let the GC do its work.
235</p>
194 236
195<h3 id="math_random">Enhanced PRNG for <tt>math.random()</tt></h3> 237<h3 id="math_random">Enhanced PRNG for <tt>math.random()</tt></h3>
196<p> 238<p>
@@ -269,6 +311,26 @@ indexes for varargs.</li>
269<li><tt>debug.getupvalue()</tt> and <tt>debug.setupvalue()</tt> handle 311<li><tt>debug.getupvalue()</tt> and <tt>debug.setupvalue()</tt> handle
270C&nbsp;functions.</li> 312C&nbsp;functions.</li>
271<li><tt>debug.upvalueid()</tt> and <tt>debug.upvaluejoin()</tt>.</li> 313<li><tt>debug.upvalueid()</tt> and <tt>debug.upvaluejoin()</tt>.</li>
314<li>Lua/C API extensions:
315<tt>lua_version()</tt>
316<tt>lua_upvalueid()</tt>
317<tt>lua_upvaluejoin()</tt>
318<tt>lua_loadx()</tt>
319<tt>lua_copy()</tt>
320<tt>lua_tonumberx()</tt>
321<tt>lua_tointegerx()</tt>
322<tt>luaL_fileresult()</tt>
323<tt>luaL_execresult()</tt>
324<tt>luaL_loadfilex()</tt>
325<tt>luaL_loadbufferx()</tt>
326<tt>luaL_traceback()</tt>
327<tt>luaL_setfuncs()</tt>
328<tt>luaL_pushmodule()</tt>
329<tt>luaL_newlibtable()</tt>
330<tt>luaL_newlib()</tt>
331<tt>luaL_testudata()</tt>
332<tt>luaL_setmetatable()</tt>
333</li>
272<li>Command line option <tt>-E</tt>.</li> 334<li>Command line option <tt>-E</tt>.</li>
273<li>Command line checks <tt>__tostring</tt> for errors.</li> 335<li>Command line checks <tt>__tostring</tt> for errors.</li>
274</ul> 336</ul>
@@ -294,6 +356,8 @@ exit status.</li>
294<li><tt>debug.setmetatable()</tt> returns object.</li> 356<li><tt>debug.setmetatable()</tt> returns object.</li>
295<li><tt>debug.getuservalue()</tt> and <tt>debug.setuservalue()</tt>.</li> 357<li><tt>debug.getuservalue()</tt> and <tt>debug.setuservalue()</tt>.</li>
296<li>Remove <tt>math.mod()</tt>, <tt>string.gfind()</tt>.</li> 358<li>Remove <tt>math.mod()</tt>, <tt>string.gfind()</tt>.</li>
359<li><tt>package.searchers</tt>.</li>
360<li><tt>module()</tt> returns the module table.</li>
297</ul> 361</ul>
298<p> 362<p>
299Note: this provides only partial compatibility with Lua 5.2 at the 363Note: this provides only partial compatibility with Lua 5.2 at the
@@ -302,6 +366,21 @@ Lua&nbsp;5.1, which prevents implementing features that would otherwise
302break the Lua/C API and ABI (e.g. <tt>_ENV</tt>). 366break the Lua/C API and ABI (e.g. <tt>_ENV</tt>).
303</p> 367</p>
304 368
369<h2 id="lua53">Extensions from Lua 5.3</h2>
370<p>
371LuaJIT supports some extensions from Lua&nbsp;5.3:
372<ul>
373<li>Unicode escape <tt>'\u{XX...}'</tt> embeds the UTF-8 encoding in string literals.</li>
374<li>The argument table <tt>arg</tt> can be read (and modified) by <tt>LUA_INIT</tt> and <tt>-e</tt> chunks.</li>
375<li><tt>io.read()</tt> and <tt>file:read()</tt> accept formats with or without a leading <tt>*</tt>.</li>
376<li><tt>assert()</tt> accepts any type of error object.</li>
377<li><tt>table.move(a1, f, e, t [,a2])</tt>.</li>
378<li><tt>coroutine.isyieldable()</tt>.</li>
379<li>Lua/C API extensions:
380<tt>lua_isyieldable()</tt>
381</li>
382</ul>
383
305<h2 id="exceptions">C++ Exception Interoperability</h2> 384<h2 id="exceptions">C++ Exception Interoperability</h2>
306<p> 385<p>
307LuaJIT has built-in support for interoperating with C++&nbsp;exceptions. 386LuaJIT has built-in support for interoperating with C++&nbsp;exceptions.
@@ -315,26 +394,21 @@ the toolchain used to compile LuaJIT:
315<td class="excinterop">Interoperability</td> 394<td class="excinterop">Interoperability</td>
316</tr> 395</tr>
317<tr class="odd separate"> 396<tr class="odd separate">
318<td class="excplatform">POSIX/x64, DWARF2 unwinding</td> 397<td class="excplatform">External frame unwinding</td>
319<td class="exccompiler">GCC 4.3+</td> 398<td class="exccompiler">GCC, Clang, MSVC</td>
320<td class="excinterop"><b style="color: #00a000;">Full</b></td> 399<td class="excinterop"><b style="color: #00a000;">Full</b></td>
321</tr> 400</tr>
322<tr class="even"> 401<tr class="even">
323<td class="excplatform">Other platforms, DWARF2 unwinding</td> 402<td class="excplatform">Internal frame unwinding + DWARF2</td>
324<td class="exccompiler">GCC</td> 403<td class="exccompiler">GCC, Clang</td>
325<td class="excinterop"><b style="color: #c06000;">Limited</b></td> 404<td class="excinterop"><b style="color: #c06000;">Limited</b></td>
326</tr> 405</tr>
327<tr class="odd"> 406<tr class="odd">
328<td class="excplatform">Windows/x64</td> 407<td class="excplatform">Windows 64 bit</td>
329<td class="exccompiler">MSVC</td> 408<td class="exccompiler">non-MSVC</td>
330<td class="excinterop"><b style="color: #00a000;">Full</b></td> 409<td class="excinterop"><b style="color: #c06000;">Limited</b></td>
331</tr> 410</tr>
332<tr class="even"> 411<tr class="even">
333<td class="excplatform">Windows/x86</td>
334<td class="exccompiler">Any</td>
335<td class="excinterop"><b style="color: #a00000;">No</b></td>
336</tr>
337<tr class="odd">
338<td class="excplatform">Other platforms</td> 412<td class="excplatform">Other platforms</td>
339<td class="exccompiler">Other compilers</td> 413<td class="exccompiler">Other compilers</td>
340<td class="excinterop"><b style="color: #a00000;">No</b></td> 414<td class="excinterop"><b style="color: #a00000;">No</b></td>
@@ -383,14 +457,6 @@ C++ destructors.</li>
383<li>Lua errors <b>cannot</b> be caught on the C++ side.</li> 457<li>Lua errors <b>cannot</b> be caught on the C++ side.</li>
384<li>Throwing Lua errors across C++ frames will <b>not</b> call 458<li>Throwing Lua errors across C++ frames will <b>not</b> call
385C++ destructors.</li> 459C++ destructors.</li>
386<li>Additionally, on Windows/x86 with SEH-based C++&nbsp;exceptions:
387it's <b>not</b> safe to throw a Lua error across any frames containing
388a C++ function with any try/catch construct or using variables with
389(implicit) destructors. This also applies to any functions which may be
390inlined in such a function. It doesn't matter whether <tt>lua_error()</tt>
391is called inside or outside of a try/catch or whether any object actually
392needs to be destroyed: the SEH chain is corrupted and this will eventually
393lead to the termination of the process.</li>
394</ul> 460</ul>
395<br class="flush"> 461<br class="flush">
396</div> 462</div>
diff --git a/doc/faq.html b/doc/faq.html
index 6b7dc563..01956e15 100644
--- a/doc/faq.html
+++ b/doc/faq.html
@@ -1,8 +1,8 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> 1<!DOCTYPE html>
2<html> 2<html>
3<head> 3<head>
4<title>Frequently Asked Questions (FAQ)</title> 4<title>Frequently Asked Questions (FAQ)</title>
5<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> 5<meta charset="utf-8">
6<meta name="Copyright" content="Copyright (C) 2005-2021"> 6<meta name="Copyright" content="Copyright (C) 2005-2021">
7<meta name="Language" content="en"> 7<meta name="Language" content="en">
8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen"> 8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
@@ -40,9 +40,13 @@ dd { margin-left: 1.5em; }
40<a href="ext_ffi_semantics.html">FFI Semantics</a> 40<a href="ext_ffi_semantics.html">FFI Semantics</a>
41</li></ul> 41</li></ul>
42</li><li> 42</li><li>
43<a href="ext_buffer.html">String Buffers</a>
44</li><li>
43<a href="ext_jit.html">jit.* Library</a> 45<a href="ext_jit.html">jit.* Library</a>
44</li><li> 46</li><li>
45<a href="ext_c_api.html">Lua/C API</a> 47<a href="ext_c_api.html">Lua/C API</a>
48</li><li>
49<a href="ext_profiler.html">Profiler</a>
46</li></ul> 50</li></ul>
47</li><li> 51</li><li>
48<a href="status.html">Status</a> 52<a href="status.html">Status</a>
diff --git a/doc/install.html b/doc/install.html
index 56fc184e..e4af9dde 100644
--- a/doc/install.html
+++ b/doc/install.html
@@ -1,8 +1,8 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> 1<!DOCTYPE html>
2<html> 2<html>
3<head> 3<head>
4<title>Installation</title> 4<title>Installation</title>
5<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> 5<meta charset="utf-8">
6<meta name="Copyright" content="Copyright (C) 2005-2021"> 6<meta name="Copyright" content="Copyright (C) 2005-2021">
7<meta name="Language" content="en"> 7<meta name="Language" content="en">
8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen"> 8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
@@ -65,9 +65,13 @@ td.compatno {
65<a href="ext_ffi_semantics.html">FFI Semantics</a> 65<a href="ext_ffi_semantics.html">FFI Semantics</a>
66</li></ul> 66</li></ul>
67</li><li> 67</li><li>
68<a href="ext_buffer.html">String Buffers</a>
69</li><li>
68<a href="ext_jit.html">jit.* Library</a> 70<a href="ext_jit.html">jit.* Library</a>
69</li><li> 71</li><li>
70<a href="ext_c_api.html">Lua/C API</a> 72<a href="ext_c_api.html">Lua/C API</a>
73</li><li>
74<a href="ext_profiler.html">Profiler</a>
71</li></ul> 75</li></ul>
72</li><li> 76</li><li>
73<a href="status.html">Status</a> 77<a href="status.html">Status</a>
@@ -102,21 +106,21 @@ operating systems, CPUs and compilers:
102<td class="compatos"><a href="#posix">Linux</a> or<br><a href="#android">Android</a></td> 106<td class="compatos"><a href="#posix">Linux</a> or<br><a href="#android">Android</a></td>
103<td class="compatos"><a href="#posix">*BSD, Other</a></td> 107<td class="compatos"><a href="#posix">*BSD, Other</a></td>
104<td class="compatos"><a href="#posix">macOS 10.4+</a> or<br><a href="#ios">iOS 3.0+</a></td> 108<td class="compatos"><a href="#posix">macOS 10.4+</a> or<br><a href="#ios">iOS 3.0+</a></td>
105<td class="compatos"><a href="#windows">Windows XP<br>or later</a></td> 109<td class="compatos"><a href="#windows">Windows 7<br>or later</a></td>
106</tr> 110</tr>
107<tr class="odd separate"> 111<tr class="odd separate">
108<td class="compatcpu">x86 (32 bit)</td> 112<td class="compatcpu">x86 (32 bit)</td>
109<td class="compatos">GCC 4.x+<br>GCC 3.4</td> 113<td class="compatos">GCC 4.2+</td>
110<td class="compatos">GCC 4.x+<br>GCC 3.4</td> 114<td class="compatos">GCC 4.2+</td>
111<td class="compatos">XCode 5.0+<br>Clang</td> 115<td class="compatos">XCode 5.0+<br>Clang</td>
112<td class="compatos">MSVC<br>MinGW, Cygwin</td> 116<td class="compatos">MSVC<br>MinGW, Cygwin</td>
113</tr> 117</tr>
114<tr class="even"> 118<tr class="even">
115<td class="compatcpu">x64 (64 bit)</td> 119<td class="compatcpu">x64 (64 bit)</td>
116<td class="compatos">GCC 4.x+</td> 120<td class="compatos">GCC 4.2+</td>
117<td class="compatos">ORBIS (<a href="#ps4">PS4</a>)</td> 121<td class="compatos">GCC 4.2+<br>ORBIS (<a href="#ps4">PS4</a>)</td>
118<td class="compatos">XCode 5.0+<br>Clang</td> 122<td class="compatos">XCode 5.0+<br>Clang</td>
119<td class="compatos">MSVC</td> 123<td class="compatos">MSVC<br>Durango (<a href="#xboxone">Xbox One</a>)</td>
120</tr> 124</tr>
121<tr class="odd"> 125<tr class="odd">
122<td class="compatcpu"><a href="#cross2">ARMv5+<br>ARM9E+</a></td> 126<td class="compatcpu"><a href="#cross2">ARMv5+<br>ARM9E+</a></td>
@@ -126,21 +130,21 @@ operating systems, CPUs and compilers:
126<td class="compatos compatno">&nbsp;</td> 130<td class="compatos compatno">&nbsp;</td>
127</tr> 131</tr>
128<tr class="even"> 132<tr class="even">
129<td class="compatcpu"><a href="#cross2">PPC</a></td> 133<td class="compatcpu"><a href="#cross2">ARM64<br>ARM64be</a></td>
130<td class="compatos">GCC 4.3+</td> 134<td class="compatos">GCC 4.8+</td>
131<td class="compatos">GCC 4.3+<br>GCC 4.1 (<a href="#ps3">PS3</a>)</td> 135<td class="compatos compatno">&nbsp;</td>
136<td class="compatos">XCode 6.0+<br>Clang 3.5+</td>
132<td class="compatos compatno">&nbsp;</td> 137<td class="compatos compatno">&nbsp;</td>
133<td class="compatos">XEDK (<a href="#xbox360">Xbox 360</a>)</td>
134</tr> 138</tr>
135<tr class="odd"> 139<tr class="odd">
136<td class="compatcpu"><a href="#cross2">PPC/e500v2</a></td> 140<td class="compatcpu"><a href="#cross2">PPC</a></td>
137<td class="compatos">GCC 4.3+</td>
138<td class="compatos">GCC 4.3+</td> 141<td class="compatos">GCC 4.3+</td>
142<td class="compatos">GCC 4.3+<br>GCC 4.1 (<a href="#ps3">PS3</a>)</td>
139<td class="compatos compatno">&nbsp;</td> 143<td class="compatos compatno">&nbsp;</td>
140<td class="compatos compatno">&nbsp;</td> 144<td class="compatos">XEDK (<a href="#xbox360">Xbox 360</a>)</td>
141</tr> 145</tr>
142<tr class="even"> 146<tr class="even">
143<td class="compatcpu"><a href="#cross2">MIPS</a></td> 147<td class="compatcpu"><a href="#cross2">MIPS32<br>MIPS64<br>MIPS64r6</a></td>
144<td class="compatos">GCC 4.3+</td> 148<td class="compatos">GCC 4.3+</td>
145<td class="compatos">GCC 4.3+</td> 149<td class="compatos">GCC 4.3+</td>
146<td class="compatos compatno">&nbsp;</td> 150<td class="compatos compatno">&nbsp;</td>
@@ -167,6 +171,13 @@ MSVC (Visual Studio).</li>
167Please read the instructions given in these files, before changing 171Please read the instructions given in these files, before changing
168any settings. 172any settings.
169</p> 173</p>
174<p>
175All LuaJIT 64 bit ports use 64 bit GC objects by default (<tt>LJ_GC64</tt>).
176For x64, you can select the old 32-on-64 bit mode by adding
177<tt>XCFLAGS=-DLUAJIT_DISABLE_GC64</tt> to the make command.
178Please check the note about the
179<a href="extensions.html#string_dump">bytecode format</a> differences, too.
180</p>
170 181
171<h2 id="posix">POSIX Systems (Linux, macOS, *BSD etc.)</h2> 182<h2 id="posix">POSIX Systems (Linux, macOS, *BSD etc.)</h2>
172<h3>Prerequisites</h3> 183<h3>Prerequisites</h3>
@@ -199,7 +210,7 @@ which is probably the default on your system, anyway. Simply run:
199make 210make
200</pre> 211</pre>
201<p> 212<p>
202This always builds a native x86, x64 or PPC binary, depending on the host OS 213This always builds a native binary, depending on the host OS
203you're running this command on. Check the section on 214you're running this command on. Check the section on
204<a href="#cross">cross-compilation</a> for more options. 215<a href="#cross">cross-compilation</a> for more options.
205</p> 216</p>
@@ -301,25 +312,36 @@ directory where <tt>luajit.exe</tt> is installed
301 312
302<h2 id="cross">Cross-compiling LuaJIT</h2> 313<h2 id="cross">Cross-compiling LuaJIT</h2>
303<p> 314<p>
315First, let's clear up some terminology:
316</p>
317<ul>
318<li>Host: This is your development system, usually based on a x64 or x86 CPU.</li>
319<li>Target: This is the target system you want LuaJIT to run on, e.g. Android/ARM.</li>
320<li>Toolchain: This comprises a C compiler, linker, assembler and a matching C library.</li>
321<li>Host (or system) toolchain: This is the toolchain used to build native binaries for your host system.</li>
322<li>Cross-compile toolchain: This is the toolchain used to build binaries for the target system. They can only be run on the target system.</li>
323</ul>
324<p>
304The GNU Makefile-based build system allows cross-compiling on any host 325The GNU Makefile-based build system allows cross-compiling on any host
305for any supported target, as long as both architectures have the same 326for any supported target:
306pointer size. If you want to cross-compile to any 32 bit target on an
307x64 OS, you need to install the multilib development package (e.g.
308<tt>libc6-dev-i386</tt> on Debian/Ubuntu) and build a 32 bit host part
309(<tt>HOST_CC="gcc -m32"</tt>).
310</p> 327</p>
328<ul>
329<li>Yes, you need a toolchain for both your host <em>and</em> your target!</li>
330<li>Both host and target architectures must have the same pointer size.</li>
331<li>E.g. if you want to cross-compile to a 32 bit target on a 64 bit host, you need to install the multilib development package (e.g. <tt>libc6-dev-i386</tt> on Debian/Ubuntu) and build a 32 bit host part (<tt>HOST_CC="gcc -m32"</tt>).</li>
332<li>64 bit targets always require compilation on a 64 bit host.</li>
333</ul>
311<p> 334<p>
312You need to specify <tt>TARGET_SYS</tt> whenever the host OS and the 335You need to specify <tt>TARGET_SYS</tt> whenever the host OS and the
313target OS differ, or you'll get assembler or linker errors. E.g. if 336target OS differ, or you'll get assembler or linker errors:
314you're compiling on a Windows or macOS host for embedded Linux or Android,
315you need to add <tt>TARGET_SYS=Linux</tt> to the examples below. For a
316minimal target OS, you may need to disable the built-in allocator in
317<tt>src/Makefile</tt> and use <tt>TARGET_SYS=Other</tt>. Don't forget to
318specify the same <tt>TARGET_SYS</tt> for the install step, too.
319</p> 337</p>
338<ul>
339<li>E.g. if you're compiling on a Windows or macOS host for embedded Linux or Android, you need to add <tt>TARGET_SYS=Linux</tt> to the examples below.</li>
340<li>For a minimal target OS, you may need to disable the built-in allocator in <tt>src/Makefile</tt> and use <tt>TARGET_SYS=Other</tt>.</li>
341<li>Don't forget to specify the same <tt>TARGET_SYS</tt> for the install step, too.</li>
342</ul>
320<p> 343<p>
321The examples below only show some popular targets &mdash; please check 344Here are some examples where host and target have the same CPU:
322the comments in <tt>src/Makefile</tt> for more details.
323</p> 345</p>
324<pre class="code"> 346<pre class="code">
325# Cross-compile to a 32 bit binary on a multilib x64 OS 347# Cross-compile to a 32 bit binary on a multilib x64 OS
@@ -337,34 +359,44 @@ use the canonical toolchain triplets for Linux.
337</p> 359</p>
338<p> 360<p>
339Since there's often no easy way to detect CPU features at runtime, it's 361Since there's often no easy way to detect CPU features at runtime, it's
340important to compile with the proper CPU or architecture settings. You 362important to compile with the proper CPU or architecture settings:
341can specify these when building the toolchain yourself. Or add 363</o>
342<tt>-mcpu=...</tt> or <tt>-march=...</tt> to <tt>TARGET_CFLAGS</tt>. For 364<ul>
343ARM it's important to have the correct <tt>-mfloat-abi=...</tt> setting, 365<li>The best way to get consistent results is to specify the correct settings when building the toolchain yourself.</li>
344too. Otherwise LuaJIT may not run at the full performance of your target 366<li>For a pre-built, generic toolchain add <tt>-mcpu=...</tt> or <tt>-march=...</tt> and other necessary flags to <tt>TARGET_CFLAGS</tt>.</li>
345CPU. 367<li>For ARM it's important to have the correct <tt>-mfloat-abi=...</tt> setting, too. Otherwise LuaJIT may not run at the full performance of your target CPU.</li>
368<li>For MIPS it's important to select a supported ABI (o32 on MIPS32, n64 on MIPS64) and consistently compile your project either with hard-float or soft-float compiler settings.</li>
369</ul>
370<p>
371Here are some examples for targets with a different CPU than the host:
346</p> 372</p>
347<pre class="code"> 373<pre class="code">
348# ARM soft-float 374# ARM soft-float
349make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabi- \ 375make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabi- \
350 TARGET_CFLAGS="-mfloat-abi=soft" 376 TARGET_CFLAGS="-mfloat-abi=soft"
351 377
352# ARM soft-float ABI with VFP (example for Cortex-A8) 378# ARM soft-float ABI with VFP (example for Cortex-A9)
353make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabi- \ 379make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabi- \
354 TARGET_CFLAGS="-mcpu=cortex-a8 -mfloat-abi=softfp" 380 TARGET_CFLAGS="-mcpu=cortex-a9 -mfloat-abi=softfp"
355 381
356# ARM hard-float ABI with VFP (armhf, requires recent toolchain) 382# ARM hard-float ABI with VFP (armhf, most modern toolchains)
357make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabihf- 383make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabihf-
358 384
385# ARM64
386make CROSS=aarch64-linux-
387
359# PPC 388# PPC
360make HOST_CC="gcc -m32" CROSS=powerpc-linux-gnu- 389make HOST_CC="gcc -m32" CROSS=powerpc-linux-gnu-
361# PPC/e500v2 (fast interpreter only)
362make HOST_CC="gcc -m32" CROSS=powerpc-e500v2-linux-gnuspe-
363 390
364# MIPS big-endian 391# MIPS32 big-endian
365make HOST_CC="gcc -m32" CROSS=mips-linux- 392make HOST_CC="gcc -m32" CROSS=mips-linux-
366# MIPS little-endian 393# MIPS32 little-endian
367make HOST_CC="gcc -m32" CROSS=mipsel-linux- 394make HOST_CC="gcc -m32" CROSS=mipsel-linux-
395
396# MIPS64 big-endian
397make CROSS=mips-linux- TARGET_CFLAGS="-mips64r2 -mabi=64"
398# MIPS64 little-endian
399make CROSS=mipsel-linux- TARGET_CFLAGS="-mips64r2 -mabi=64"
368</pre> 400</pre>
369<p> 401<p>
370You can cross-compile for <b id="android">Android</b> using the <a href="https://developer.android.com/ndk/"><span class="ext">&raquo;</span>&nbsp;Android NDK</a>. 402You can cross-compile for <b id="android">Android</b> using the <a href="https://developer.android.com/ndk/"><span class="ext">&raquo;</span>&nbsp;Android NDK</a>.
@@ -372,8 +404,16 @@ Please adapt the environment variables to match the install locations and the
372desired target platform. E.g. Android&nbsp;4.1 corresponds to ABI level&nbsp;16. 404desired target platform. E.g. Android&nbsp;4.1 corresponds to ABI level&nbsp;16.
373</p> 405</p>
374<pre class="code"> 406<pre class="code">
375# Android/ARM, armeabi-v7a (ARMv7 VFP), Android 4.1+ (JB) 407# Android/ARM64, aarch64, Android 5.0+ (L)
408NDKDIR=/opt/android/ndk
409NDKBIN=$NDKDIR/toolchains/llvm/prebuilt/linux-x86_64/bin
410NDKCROSS=$NDKBIN/aarch64-linux-android-
411NDKCC=$NDKBIN/aarch64-linux-android21-clang
412make CROSS=$NDKCROSS \
413 STATIC_CC=$NDKCC DYNAMIC_CC="$NDKCC -fPIC" \
414 TARGET_LD=$NDKCC
376 415
416# Android/ARM, armeabi-v7a (ARMv7 VFP), Android 4.1+ (JB)
377NDKDIR=/opt/android/ndk 417NDKDIR=/opt/android/ndk
378NDKBIN=$NDKDIR/toolchains/llvm/prebuilt/linux-x86_64/bin 418NDKBIN=$NDKDIR/toolchains/llvm/prebuilt/linux-x86_64/bin
379NDKCROSS=$NDKBIN/arm-linux-androideabi- 419NDKCROSS=$NDKBIN/arm-linux-androideabi-
@@ -383,9 +423,23 @@ make HOST_CC="gcc -m32" CROSS=$NDKCROSS \
383 TARGET_LD=$NDKCC 423 TARGET_LD=$NDKCC
384</pre> 424</pre>
385<p> 425<p>
386Please use the LuaJIT 2.1 branch to compile for 426You can cross-compile for <b id="ios">iOS 3.0+</b> (iPhone/iPad) using the <a href="https://developer.apple.com/ios/"><span class="ext">&raquo;</span>&nbsp;iOS SDK</a>:
387<b id="ios">iOS</b> (iPhone/iPad). 427</p>
428<p style="font-size: 8pt;">
429Note: <b>the JIT compiler is disabled for iOS</b>, because regular iOS Apps
430are not allowed to generate code at runtime. You'll only get the performance
431of the LuaJIT interpreter on iOS. This is still faster than plain Lua, but
432much slower than the JIT compiler. Please complain to Apple, not me.
433Or use Android. :-p
388</p> 434</p>
435<pre class="code">
436# iOS/ARM64
437ISDKP=$(xcrun --sdk iphoneos --show-sdk-path)
438ICC=$(xcrun --sdk iphoneos --find clang)
439ISDKF="-arch arm64 -isysroot $ISDKP"
440make DEFAULT_CC=clang CROSS="$(dirname $ICC)/" \
441 TARGET_FLAGS="$ISDKF" TARGET_SYS=iOS
442</pre>
389 443
390<h3 id="consoles">Cross-compiling for consoles</h3> 444<h3 id="consoles">Cross-compiling for consoles</h3>
391<p> 445<p>
@@ -441,6 +495,16 @@ the following commands:
441cd src 495cd src
442xedkbuild 496xedkbuild
443</pre> 497</pre>
498<p>
499To cross-compile for <b id="xboxone">Xbox One</b> from a Windows host,
500open a "Visual Studio .NET Command Prompt" (64&nbsp;bit host compiler),
501<tt>cd</tt> to the directory where you've unpacked the sources and run
502the following commands:
503</p>
504<pre class="code">
505cd src
506xb1build
507</pre>
444 508
445<h2 id="embed">Embedding LuaJIT</h2> 509<h2 id="embed">Embedding LuaJIT</h2>
446<p> 510<p>
@@ -469,16 +533,6 @@ the DLL). You may link LuaJIT statically on Windows only if you don't
469intend to load Lua/C modules at runtime. 533intend to load Lua/C modules at runtime.
470</li></ul> 534</li></ul>
471</li> 535</li>
472<li>
473<i>Important: this relates to LuaJIT 2.0 only &mdash; use LuaJIT 2.1 to
474avoid these complications.</i><br>
475If you're building a 64 bit application on macOS which links directly or
476indirectly against LuaJIT, you need to link your main executable
477with these flags:
478<pre class="code">
479-pagezero_size 10000 -image_base 100000000
480</pre>
481</li>
482</ul> 536</ul>
483<p>Additional hints for initializing LuaJIT using the C API functions:</p> 537<p>Additional hints for initializing LuaJIT using the C API functions:</p>
484<ul> 538<ul>
diff --git a/doc/luajit.html b/doc/luajit.html
index 42f32750..a25267a6 100644
--- a/doc/luajit.html
+++ b/doc/luajit.html
@@ -1,8 +1,8 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> 1<!DOCTYPE html>
2<html> 2<html>
3<head> 3<head>
4<title>LuaJIT</title> 4<title>LuaJIT</title>
5<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> 5<meta charset="utf-8">
6<meta name="Copyright" content="Copyright (C) 2005-2021"> 6<meta name="Copyright" content="Copyright (C) 2005-2021">
7<meta name="Language" content="en"> 7<meta name="Language" content="en">
8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen"> 8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
@@ -122,9 +122,13 @@ table.feature small {
122<a href="ext_ffi_semantics.html">FFI Semantics</a> 122<a href="ext_ffi_semantics.html">FFI Semantics</a>
123</li></ul> 123</li></ul>
124</li><li> 124</li><li>
125<a href="ext_buffer.html">String Buffers</a>
126</li><li>
125<a href="ext_jit.html">jit.* Library</a> 127<a href="ext_jit.html">jit.* Library</a>
126</li><li> 128</li><li>
127<a href="ext_c_api.html">Lua/C API</a> 129<a href="ext_c_api.html">Lua/C API</a>
130</li><li>
131<a href="ext_profiler.html">Profiler</a>
128</li></ul> 132</li></ul>
129</li><li> 133</li><li>
130<a href="status.html">Status</a> 134<a href="status.html">Status</a>
@@ -158,13 +162,13 @@ LuaJIT is Copyright &copy; 2005-2021 Mike Pall, released under the
158<tr><td><span style="font-size:90%;">Embedded</span></td><td>Android</td><td>iOS</td></tr> 162<tr><td><span style="font-size:90%;">Embedded</span></td><td>Android</td><td>iOS</td></tr>
159</table> 163</table>
160<table class="feature os os3"> 164<table class="feature os os3">
161<tr><td>PS3</td><td>PS4</td><td>PS Vita</td><td>Xbox 360</td></tr> 165<tr><td>PS3</td><td>PS4</td><td>PS Vita</td><td>Xbox 360</td><td>Xbox One</td></tr>
162</table> 166</table>
163<table class="feature compiler"> 167<table class="feature compiler">
164<tr><td>GCC</td><td>CLANG<br>LLVM</td><td>MSVC</td></tr> 168<tr><td>GCC</td><td>Clang<br>LLVM</td><td>MSVC</td></tr>
165</table> 169</table>
166<table class="feature cpu"> 170<table class="feature cpu">
167<tr><td>x86</td><td>x64</td><td>ARM</td><td>PPC</td><td>e500</td><td>MIPS</td></tr> 171<tr><td>x86<br>x64</td><td>ARM<br>ARM64</td><td>PPC</td><td>MIPS32<br>MIPS64</td></tr>
168</table> 172</table>
169<table class="feature fcompat"> 173<table class="feature fcompat">
170<tr><td>Lua&nbsp;5.1<br>API+ABI</td><td>+&nbsp;JIT</td><td>+&nbsp;BitOp</td><td>+&nbsp;FFI</td><td>Drop-in<br>DLL/.so</td></tr> 174<tr><td>Lua&nbsp;5.1<br>API+ABI</td><td>+&nbsp;JIT</td><td>+&nbsp;BitOp</td><td>+&nbsp;FFI</td><td>Drop-in<br>DLL/.so</td></tr>
diff --git a/doc/running.html b/doc/running.html
index ea46a97e..b55b8439 100644
--- a/doc/running.html
+++ b/doc/running.html
@@ -1,8 +1,8 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> 1<!DOCTYPE html>
2<html> 2<html>
3<head> 3<head>
4<title>Running LuaJIT</title> 4<title>Running LuaJIT</title>
5<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> 5<meta charset="utf-8">
6<meta name="Copyright" content="Copyright (C) 2005-2021"> 6<meta name="Copyright" content="Copyright (C) 2005-2021">
7<meta name="Language" content="en"> 7<meta name="Language" content="en">
8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen"> 8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
@@ -59,9 +59,13 @@ td.param_default {
59<a href="ext_ffi_semantics.html">FFI Semantics</a> 59<a href="ext_ffi_semantics.html">FFI Semantics</a>
60</li></ul> 60</li></ul>
61</li><li> 61</li><li>
62<a href="ext_buffer.html">String Buffers</a>
63</li><li>
62<a href="ext_jit.html">jit.* Library</a> 64<a href="ext_jit.html">jit.* Library</a>
63</li><li> 65</li><li>
64<a href="ext_c_api.html">Lua/C API</a> 66<a href="ext_c_api.html">Lua/C API</a>
67</li><li>
68<a href="ext_profiler.html">Profiler</a>
65</li></ul> 69</li></ul>
66</li><li> 70</li><li>
67<a href="status.html">Status</a> 71<a href="status.html">Status</a>
@@ -172,6 +176,7 @@ Here are the available LuaJIT control commands:
172<li id="j_flush"><tt>-jflush</tt> &mdash; Flushes the whole cache of compiled code.</li> 176<li id="j_flush"><tt>-jflush</tt> &mdash; Flushes the whole cache of compiled code.</li>
173<li id="j_v"><tt>-jv</tt> &mdash; Shows verbose information about the progress of the JIT compiler.</li> 177<li id="j_v"><tt>-jv</tt> &mdash; Shows verbose information about the progress of the JIT compiler.</li>
174<li id="j_dump"><tt>-jdump</tt> &mdash; Dumps the code and structures used in various compiler stages.</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>
175</ul> 180</ul>
176<p> 181<p>
177The <tt>-jv</tt> and <tt>-jdump</tt> commands are extension modules 182The <tt>-jv</tt> and <tt>-jdump</tt> commands are extension modules
diff --git a/doc/status.html b/doc/status.html
index 4ab20dd3..1d3ba984 100644
--- a/doc/status.html
+++ b/doc/status.html
@@ -1,8 +1,8 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> 1<!DOCTYPE html>
2<html> 2<html>
3<head> 3<head>
4<title>Status</title> 4<title>Status</title>
5<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> 5<meta charset="utf-8">
6<meta name="Copyright" content="Copyright (C) 2005-2021"> 6<meta name="Copyright" content="Copyright (C) 2005-2021">
7<meta name="Language" content="en"> 7<meta name="Language" content="en">
8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen"> 8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
@@ -40,9 +40,13 @@ ul li { padding-bottom: 0.3em; }
40<a href="ext_ffi_semantics.html">FFI Semantics</a> 40<a href="ext_ffi_semantics.html">FFI Semantics</a>
41</li></ul> 41</li></ul>
42</li><li> 42</li><li>
43<a href="ext_buffer.html">String Buffers</a>
44</li><li>
43<a href="ext_jit.html">jit.* Library</a> 45<a href="ext_jit.html">jit.* Library</a>
44</li><li> 46</li><li>
45<a href="ext_c_api.html">Lua/C API</a> 47<a href="ext_c_api.html">Lua/C API</a>
48</li><li>
49<a href="ext_profiler.html">Profiler</a>
46</li></ul> 50</li></ul>
47</li><li> 51</li><li>
48<a class="current" href="status.html">Status</a> 52<a class="current" href="status.html">Status</a>
@@ -56,7 +60,7 @@ ul li { padding-bottom: 0.3em; }
56</div> 60</div>
57<div id="main"> 61<div id="main">
58<p> 62<p>
59This documentation is for LuaJIT 2.0.5. Please check the <tt>doc</tt> 63This documentation is for LuaJIT 2.1.0-beta3. Please check the <tt>doc</tt>
60directory in each git branch for the version-specific documentation. 64directory in each git branch for the version-specific documentation.
61</p> 65</p>
62<p> 66<p>
@@ -88,12 +92,6 @@ The Lua <b>debug API</b> is missing a couple of features (return
88hooks for non-Lua functions) and shows slightly different behavior 92hooks for non-Lua functions) and shows slightly different behavior
89in LuaJIT (no per-coroutine hooks, no tail call counting). 93in LuaJIT (no per-coroutine hooks, no tail call counting).
90</li> 94</li>
91<li>
92Currently some <b>out-of-memory</b> errors from <b>on-trace code</b> are not
93handled correctly. The error may fall through an on-trace
94<tt>pcall</tt> or it may be passed on to the function set with
95<tt>lua_atpanic</tt> on x64.
96</li>
97</ul> 95</ul>
98<br class="flush"> 96<br class="flush">
99</div> 97</div>
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-08-05 00:22:08 +0000