# LuaRocks Integration
The LRocket Project is integrated with the [LuaRocks](https://luarocks.org) package manager and its build system.
To compile something with `lrc` via LuaRocks, simply set `build.type = 'lrocket'` in your [rockspec](https://github.com/luarocks/luarocks/blob/main/docs/creating_a_rock.md):
```lua
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`](https://luarocks.org/modules/sewbacca/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](https://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](#rockspec-build-options) of available build options).
\* The method is based on the [lr-hooks](https://codeberg.org/leso-kn/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`
| List of module search paths in the format `:` (where `` is one of: `lua,shared,static,c,teal,`) |
| `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`
default: `'static'` | Variant of the Lua library to link against |
| `debug`
- `'all'`
- `'project'`
- `'module'`
| Add debugging information to the output file |
| `optimize`
| 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_` |
| `export`
(for otype `shared`) | Export additional `luaopen_` (supports globs) |
Extra Options for Debugging lrc
| Option | Description |
| ------ | ---------- |
| `log_level`
| lrocket compiler: level of verbosity |
| `warnmode`
| 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`
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``](https://codeberg.org/lrocket/lrc/src/branch/main/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](#rockspec-build-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:**
```lua
-- ~/.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](cross-compilation), you gain the additional option to store config values in the platform specific rocks trees (see [Cross Compilation](cross-compilation.md#persisting-the-sysroot-setting) for more information).
_The Luarocks logo was created by [Hisham Muhammad](https://hisham.hm/projects)._