From 18aa232b1cfbe040cfdc63504e39a7ba5c57aa3b Mon Sep 17 00:00:00 2001
From: dimgigov <gigov@gigov.org>
Date: Wed, 10 Jun 2026 20:19:17 +0300
Subject: [PATCH] docs: add cross-compilation design document

---
 .../2026-06-10-cross-compilation-design.md    | 97 +++++++++++++++++++
 1 file changed, 97 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-06-10-cross-compilation-design.md

diff --git a/docs/superpowers/specs/2026-06-10-cross-compilation-design.md b/docs/superpowers/specs/2026-06-10-cross-compilation-design.md
new file mode 100644
index 0000000..0848b2d
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-10-cross-compilation-design.md
@@ -0,0 +1,97 @@
+# 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
+
+```bash
+# 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