Cross Compilation

Added in lrc v1.2.0

Since v1.2 lrc can target other platforms (cross-compilation) in addition to building for the host machine (default).

Cross-compilation can be enabled by adding the --target=<...> argument or setting the CROSS=<...> environment variable.

Some otypes will also enable cross-compilation automatically (e.g. lrocket-build-wasm).

Requirements

The general requirements for targeting any foreign platform are:

  • A C compiler that supports the target platform *

  • [usually] A sysroot containing headers and libraries for the target platform

* clang supports many platforms out of the box and is recommended for most cross-compilation screnarios. Target specific versions of gcc are supported just as well.

Usage

Note When you are calling lrc from a parent build system which already supports cross-compilation (e.g. abuild on Alpine Linux), cross-compilation should work automatically, as lrc looks for the standard environment variables CROSS and SYSROOT by default.

# Compile on Linux => for Windows
> lrc --target=x86_64-pc-windows-gnu --sysroot=~/win64-sysroot -o program.exe entrypoint.lua

Using luarocks

Since v1.2 the LRocket LuaRocks Integration adds the --target flag to the luarocks package manager itself.

Therefor you can do:

# Compile on Linux => for Windows
> luarocks make --target=x86_64-pc-windows-gnu

If a project should always target a specific platform, you can also use the rockspec file to persist the target specification:

-- project-scm-0.rockspec
...

build = {
	type = 'lrocket',
	entrypoint = 'main.lua'
	output = 'program'  -- .exe is automatically added in case Windows is targeted
	target = 'x86_64-pc-windows-gnu'  -- always compile for Windows
}

Host Lua Version

If you are building with LuaRocks and the platform you target uses a different Lua version than your LuaRocks installation, you can specify the host and target lua versions explicitly:

# Use LRocket installed in a Lua 5.5 rocks tree and => compile for Windows with LuaJIT
> luarocks make --target=x86_64-pc-windows-gnu --host-lua-version=5.5 --lua-version=jit

Platform-Specific Rocks Trees

If you are building with LuaRocks, the LRocket LuaRocks Integration will automatically create platform-specific rocks trees when you use cross-compilation.

By default, these will be located in your home tree (e.g. ~/.luarocks on Linux) in a subdirectory based on the target triple).

Example: ~/.luarocks/x86_64-pc-windows-gnu/

Persisting the sysroot setting

If are building with LuaRocks and you wish to use the same sysroot every time you target a specific platform, you can persist the sysroot directory in a respective luarocks config file, as lrc integrates with the config system of LuaRocks.

You can either create a config file in ~/.luarocks/[target]/config-5.5.lua (if you wish to apply the setting for a specific Lua version) or in ~/.luarocks/[target]/config.lua (if you want to apply the setting for all Lua versions):

-- config[-5.x|jit].lua
lrocket = {
	sysroot = '/home/me/windows-sysroot'
}

Supported LuaRocks Build Drivers

Make sure you have the LRocket LuaRocks Integration installed in order to use luarocks packages in cross-builds.

lrc supports the use of external Lua packages (modules) via the LuaRocks package manager. The Luarocks Integration ensures that external packages are automatically compiled for the platform you wish to target with lrc.

As of lrc v1.2.0, the following luarocks build drivers are integrated with the cross-compilation feature:

  • builtin

  • makefile

  • cmake

  • rust

Other build drivers may work as well, but are not officially tested to work with lrc.