aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorMike Pall <mike>2024-01-22 19:06:36 +0100
committerMike Pall <mike>2024-01-22 19:06:36 +0100
commit4b90f6c4d7420139c135435e1580acb52ea18436 (patch)
tree1c3543b6baa4f8b30a33e8a624b60edc6feb0206 /doc
parentc525bcb9024510cad9e170e12b6209aedb330f83 (diff)
downloadluajit-4b90f6c4d7420139c135435e1580acb52ea18436.tar.gz
luajit-4b90f6c4d7420139c135435e1580acb52ea18436.tar.bz2
luajit-4b90f6c4d7420139c135435e1580acb52ea18436.zip
Add cross-32/64 bit and deterministic bytecode generation.
Contributed by Peter Cawley. #993 #1008
Diffstat (limited to 'doc')
-rw-r--r--doc/extensions.html51
-rw-r--r--doc/running.html3
2 files changed, 42 insertions, 12 deletions
diff --git a/doc/extensions.html b/doc/extensions.html
index a4f20841..1d28475c 100644
--- a/doc/extensions.html
+++ b/doc/extensions.html
@@ -160,13 +160,33 @@ passes any arguments after the error function to the function
160which is called in a protected context. 160which is called in a protected context.
161</p> 161</p>
162 162
163<h3 id="load"><tt>loadfile()</tt> etc. handle UTF-8 source code</h3> 163<h3 id="load"><tt>load*()</tt> handle UTF-8 source code</h3>
164<p> 164<p>
165Non-ASCII characters are handled transparently by the Lua source code parser. 165Non-ASCII characters are handled transparently by the Lua source code parser.
166This allows the use of UTF-8 characters in identifiers and strings. 166This allows the use of UTF-8 characters in identifiers and strings.
167A UTF-8 BOM is skipped at the start of the source code. 167A UTF-8 BOM is skipped at the start of the source code.
168</p> 168</p>
169 169
170<h3 id="load_mode"><tt>load*()</tt> add a mode parameter</h3>
171<p>
172As an extension from Lua 5.2, the functions <tt>loadstring()</tt>,
173<tt>loadfile()</tt> and (new) <tt>load()</tt> add an optional
174<tt>mode</tt> parameter.
175</p>
176<p>
177The default mode string is <tt>"bt"</tt>, which allows loading of both
178source code and bytecode. Use <tt>"t"</tt> to allow only source code
179or <tt>"b"</tt> to allow only bytecode to be loaded.
180</p>
181<p>
182By default, the <tt>load*</tt> functions generate the native bytecode format.
183For cross-compilation purposes, add <tt>W</tt> to the mode string to
184force the 32 bit format and <tt>X</tt> to force the 64 bit format.
185Add both to force the opposite format. Note that non-native bytecode
186generated by <tt>load*</tt> cannot be run, but can still be passed
187to <tt>string.dump</tt>.
188</p>
189
170<h3 id="tostring"><tt>tostring()</tt> etc. canonicalize NaN and &plusmn;Inf</h3> 190<h3 id="tostring"><tt>tostring()</tt> etc. canonicalize NaN and &plusmn;Inf</h3>
171<p> 191<p>
172All number-to-string conversions consistently convert non-finite numbers 192All number-to-string conversions consistently convert non-finite numbers
@@ -186,26 +206,33 @@ works independently of the current locale and it supports hex floating-point
186numbers (e.g. <tt>0x1.5p-3</tt>). 206numbers (e.g. <tt>0x1.5p-3</tt>).
187</p> 207</p>
188 208
189<h3 id="string_dump"><tt>string.dump(f [,strip])</tt> generates portable bytecode</h3> 209<h3 id="string_dump"><tt>string.dump(f [,mode])</tt> generates portable bytecode</h3>
190<p> 210<p>
191An extra argument has been added to <tt>string.dump()</tt>. If set to 211An extra argument has been added to <tt>string.dump()</tt>. If set to
192<tt>true</tt>, 'stripped' bytecode without debug information is 212<tt>true</tt> or to a string which contains the character <tt>s</tt>,
193generated. This speeds up later bytecode loading and reduces memory 213'stripped' bytecode without debug information is generated. This speeds
194usage. See also the 214up later bytecode loading and reduces memory usage. See also the
195<a href="running.html#opt_b"><tt>-b</tt> command line option</a>. 215<a href="running.html#opt_b"><tt>-b</tt> command line option</a>.
196</p> 216</p>
197<p> 217<p>
198The generated bytecode is portable and can be loaded on any architecture 218The generated bytecode is portable and can be loaded on any architecture
199that LuaJIT supports, independent of word size or endianess. However, the 219that LuaJIT supports. However, the bytecode compatibility versions must
200bytecode compatibility versions must match. Bytecode stays compatible 220match. Bytecode only stays compatible within a major+minor version
201for dot releases (x.y.0 &rarr; x.y.1), but may change with major or 221(x.y.aaa &rarr; x.y.bbb), except for development branches. Foreign bytecode
202minor releases (2.0 &rarr; 2.1) or between any beta release. Foreign 222(e.g. from Lua 5.1) is incompatible and cannot be loaded.
203bytecode (e.g. from Lua 5.1) is incompatible and cannot be loaded.
204</p> 223</p>
205<p> 224<p>
206Note: <tt>LJ_GC64</tt> mode requires a different frame layout, which implies 225Note: <tt>LJ_GC64</tt> mode requires a different frame layout, which implies
207a different, incompatible bytecode format for all 64 bit ports. This may be 226a different, incompatible bytecode format between 32 bit and 64 bit ports.
208rectified in the future. 227This may be rectified in the future. In the meantime, use the <tt>W</tt>
228and </tt>X</tt> <a href="#load_mode">modes of the <tt>load*</tt> functions</a>
229for cross-compilation purposes.
230</p>
231<p>
232Due to VM hardening, bytecode is not deterministic. Add <tt>d</tt> to the
233mode string to dump it in a deterministic manner: identical source code
234always gives a byte-for-byte identical bytecode dump. This feature is
235mainly useful for reproducible builds.
209</p> 236</p>
210 237
211<h3 id="table_new"><tt>table.new(narray, nhash)</tt> allocates a pre-sized table</h3> 238<h3 id="table_new"><tt>table.new(narray, nhash)</tt> allocates a pre-sized table</h3>
diff --git a/doc/running.html b/doc/running.html
index 9dd2b411..142b810f 100644
--- a/doc/running.html
+++ b/doc/running.html
@@ -106,6 +106,9 @@ are accepted:
106<li><tt>-l</tt> &mdash; Only list bytecode.</li> 106<li><tt>-l</tt> &mdash; Only list bytecode.</li>
107<li><tt>-s</tt> &mdash; Strip debug info (this is the default).</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> 108<li><tt>-g</tt> &mdash; Keep debug info.</li>
109<li><tt>-W</tt> &mdash; Generate 32 bit (non-GC64) bytecode.</li>
110<li><tt>-X</tt> &mdash; Generate 64 bit (GC64) bytecode.</li>
111<li><tt>-d</tt> &mdash; Generate bytecode in deterministic manner.</li>
109<li><tt>-n name</tt> &mdash; Set module name (default: auto-detect from input name)</li> 112<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> 113<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> 114<li><tt>-a arch</tt> &mdash; Override architecture for object files (default: native).</li>