The LRocket Project

The LRocket Compiler (lrc) bundles and compiles Lua programs into 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.

Some advanced features of lrc include cross-compilation arbitrary resource embedding and compiler extensions.

Usage

> lrc main.lua
# outputs ./main (exectuable, or main.exe on Windows)

lrc supports many options and there is integration for the luarocks module manager and build system.

For a full list of options see https://lrocket.codeberg.page/lrc.html.

Installation

The compiler is available on luarocks!

> luarocks install lrc

From Source (e.g. for Development)

> git clone https://codeberg.org/lrocket/lrc
> cd lrc
# compile C bits
> luarocks make --no-install
# run directly via:
> lua cmd/lrc.lua

Features

• Dependency Tracing and Bundling
  • Packs lua programs/modules into a single bundle
  • Links C modules into the target binary or
  • Copies shared libraries (.so/.dll) into target directory
• Static and Dynamic Linking support
• Embedding of Arbitrary Resource-Files
• Cross-Compilation
• Integration with LuaRocks
• Platform Support
  • Linux
  • Windows
  • macOS was not tested
  • WebAssembly
• Output Formats
  • Lua Bundle (single .lua-file)
  • Native Executable (e.g. ELF64 or .exe)
  • Native Lua Module (.dll/.so)
• Lua Versions
  • Supports 5.4, 5.3, 5.2, 5.1 and LuaJIT
  • Automatically finds lua in system paths (and via pkg-config if installed)
  • Allows multiple lua versions to be installed with flag to select a version
• Language Support for C and Teal modules
• Debugging: Compiled executables support lua debuggers (e.g. Local Lua Debugger)
• Optional Embedding of Bytecode
• Optimization Profiles (space / speed)
• Bash/ZSH Completion
• Log Levels
• Many Command-Line Options
• lrc supports custom Compiler Extensions

Hacking

The functionality of lrc can be expanded with custom Compiler Extensions! Read more here: Hacking the LRocket Compiler.

License

LRocket is licensed under the MIT License.

The Lua Programming Language logo was created by Alexandre Nakonechnyj.

Related Works

LRocket was inspired by and is loosely based on luastatic.

During late development we also found luapak, which does an awesome job at bundling and shares some concepts with lrc! Both however have some unique features:

The main differences being that luapak supports compression of lua source code while lrocket does not rely on luarocks and has broader platform support for some features like static-linking.

Known Issues

See Troubleshooting or in case of doubt, feel free to open an issue!

Have a fix ready? Cool! Just file an issue for the problem you're fixing if nobody has done so yet and reference it when submitting your Pull-Request.

Changelog

See changelog.md.

Created by Sewbacca and Lesosoftware in 2023 - 2026