lrc

The lrocket compiler (lrc) bundles and compiles Lua programs to several formats.

It’s typically invoked by specifying a single lua file that serves as entrypoint. From thereon lrc automatically resolves any further lua files and modules based on require() statements in the overall code.

Basic Command-Line Example

# results in the program `main` (or `main.exe` on Windows)
$ lrc main.lua

Target Support

At the moment lrc supports compiling into native executables, shared libraries, bundled lua files and C code representing either a native executable or a shared library.

If an output filename is given via the -o-flag and the target format has not been specified via the --otype-flag, it is derrived from the output file extension (e.g. .exe for “executable” on Windows or no file extension on Linux or macOS).

The compilation can be tuned using several command line options. A full listing can be found below:

Module Search Options

Arguments

  • entrypoint – Main lua file

Option

Description

-P <package.path>
--path <package.path>

(default: ./?.lua;./?/init.lua;;)

Lua search path

-C <package.cpath>
--cpath <package.cpath>

(default: ./?.dll;;)

C modules search path

-S <archive-path>
--spath <archive-path>

(default: ./?.a;;)

Static C module search path

-x <module>
--exclude <module>

Exclude given module from search

-m <module>
--module <module>

Explicitly include module

--fuzzy {yes,no}

(default: yes)

Examine complex require statements when resolving modules

--opt [<opt>]

(default: **)

Enables optional module parsing for specified (statements using [x]pcall)

--no-opt

excludes optional modules from search (will be deprecated in 2)

The path options --path, --spath and --cpath are used to specify where lrc should look for Lua-modules. They are processed in-order as written in the command-line. To for example priorize the static versions of native modules (.a / .lib), place the --spath argument before --cpath.

The syntax for the path-options is based on the standard Lua path syntax:

  • ? is a wildcard for the required module name

  • Individual paths are seperated by ;

  • ;; is replaced by the Interpreter’s standard-paths

In addition, the suffix ?? can be used to append a standard Lua path pattern or expand the path into multiple paths. This is especially useful for --path: e.g. lua/?? will be replaced by lua/?.lua;lua/?/init.lua. For --cpath and --spath the library file extensions are chosen based on the current platform and toolchain (i.e. ?.so, ?.a, etc.).

The final search-paths calculated by lrc can be observed by specifying --log-level=debug.

Output Options

Arguments

  • compiler-args – Extra arguments to the C compiler

Option

Description

-o <output>
--output <output>

Output filename

--otype {executable,executable-c,lua,shared,shared-c}

(default: autodetect from --output extension)

Output file format

--lua-version {auto,5.4,5.3,5.2,jit,5.1}

(default: auto)

Target lua version

-g [{all,project,module}]
--debug [{all,project,module}]

Add specified debugging information to the output target

-O [{space,speed}]
--optimize [{space,speed}]

Enable optimizations

-K
--keep

Do not remove intermediate C code after compilation

If any optimization is enabled, Lua-bytecode is embedded in the target binary instead of the source-code. To prevent the execution of strip, enable the --debug option and set it to one of the following options, which control which information is preserved inside the bundle to print stacktraces:

  • all: Preserves the full filepath of all modules

  • project: Only preserves the relative filepaths of modules inside or below the project directory (use this option to keep filenames while hiding information about the build environment).

  • module: Drop all module filepaths, preserving only dot-separated module-names (same path as used for require).

The newest installed Lua version is detected and linked against automatically. To specify a different version use the --lua-version option.

Executable Options

Option

Description

--copy-native-libs

Copies required shared C libraries to the output directory

--link-sibling-deps {yes,no}

(default: yes)

Resolve dynamic dependencies of statically linked lua modules (.a) by scanning equally named dynamic modules (.dll)

--liblua-shared

Link against the dynamic variant of the Lua library (default is static)

--windows-gui

Link with /SUBSYSTEM:WINDOWS (or -mwindows for MinGW)

--no-runtime-cache

Forces recompilation of runtime cache

Shared Library Options

Option

Description

--modname <modname>

module name of the shared library, used for luaopen_

--export <modname>

export additional luaopen_ (supports globs)

Other options

Option

Description

-h
--help

Show this help message and exit.

--completion {bash,zsh,fish}

Output a shell completion script for the specified shell.

--perf

Show instrumentalized timings

--perf-log <filename>

(dev) Log profiling stacktraces to this file (flamegraph format)

--version

Prints version and exits

--log-level <log-level>

(default: warn)

ascending: none (0), error, warn, info, debug