lrc

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

Starting from a single Lua file (entrypoint), it automatically resolves any required Lua modules, file resources and native modules recursively, based on require() and io.open() statements.

Basic Command-Line Example

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

Target Support

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

There are also extensions which add support for more source languages and target formats (e.g. WebAssembly) and you can write your own extensions.

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 fine-tuned using the LRocket Spec format or via command-line options. Below you can find a list of available command-line options:

Module Search Options

Arguments

  • entrypoint – Main lua file

  • extra-files – Extra (C,object,archive,lra) files to compile with

Option

Description

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

Lua search path

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

package.cpath module search path (for compiled shared libraries)

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

Static pendant for package.cpath search path

--xpath <xpath>

Extended search path for non standard modules : (natively supported are lua,shared,static,c,teal)

-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: **)

Include these optional modules. This argument enables optional module parsing for specified statements (using [x]pcall)

--no-opt

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

--runtime-path <runtime_path>

Runtime LUA_PATH used for lua modules (supports ?? and !)

--runtime-cpath <runtime_cpath>

Runtime LUA_CPATH used for lua modules (supports ?? and !)

Search Paths

The path options --path, --spath and --cpath are used to specify where lrc should look for Lua-modules.

lrc processes them in-order, as written in the command-line.

If you for example wish to prefer the static versions of native modules (.a / .lib) over shared libraries (.so / .dll), place the --spath argument before --cpath.

Syntax

The path-options follow a similar syntax as the standard Lua path:

  • ? – wildcard for the required module name

  • ; – separates multiple paths

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

In addition, the suffix ?? can be used to append a standard Lua path pattern or respectively expand the path into multiple paths.

For --path, this can be especially useful: 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.).

Insights

You can ask lrc to print the final calculated search-paths by setting the log level to --log-level=detail.

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.5,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

--target <target>

Cross compilation target

--sysroot <sysroot>

Sysroot for finding crossbuild libraries

--tree <tree>

Add a tree in which Lua libraries and headers should be searched

-K
--keep

Do not remove intermediate C code after compilation

--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 by scanning equally named dynamic modules

--liblua-shared

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

Lua Version Selection

lrc automatically detects and links against the latest installed Lua version.

To specify a different version use the --lua-version command-line argument.

Pre-compiling Lua Code

If optimization is enabled, pre-compiled Lua-bytecode is embedded into the target binary instead of the source-code.

Debug Information

Executables and shared libraries are minified automatically via the strip command. This can be disabled (e.g. for debugging) using the --debug <mode> command-line argument.

The following possible values for <mode> control which information is preserved inside the bundle for printing stacktraces:

  • all: Preserves the absolute filepath of all modules

  • project: Preserves only the relative filepath 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).

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>

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

-v
--verbose

Increase the log_level by one