# 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 `otype`s will also enable cross-compilation automatically (e.g. [`lrocket-build-wasm`](web-assembly)).

## Requirements

The general requirements for targeting any foreign platform are:

* A C compiler that supports the target platform \*
* [usually] A [sysroot](https://en.wiktionary.org/wiki/sysroot) containing headers and libraries for the target platform

\* [`clang`](https://clang.llvm.org/) 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`](https://wiki.alpinelinux.org/wiki/Abuild_and_Helpers) on Alpine Linux), cross-compilation should work automatically, as `lrc` looks for the standard environment variables `CROSS` and `SYSROOT` by default.

```bash
# 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](luarocks-integration) adds the `--target` flag to the luarocks package manager itself.

Therefor you can do:

```bash
# 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:

```lua
-- 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:

```bash
# 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](luarocks-integration) will automatically create platform-specific [rocks trees](https://github.com/luarocks/luarocks/blob/main/docs/rocks_repositories.md) 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):

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

## Supported LuaRocks Build Drivers

> Make sure you have the [LRocket LuaRocks Integration](luarocks-integration) installed in order to use luarocks packages in cross-builds.

`lrc` supports the use of external Lua packages (modules) via the [LuaRocks](https://luarocks.org/) package manager. The [Luarocks Integration](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`](https://luarocks.org/modules/khvzak/luarocks-build-rust-mlua)

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