Cross-Compilation

Phase 111 made cross-compilation explicit: karkain build --target <triple> compiles for the requested target through Karkain-owned compiler-driver selection, and a missing cross-linker fails deterministically instead of silently producing a host binary.

Usage

$ karkain build hello.kark --target <triple> [-o <output>]

The --target switch accepts any Target Triples form; long forms such as x86_64-unknown-linux-gnu are normalized at parse time.

Supported matrix

On this documentation’s reference host (Windows x86_64), the honest matrix is:

Target

Status

Notes

x86_64-windows

PASS

Native build; verifiable here. Emits a real PE32+ executable whose x86-64 machine field is validated on the host.

x86_64-linux

N/A

No cross-linker on PATH in the reference environment. The mechanism is fully implemented — see “Toolchain discovery” below — but artifacts are unverifiable on this host.

aarch64-linux

N/A

Same story as x86_64-linux: mechanism implemented, needs a triple-prefixed GNU cross-gcc on PATH to actually build.

aarch64-windows

N/A

Needs aarch64-w64-mingw32-gcc or clang on PATH (Phase 139).

riscv64-linux

N/A

Parse + error paths only (Phase 139): no backend builds it yet, so the deterministic ToolchainError is the whole surface.

x86_64-macos

N/A

Needs clang with --target=x86_64-apple-macosx on PATH (Phase 139; never GNU/MSVC by design).

aarch64-macos

N/A

Needs clang with --target=aarch64-apple-macosx on PATH (Phase 139).

wasm32-wasi

Production Candidate

The dedicated Karkain-owned WASM backend emits the module directly (no cross-linker needed). Phase 123 added the WASI boundary: exit codes, stderr diagnostics and getArgs().

A compiler that does not have a cross-linker installed gets a deterministic failure (below), not a wrong-architecture binary.

Toolchain discovery

The C-driver selection in pkg/codegen/cross_target.go works in two modes:

  • Same-machine targets (SameMachine(host)) compile with the historical host probe — $CC override, then gcc, clang, and MSVC cl.exe on Windows — with byte-identical flags (-std=c2x -O0 -lgmp, -mconsole on Windows).

  • Cross targets probe conventional triple-prefixed GNU cross-gcc first, then clang with an explicit ``–target``:

    • x86_64-linux → x86_64-linux-gnu-gcc, x86_64-pc-linux-gnu-gcc, x86_64-unknown-linux-gnu-gcc, then clang --target=x86_64-unknown-linux-gnu

    • Windows cross targets → x86_64-w64-mingw32-gcc then clang --target=x86_64-w64-mingw32

Missing cross-linker

When no cross toolchain is on PATH, the build fails deterministically with a ToolchainError (exit 6) that lists exactly what was searched and what to install:

$ karkain build hello.kark --target x86_64-linux -o hello_linux
no cross-linker available for target 'x86_64-linux' on host
'x86_64-windows' (searched: 'x86_64-linux-gnu-gcc', ...); install a C
cross-toolchain for x86_64-linux (see `karkain target`) and ensure it
is on PATH — the host toolchain can neither link nor execute
x86_64-linux output
$ echo $?    # 6

There is never a silent fallback to the host toolchain and never a wrong-architecture binary.

Cross-run

Running a foreign binary on the host is impossible without an emulator or remote target, so karkain run --target <foreign> is refused with a build-only hint:

$ karkain run hello.kark --target x86_64-linux
cannot run a x86_64-linux binary on the host (x86_64-windows):
cross-run requires an emulator or a remote target; use `karkain build
--target x86_64-linux -o <path>` to build only

Generated C self-description

Every generated C file self-describes its target via a header comment and preprocessor defines:

/* karkain-target: x86_64-linux */
#define KARKAIN_TARGET_ARCH_X86_64 1
#define KARKAIN_TARGET_OS_LINUX 1

Boundaries

  • In-language target.os / target.arch builtins are planned post-111 (they would require kcc-parity changes) and are not available in Karkain source yet.

  • pkg/backends for the native engine produce host binaries; the native-link pipeline is a host-object/linker path unaffected by cross-builds.

Gates

Phase-111 behavior is locked by pkg/cli/phase111_cross_compile_test.go and pkg/target/triple_test.go (parse/normalize/host-vs-foreign matrix).

See also

Target — the karkain target command. Target Triples — the accepted triple forms. Host Targets — host detection and the pkg/target model. Build — karkain build options.