WIP: multi-platform builds pipeline

2026-02-26 18:54:01 +01:00
parent 47099a6eef
commit f618f47811
16 changed files with 1097 additions and 247 deletions
--- a/BUILDING.md
+++ b/BUILDING.md
@@ -1,5 +1,15 @@
 # Building Cagire

+## Quick Start
+
+```bash
+git clone --recursive https://github.com/Bubobubobubobubo/cagire
+cd cagire
+cargo build --release
+```
+
+The `doux` audio engine is fetched automatically from git. No local path setup needed.
+
 ## Prerequisites

 **Rust** (stable toolchain): https://rustup.rs
@@ -68,6 +78,14 @@ Desktop (egui window):
 cargo build --release --features desktop --bin cagire-desktop
 ```

+Plugins (CLAP/VST3):
+
+```bash
+cargo xtask bundle cagire-plugins --release
+```
+
+The xtask alias is defined in `.cargo/config.toml` (committed). Plugin bundles are output to `target/bundled/`.
+
 ## Run

 Terminal (default):
@@ -89,3 +107,81 @@ cargo run --release --features desktop --bin cagire-desktop
 | `-i, --input <device>` | Input audio device |
 | `-c, --channels <n>` | Output channel count |
 | `-b, --buffer <size>` | Audio buffer size |
+
+## Cross-Compilation
+
+[cross](https://github.com/cross-rs/cross) uses Docker to build for other platforms without installing their toolchains locally. It works on any OS that runs Docker.
+
+### Targets
+
+| Target | Method | Binaries |
+|--------|--------|----------|
+| aarch64-apple-darwin | Native (macOS ARM only) | `cagire`, `cagire-desktop` |
+| x86_64-apple-darwin | Native (macOS only) | `cagire`, `cagire-desktop` |
+| x86_64-unknown-linux-gnu | `cross build` | `cagire`, `cagire-desktop` |
+| aarch64-unknown-linux-gnu (RPi 64-bit) | `cross build` | `cagire`, `cagire-desktop` |
+| x86_64-pc-windows-gnu | `cross build` | `cagire`, `cagire-desktop` |
+
+macOS targets can only be built on macOS — Apple does not support cross-compilation to macOS from other platforms. Linux and Windows targets can be cross-compiled from any OS. The aarch64-unknown-linux-gnu target covers Raspberry Pi (64-bit OS).
+
+### Windows ABI
+
+CI produces `x86_64-pc-windows-msvc` binaries (native Windows build, better compatibility). Local cross-compilation from non-Windows hosts produces `x86_64-pc-windows-gnu` binaries (MinGW via Docker). Both work; MSVC is preferred for releases.
+
+### Prerequisites
+
+1. **Docker**: https://docs.docker.com/get-docker/
+2. **cross**: `cargo install cross --git https://github.com/cross-rs/cross`
+3. On macOS, add the Intel target: `rustup target add x86_64-apple-darwin`
+
+Docker must be running before invoking `cross` or `scripts/build-all.sh`.
+
+### Building Individual Targets
+
+```bash
+# Linux x86_64
+cross build --release --target x86_64-unknown-linux-gnu
+cross build --release --features desktop --bin cagire-desktop --target x86_64-unknown-linux-gnu
+
+# Linux aarch64
+cross build --release --target aarch64-unknown-linux-gnu
+cross build --release --features desktop --bin cagire-desktop --target aarch64-unknown-linux-gnu
+
+# Windows x86_64
+cross build --release --target x86_64-pc-windows-gnu
+cross build --release --features desktop --bin cagire-desktop --target x86_64-pc-windows-gnu
+```
+
+### Building All Targets (macOS only)
+
+```bash
+# Interactive (prompts for platform/target selection):
+scripts/build-all.sh
+
+# Non-interactive:
+scripts/build-all.sh --platforms macos-arm64,linux-x86_64 --targets cli,desktop --yes
+scripts/build-all.sh --all --yes
+```
+
+Builds selected targets, producing binaries in `target/releases/`.
+
+Platform aliases: `macos-arm64`, `macos-x86_64`, `linux-x86_64`, `linux-aarch64`, `windows-x86_64`.
+Target aliases: `cli`, `desktop`, `plugins`.
+
+### Linux AppImage Packaging
+
+Linux releases ship as AppImages — self-contained executables that bundle all shared library dependencies (ALSA, JACK, X11, OpenGL). No runtime dependencies required.
+
+After building a Linux target, produce an AppImage with:
+
+```bash
+scripts/make-appimage.sh target/x86_64-unknown-linux-gnu/release/cagire x86_64 target/releases
+```
+
+`scripts/build-all.sh` does this automatically for every Linux target selected. The CI pipeline produces AppImages for the x86_64 Linux build. Cross-arch AppImage building (e.g. aarch64 on x86_64) is not supported — run on a matching host or in CI.
+
+### Notes
+
+- Custom Dockerfiles in `cross/` install the native libraries Cagire depends on (ALSA, JACK, X11, cmake, libclang, etc.). `Cross.toml` maps each target to its Dockerfile.
+- The first build per target downloads Docker base images and installs packages. Subsequent builds use cached layers.
+- Cross-architecture Docker builds (e.g. aarch64 on x86_64 or vice versa) run under QEMU emulation and are significantly slower.