Lua

This documentation is for LuaJIT 2.1. Please check the doc directory in each git branch for the version-specific documentation.

LuaJIT has only a single stand-alone executable, called luajit on POSIX systems or luajit.exe on Windows. It can be used to run simple Lua statements or whole Lua applications from the command line. It has an interactive mode, too.

Command Line Options

The luajit stand-alone executable is just a slightly modified version of the regular lua stand-alone executable. It supports the same basic options, too. luajit -h prints a short list of the available options. Please have a look at the Lua manual for details.

LuaJIT has some additional options:

-b[options] input output

This option saves or lists bytecode. The following additional options are accepted:

The output file type is auto-detected from the extension of the output file name:

Notes:

Typical usage examples:

luajit -b test.lua test.out                 # Save bytecode to test.out
luajit -bg test.lua test.out                # Keep debug info
luajit -be "print('hello world')" test.out  # Save cmdline script

luajit -bl test.lua                         # List to stdout
luajit -bl test.lua test.txt                # List to test.txt
luajit -ble "print('hello world')"          # List cmdline script

luajit -b test.lua test.obj                 # Generate object file
# Link test.obj with your application and load it with require("test")

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

This option performs a LuaJIT 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.

Here are the available LuaJIT control commands:

The -jv and -jdump commands are extension modules written in Lua. They are mainly used for debugging the JIT compiler itself. For a description of their options and output format, please read the comment block at the start of their source. They can be found in the lib directory of the source distribution or installed under the jit directory. By default, this is /usr/local/share/luajit-XX.YY.ZZ>/jit on POSIX systems (replace XX.YY.ZZ by the installed version).

-O[level]
-O[+]flag   -O-flag
-Oparam=value

This options allows fine-tuned control of the optimizations used by the JIT compiler. This is mainly intended for debugging LuaJIT 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.

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.

Note that -Ofma is not enabled by default at any level, because it affects floating-point result accuracy. Only enable this, if you fully understand the trade-offs of FMA for performance (higher), determinism (lower) and numerical accuracy (higher).

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

Flag -O1 -O2 -O3  
foldConstant Folding, Simplifications and Reassociation
cseCommon-Subexpression Elimination
dceDead-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/Store Sinking
fuse  Fusion of operands into instructions
fma    Fused multiply-add

Here are the parameters and their default settings:

Parameter Default  
maxtrace1000Max. number of traces in the cache
maxrecord4000Max. number of recorded IR instructions
maxirconst500Max. number of IR constants of a trace
maxside100Max. number of side traces of a root trace
maxsnap500Max. number of snapshots for a trace
hotloop56Number of iterations to detect a hot loop or hot call
hotexit10Number of taken exits to start a side trace
tryside4Number of attempts to compile a side trace
instunroll4Max. unroll factor for instable loops
loopunroll15Max. unroll factor for loop ops in side traces
callunroll3Max. unroll factor for pseudo-recursive calls
recunroll2Min. unroll factor for true recursion
sizemcode32Size of each machine code area in KBytes (Windows: 64K)
maxmcode512Max. total size of all machine code areas in KBytes