Running LuaVela


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.


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.


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.


  • -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)


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

Extended Configuration Options


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