LuaRocks Integration

The LRocket Project is integrated with the LuaRocks package manager and its build system.

To compile something with lrc via LuaRocks, simply set build.type = 'lrocket' in your rockspec:

build = {
    type = 'lrocket',
    entrypoint = 'main.lua',
    output = 'bin/program' -- compiles into ./bin/program or 'bin/program.exe' on windows
}

Note If you are running an old version of luarocks <3.11, you will need to add luarocks-build-lrocket module to the dependencies of their rockspec file. For recent versions of LuaRocks, the module will be installed automatically when you build a rock that uses it.

Running the luarocks make command will now bundle and compile all code contained in the entrypoint main.lua and produce ./bin/program (or bin/program.exe on windows).

Naturally this will also include the code of all additional Lua files and c modules required by the file:

> luarocks make

What about C-based rocks and static linking, won’t that be a problem?

The integration (luarocks-build-lrocket) configures LuaRocks to compile all newly installed packages or dependencies that contain C code into both, a shared library (.dll/.so) and a static archive (.a/.lib)!

This means any native package available on luarocks.org and supported by the mechanism* can be statically linked into the executable with no extra .dll/.so required.

If a native package is not supported, lrc will automatically fallback to using the .dll/.so instead. This can also be configured using the prefer_c_module_type rockspec build option (see the section below for a full list of available build options).

* The method is based on the lr-hooks framework and works on any package that uses the luarocks builtin or rust build system and is likely to work on packages using a Makefile.

rockspec Build Options

The integration passes any option specified in the build = {} table of your rockspec to the LRocket Compiler.

This allows you to use the LRocket Spec format directly from inside your rockspec!

LRocket Spec is lrc’s internal build configuration format, so being able to interface with it in the rockspec gives quite powerful control over many aspects of the compilation.

The current list of available LRocket Spec options can be found below:

Option	Description
entrypoint	required: Main lua file
output	Output filename
otype	Output file format
modpath searchpath[]	List of module search paths in the format <lang>:<searchpath> (where <lang> is one of: lua,shared,static,c,teal,<custom>)
modules	Explicitly include the specified modules
exclude	Exclude given modules from search
optional	Include these optional modules. This argument enables optional module parsing for specified statements (using [x]pcall)
liblua 'shared' 'static' default: 'static'	Variant of the Lua library to link against
debug 'all' 'project' 'module'	Add debugging information to the output file
optimize 'space' 'speed'	Enable optimizations
fuzzy default: true	Examine complex require statements when resolving modules
runtime_path	Runtime LUA_PATH used for lua modules (supports ?? and !)
runtime_cpath	Runtime LUA_CPATH used for lua modules (supports ?? and !)
keep default: false	Do not remove intermediate C code after compilation
link_sibling_deps default: true	Resolve dynamic dependencies of statically linked lua modules by scanning equally named dynamic modules
copy_native_libs default: true	Copies required shared C libraries to the output directory
windows_gui default: false	Link with /SUBSYSTEM:WINDOWS (or -mwindows for MinGW)
modname (for otype shared)	Module name of the shared library, used for luaopen_<modname>
export (for otype shared)	Export additional luaopen_<modname> (supports globs)

Extra Options for Debugging lrc

Option	Description
log_level string integer	lrocket compiler: level of verbosity
warnmode 'error' 'warn'	Decides whether warnings should warn or throw an error
perf default: false	Show instrumentalized timings
perf_log	Log profiling stacktraces to this file (flamegraph format)
prefer_c_module_type 'shared' 'static' default: 'static'	Choose the preferred variant of native Lua modules to link against

Internal Options

Since luarocks-build-lrocket v1.2, options specified in the build-table of your rockspec are passed directly to lrc.

This gives you direct control over the LRocket Spec build configuration, meaning that you could even adjust internal (undocumented) options of the build.

If this tickles your nose, check out lrocket/api.lua for a full list of internal options!

Tree Config Integration

Added in luarocks-build-lrocket v1.2.0

Since v1.2 LRocket Spec options can be stored inside the tree config files of LuaRocks, under the lrocket namespace. This is useful for persisting common settings, such as sysroot directories or logging preferences.

lrc will use settings stored inside the config files as fallback values, in the case they are not manually specified during the build (e.g. inside the rockspec or via command line flags).

Note When you are on Linux or macOS, your default user tree is stored under ~/.luarocks. On Windows, your home tree is located inside %APPDATA%\LuaRocks

Example:

-- ~/.luarocks/config-5.5.lua
lrocket = {
	log_level = 'detail'  -- use 'detail' log level in all builds by default
}

In addition to the regular config[-ver].lua files of LuaRocks, the LRocket Luarocks integration adds the option to store settings for all lua versions: in a generic ~/.luarocks/config.lua.

When you are using cross-compilation, you gain the additional option to store config values in the platform specific rocks trees (see Cross Compilation for more information).

The Luarocks logo was created by Hisham Muhammad.