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