bux-lang/docs/superpowers/specs/2026-06-10-cross-compilation-design.md

Bux Cross-Compilation Support — Design Document

Date: 2026-06-10 Status: Approved Scope: MVP cross-compilation via --target CLI flag

---

1. Overview

Bux compiles to C, which means cross-compilation is nearly free — we only need to pass the correct target triple to the C compiler (cc). This feature adds --target <triple> support to the Bux CLI.

Goals

• bux build --target aarch64-linux-gnu produces an ARM64 binary
• bux build --target x86_64-windows-gnu produces a Windows binary
• No changes to the compiler pipeline — only the final cc invocation changes

Non-Goals

• Automatic cross-compiler toolchain detection
• Custom linker scripts or startup code
• Multiple target builds in one invocation

---

2. How Cross-Compilation Works

Bux compilation pipeline:

.bux source → lexer → parser → sema → HIR → C code → cc → binary

The entire pipeline is target-independent until the final cc step. For cross-compilation:

1. Bux generates the same C code
2. Instead of cc -O2 -pthread -o output ...
3. We run cc -O2 -pthread -target aarch64-linux-gnu -o output ...

Or, if a cross-compiler prefix is needed:

aarch64-linux-gnu-gcc -O2 -pthread -o output ...

---

3. CLI Interface

# Native build (default)
bux build

# Cross-compile to ARM64 Linux
bux build --target aarch64-linux-gnu

# Cross-compile to Windows
bux build --target x86_64-pc-windows-gnu

# Also works with buxc project
buxc project . --target aarch64-linux-gnu

---

4. Implementation

Changes to src/cli.bux

1. Parse --target flag: In Cli_Run, scan args for --target before processing the command. Extract the target triple.

2. Store target: Add a global variable g_targetTriple: String (default "").

3. Pass to cc: In both Cli_Compile (line ~251) and Cli_BuildProject (line ~1143), append -target <triple> to the cc command if g_targetTriple is set.

Target Triple Format

We pass the triple directly to cc without validation. Examples:

• aarch64-linux-gnu → cc -target aarch64-linux-gnu ...
• x86_64-pc-windows-gnu → cc -target x86_64-pc-windows-gnu ...
• wasm32-wasi → cc -target wasm32-wasi ...

Error Handling

If cc fails with an invalid target, the user sees the standard cc error message. Bux does not need custom error handling for this.

---

5. Files to Modify

File	Change
src/cli.bux	Parse --target flag, store in global, append to cc command

---

6. Testing

1. Native build: bux build — should work as before (no -target flag)
2. Invalid target: bux build --target invalid-target — cc should fail with appropriate error
3. Valid target (if cross-compiler available): bux build --target aarch64-linux-gnu — should produce ARM64 binary