98 lines
2.8 KiB
Markdown
98 lines
2.8 KiB
Markdown
# 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
|