Running LuaVela

Note

The internal name of LuaVela in IPONWEB is uJIT. These two along with respective CLI names may be used interchangeably in the documentation for historical reasons.

Note

This manual is effective as of LuaVela 0.7 release. Please beware: Although it originates from LuaJIT’s CLI guide, current set of CLI options supported by LuaVela differs significantly. For older LuaVela releases, please use the aforementioned LuaJIT’s guide.

Note

Prior to LuaVela 0.15 the name of the executable was luajit.

General CLI Options

LuaVela has only a single stand-alone executable, called ujit. It can be used to run simple Lua statements or whole Lua applications from the command line. It has an interactive mode, too.

The ujit stand-alone executable is just a slightly modified version of the regular lua stand-alone executable. It supports the same basic options, too. ujit -h prints a short list of the available options. Please have a look at the Lua 5.1 Reference Manual for details. The sections below cover additional options provided by LuaVela .

LuaVela Interpreter Options

-b (dump bytecode)

$ ujit -b output ...

Dumps bytecode of the chunk saving it to the output file in human readable form. output parameter is required and cannot be omitted. To dump to stdout, set output to - (dash character).

Output file is overwritten on each run.

Typical usage examples:

$ ujit -b test.out test.lua                  # List bytecode to test.out
$ ujit -b test.out -e "print('hello world')" # List cmdline script's bytecode to test.out
$ ujit -b- test.lua                          # List bytecode to stdout
$ ujit -b- -e "print('hello world')"         # List cmdline script's bytecode to stdout

-B (dump bytecode with source)

$ ujit -B output script_file.lua

Similar to -b, but also prints a source code which corresponds to each bytecode (similar to ‘disassembly /s’ in gdb). If command line chunk is given instead of a script file, prints a warning and dumps bytecode as -b.

LuaVela General Compiler Options

LuaVela provides a number of options for manipulating JIT compiler’s behaviour. General syntax is following:

$ ujit -j cmd[=arg[,arg...]] ...

This option performs a LuaVela control command or activates one of the loadable extension modules. The command is first looked up in the jit.* library. If no matching function is found, a module named jit.<cmd> is loaded and the start() function of the module is called with the specified arguments (if any). The space between -j and cmd is optional.

Control Commands

$ ujit -jcmd

Following commands are supported:

Command	Description
on	Turns the JIT compiler on (default).
off	Turns the JIT compiler off (only use the interpreter).
flush	Flushes the whole cache of compiled code.

Dumping Compiler Progress

$ ujit -p output ...

Executes a chunk and dumps compiler’s progress as the execution moves on. For each trace, following information is dumped:

• Bytecode corresponding to the recorded trace.
• IR of the trace, along with emitted snapshots and information about allocated host registers (if available, i.e. if trace recording was not aborted).
• Machine code of the trace (if available, i.e. if trace recording was not aborted).
• If trace recoding was aborted, specifies the abort reason.
• If the trace exited during script execution, exit state is dumped.

output parameter is required and cannot be omitted. To dump to stdout, set output to - (dash character). Output file is overwritten on each run.

LuaVela Compiler Optimization Options

$ ujit -O[level] ...
$ ujit -O[+]flag -O-flag ...
$ ujit -Oparam=value ...

This options allows fine-tuned control of the optimizations used by the JIT compiler. This is mainly intended for debugging LuaVela itself. Please note that the JIT compiler is extremely fast (we are talking about the microsecond to millisecond range). Disabling optimizations doesn’t have any visible impact on its overhead, but usually generates code that runs slower.

The first form sets an optimization level — this enables a specific mix of optimization flags. -O0 turns off all optimizations and higher numbers enable more optimizations. Omitting the level (i.e. just -O) sets the default optimization level, which is -O3 in the current version. Optimizations specific to`` -O4`` are either experimental or known to work improperly.

From within Lua code optimization level can be set by the same integer values passed as a first argument to jit.opt.start(<optimization_level>, ...).

The second form adds or removes individual optimization flags. The third form sets a parameter for the VM or the JIT compiler to a specific value.

You can either use this option multiple times (like -Ocse -O-dce -Ohotloop=10) or separate several settings with a comma (like -O+cse,-dce,hotloop=10). The settings are applied from left to right and later settings override earlier ones. You can freely mix the three forms, but note that setting an optimization level overrides all earlier flags.

To set individual option flags from within Lua code, define each one as a separate argument to jii.opt.start e.g.``jit.opt.start(“-sink”, “+loop”).``

Here are the available flags and at what optimization levels they are enabled:

Flag	-01	-02	-03	-04	WIP	Description
fold	✅	✅	✅	✅		Constant Folding, Simplifications and Reassociation
cse	✅	✅	✅	✅		Common-Subexpression Elimination
dce	✅	✅	✅	✅		Dead-Code Elimination
narrow		✅	✅	✅		Narrowing of numbers to integers
loop		✅	✅	✅		Loop Optimizations (code hoisting)
fwd			✅	✅		Load Forwarding (L2L) and Store Forwarding (S2L)
dse			✅	✅		Dead-Store Elimination
abc			✅	✅		Array Bounds Check Elimination
sink			✅	✅		Allocation Sinking Optimization
fuse					❗	Fusion of operands into instructions. This optimization is currently a no-op in LuaVela at the moment.
nohrefk				✅		Disables emission of the HREFK IR instruction. Available since LuaVela 0.10.
noretl				✅		Disables recording of returns to lower Lua frames. Available since LuaVela 0.10.
jitcat				✅		Enables compilation of concatenation. Available since LuaVela 0.11.
jittabcat				✅		Enables compilation of table.concat. Available since LuaVela 0.20.
jitstr				✅		Enables compilation of string.find, string.lower, string.upper. Available since LuaVela 0.20.
movtv					❗	Optimizes copying data between tables. Available since LuaVela 0.23.
movtvpri					❗	Same as movtv, but for recording-time nil, false and true values. Available since LuaVela 0.24.
jitpairs					❗	Enables compilation of ‘pairs’ and ‘next’. Available since LuaVela 0.22, but is known to produce incorrect results sometimes. Work on fix in progress.

Notes:

• -O3 is the default set of optimizations provided by LuaJIT
• -O4 is -O3 plus the set of optimizations specific to LuaVela

Here are the parameters and their default values:

Parameter	Default	Description
maxtrace	1000	Maximum number of traces in the cache
maxrecord	4000	Maximum number of recorded IR instructions
maxirconst	500	Maximum number of IR constants of a trace
maxside	100	Maximum number of side traces of a root trace
maxsnap	500	Maximum number of snapshots for a trace
hotloop	56	Number of iterations to detect a hot loop or hot call
hotexit	10	Number of taken exits to start a side trace
tryside	4	Number of attempts to compile a side trace
instunroll	4	Maximum unroll factor for instable loops
loopunroll	15	Maximum unroll factor for loop ops in side traces
callunroll	3	Maximum unroll factor for pseudo-recursive calls
recunroll	2	Minimum unroll factor for true recursion
sizemcode	64	Size of each machine code area in KBytes (In LuaJIT default value is 32. This might be important for comparing JIT performance)
maxmcode	8192	Maximum total size of all machine code areas in KBytes (In LuaJIT default value is 512. This might be important for comparing JIT performance)

Warning

Unlike LuaJIT, LuaVela does not support -Onodce syntax for optimization flags, use -O-dce for switching certain optimizations off.

Extended Configuration Options

Note

This section applies to LuaVela 0.21 and above.

LuaVela supports extended configuration options in the form of

$ ujit -X opt1=value1 -X opt2=value2

When CLI is invoked, these options are read first and are used for creating an according virtual machine instance.

Supported options:

Option	Description	Supported Values	Availability
hashf	Hashing function used for interning strings across the platform	murmur (default) city	Since LuaVela 0.21
itern	Enables ITERN optimization in frontend	on (default) off	Since LuaVela 0.22