From 4b90f6c4d7420139c135435e1580acb52ea18436 Mon Sep 17 00:00:00 2001 From: Mike Pall Date: Mon, 22 Jan 2024 19:06:36 +0100 Subject: Add cross-32/64 bit and deterministic bytecode generation. Contributed by Peter Cawley. #993 #1008 --- doc/extensions.html | 51 +++++++++++++++++++++++++++++++++++++++------------ doc/running.html | 3 +++ 2 files changed, 42 insertions(+), 12 deletions(-) (limited to 'doc') 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 which is called in a protected context.

-

loadfile() etc. handle UTF-8 source code

+

load*() handle UTF-8 source code

Non-ASCII characters are handled transparently by the Lua source code parser. This allows the use of UTF-8 characters in identifiers and strings. A UTF-8 BOM is skipped at the start of the source code.

+

load*() add a mode parameter

+

+As an extension from Lua 5.2, the functions loadstring(), +loadfile() and (new) load() add an optional +mode parameter. +

+

+The default mode string is "bt", which allows loading of both +source code and bytecode. Use "t" to allow only source code +or "b" to allow only bytecode to be loaded. +

+

+By default, the load* functions generate the native bytecode format. +For cross-compilation purposes, add W to the mode string to +force the 32 bit format and X to force the 64 bit format. +Add both to force the opposite format. Note that non-native bytecode +generated by load* cannot be run, but can still be passed +to string.dump. +

+

tostring() etc. canonicalize NaN and ±Inf

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 numbers (e.g. 0x1.5p-3).

-

string.dump(f [,strip]) generates portable bytecode

+

string.dump(f [,mode]) generates portable bytecode

An extra argument has been added to string.dump(). If set to -true, 'stripped' bytecode without debug information is -generated. This speeds up later bytecode loading and reduces memory -usage. See also the +true or to a string which contains the character s, +'stripped' bytecode without debug information is generated. This speeds +up later bytecode loading and reduces memory usage. See also the -b command line option.

The generated bytecode is portable and can be loaded on any architecture -that LuaJIT supports, independent of word size or endianess. However, the -bytecode compatibility versions must match. Bytecode stays compatible -for dot releases (x.y.0 → x.y.1), but may change with major or -minor releases (2.0 → 2.1) or between any beta release. Foreign -bytecode (e.g. from Lua 5.1) is incompatible and cannot be loaded. +that LuaJIT supports. However, the bytecode compatibility versions must +match. Bytecode only stays compatible within a major+minor version +(x.y.aaa → x.y.bbb), except for development branches. Foreign bytecode +(e.g. from Lua 5.1) is incompatible and cannot be loaded.

Note: LJ_GC64 mode requires a different frame layout, which implies -a different, incompatible bytecode format for all 64 bit ports. This may be -rectified in the future. +a different, incompatible bytecode format between 32 bit and 64 bit ports. +This may be rectified in the future. In the meantime, use the W +and X modes of the load* functions +for cross-compilation purposes. +

+

+Due to VM hardening, bytecode is not deterministic. Add d to the +mode string to dump it in a deterministic manner: identical source code +always gives a byte-for-byte identical bytecode dump. This feature is +mainly useful for reproducible builds.

table.new(narray, nhash) allocates a pre-sized table

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:
  • -l — Only list bytecode.
  • -s — Strip debug info (this is the default).
  • -g — Keep debug info.
    • +
  • -W — Generate 32 bit (non-GC64) bytecode.
    • +
  • -X — Generate 64 bit (GC64) bytecode.
    • +
  • -d — Generate bytecode in deterministic manner.
  • -n name — Set module name (default: auto-detect from input name)
  • -t type — Set output file type (default: auto-detect from output name).
  • -a arch — Override architecture for object files (default: native).
    • -- cgit v1.2.3-55-g6feb