diff options
author | Mike Pall <mike> | 2024-01-22 19:06:36 +0100 |
---|---|---|
committer | Mike Pall <mike> | 2024-01-22 19:06:36 +0100 |
commit | 4b90f6c4d7420139c135435e1580acb52ea18436 (patch) | |
tree | 1c3543b6baa4f8b30a33e8a624b60edc6feb0206 /doc | |
parent | c525bcb9024510cad9e170e12b6209aedb330f83 (diff) | |
download | luajit-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.html | 51 | ||||
-rw-r--r-- | doc/running.html | 3 |
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 | |||
160 | which is called in a protected context. | 160 | which 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> |
165 | Non-ASCII characters are handled transparently by the Lua source code parser. | 165 | Non-ASCII characters are handled transparently by the Lua source code parser. |
166 | This allows the use of UTF-8 characters in identifiers and strings. | 166 | This allows the use of UTF-8 characters in identifiers and strings. |
167 | A UTF-8 BOM is skipped at the start of the source code. | 167 | A 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> | ||
172 | As 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> | ||
177 | The default mode string is <tt>"bt"</tt>, which allows loading of both | ||
178 | source code and bytecode. Use <tt>"t"</tt> to allow only source code | ||
179 | or <tt>"b"</tt> to allow only bytecode to be loaded. | ||
180 | </p> | ||
181 | <p> | ||
182 | By default, the <tt>load*</tt> functions generate the native bytecode format. | ||
183 | For cross-compilation purposes, add <tt>W</tt> to the mode string to | ||
184 | force the 32 bit format and <tt>X</tt> to force the 64 bit format. | ||
185 | Add both to force the opposite format. Note that non-native bytecode | ||
186 | generated by <tt>load*</tt> cannot be run, but can still be passed | ||
187 | to <tt>string.dump</tt>. | ||
188 | </p> | ||
189 | |||
170 | <h3 id="tostring"><tt>tostring()</tt> etc. canonicalize NaN and ±Inf</h3> | 190 | <h3 id="tostring"><tt>tostring()</tt> etc. canonicalize NaN and ±Inf</h3> |
171 | <p> | 191 | <p> |
172 | All number-to-string conversions consistently convert non-finite numbers | 192 | All 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 | |||
186 | numbers (e.g. <tt>0x1.5p-3</tt>). | 206 | numbers (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> |
191 | An extra argument has been added to <tt>string.dump()</tt>. If set to | 211 | An 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>, |
193 | generated. This speeds up later bytecode loading and reduces memory | 213 | 'stripped' bytecode without debug information is generated. This speeds |
194 | usage. See also the | 214 | up 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> |
198 | The generated bytecode is portable and can be loaded on any architecture | 218 | The generated bytecode is portable and can be loaded on any architecture |
199 | that LuaJIT supports, independent of word size or endianess. However, the | 219 | that LuaJIT supports. However, the bytecode compatibility versions must |
200 | bytecode compatibility versions must match. Bytecode stays compatible | 220 | match. Bytecode only stays compatible within a major+minor version |
201 | for dot releases (x.y.0 → x.y.1), but may change with major or | 221 | (x.y.aaa → x.y.bbb), except for development branches. Foreign bytecode |
202 | minor releases (2.0 → 2.1) or between any beta release. Foreign | 222 | (e.g. from Lua 5.1) is incompatible and cannot be loaded. |
203 | bytecode (e.g. from Lua 5.1) is incompatible and cannot be loaded. | ||
204 | </p> | 223 | </p> |
205 | <p> | 224 | <p> |
206 | Note: <tt>LJ_GC64</tt> mode requires a different frame layout, which implies | 225 | Note: <tt>LJ_GC64</tt> mode requires a different frame layout, which implies |
207 | a different, incompatible bytecode format for all 64 bit ports. This may be | 226 | a different, incompatible bytecode format between 32 bit and 64 bit ports. |
208 | rectified in the future. | 227 | This may be rectified in the future. In the meantime, use the <tt>W</tt> |
228 | and </tt>X</tt> <a href="#load_mode">modes of the <tt>load*</tt> functions</a> | ||
229 | for cross-compilation purposes. | ||
230 | </p> | ||
231 | <p> | ||
232 | Due to VM hardening, bytecode is not deterministic. Add <tt>d</tt> to the | ||
233 | mode string to dump it in a deterministic manner: identical source code | ||
234 | always gives a byte-for-byte identical bytecode dump. This feature is | ||
235 | mainly 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> — Only list bytecode.</li> | 106 | <li><tt>-l</tt> — Only list bytecode.</li> |
107 | <li><tt>-s</tt> — Strip debug info (this is the default).</li> | 107 | <li><tt>-s</tt> — Strip debug info (this is the default).</li> |
108 | <li><tt>-g</tt> — Keep debug info.</li> | 108 | <li><tt>-g</tt> — Keep debug info.</li> |
109 | <li><tt>-W</tt> — Generate 32 bit (non-GC64) bytecode.</li> | ||
110 | <li><tt>-X</tt> — Generate 64 bit (GC64) bytecode.</li> | ||
111 | <li><tt>-d</tt> — Generate bytecode in deterministic manner.</li> | ||
109 | <li><tt>-n name</tt> — Set module name (default: auto-detect from input name)</li> | 112 | <li><tt>-n name</tt> — Set module name (default: auto-detect from input name)</li> |
110 | <li><tt>-t type</tt> — Set output file type (default: auto-detect from output name).</li> | 113 | <li><tt>-t type</tt> — Set output file type (default: auto-detect from output name).</li> |
111 | <li><tt>-a arch</tt> — Override architecture for object files (default: native).</li> | 114 | <li><tt>-a arch</tt> — Override architecture for object files (default: native).</li> |