Cagire/BUILDING.md

Building Cagire

Quick Start

git clone https://git.raphaelforment.fr/BuboBubo/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

System Dependencies

macOS

brew install cmake

cmake is required by rusty_link (Ableton Link C++ bindings). Xcode Command Line Tools provide the C++ compiler. CoreAudio and CoreMIDI are built-in. The desktop build needs no additional dependencies on macOS (Cocoa/Metal are provided by the system).

Linux (Debian/Ubuntu)

sudo apt install cmake g++ pkg-config libasound2-dev libjack-jackd2-dev

For the desktop build (egui/eframe), also install:

sudo apt install libgl-dev libxkbcommon-dev libx11-dev libxcursor-dev libxrandr-dev libxi-dev libwayland-dev

Linux (Arch)

sudo pacman -S cmake gcc pkgconf alsa-lib jack2

For the desktop build:

sudo pacman -S libxkbcommon libx11 libxcursor libxrandr libxi wayland mesa

Linux (Fedora)

sudo dnf install cmake gcc-c++ pkgconf-pkg-config alsa-lib-devel jack-audio-connection-kit-devel

For the desktop build:

sudo dnf install libxkbcommon-devel libX11-devel libXcursor-devel libXrandr-devel libXi-devel wayland-devel mesa-libGL-devel

Windows

Install Visual Studio Build Tools (MSVC) and CMake. Everything else is provided by the Windows SDK.

Build

Terminal (default):

cargo build --release

Desktop (egui window):

cargo build --release --features desktop --bin cagire-desktop

Plugins (CLAP/VST3):

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):

cargo run --release -- [OPTIONS]

Desktop (egui window):

cargo run --release --features desktop --bin cagire-desktop

Flag	Description
-s, --samples <path>	Sample directory (repeatable)
-o, --output <device>	Output audio device
-i, --input <device>	Input audio device
-c, --channels <n>	Output channel count
-b, --buffer <size>	Audio buffer size

Cross-Compilation

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 (Docker)	cagire, cagire-desktop
aarch64-unknown-linux-gnu (RPi 64-bit)	cross build (Docker)	cagire, cagire-desktop
x86_64-pc-windows-msvc	cargo xwin build (native)	cagire, cagire-desktop

macOS targets can only be built on macOS. Linux targets are cross-compiled via Docker (cross). Windows targets are cross-compiled natively via cargo-xwin (downloads Windows SDK + MSVC CRT headers, no Docker needed).

Prerequisites

1. Docker + cross (Linux targets only): cargo install cross --git https://github.com/cross-rs/cross
2. cargo-xwin (Windows target): cargo install cargo-xwin and rustup target add x86_64-pc-windows-msvc
3. On macOS, add the Intel target: rustup target add x86_64-apple-darwin

Building Individual Targets

# Linux x86_64 (Docker)
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 (Docker)
cross build --release --target aarch64-unknown-linux-gnu
cross build --release --features desktop --bin cagire-desktop --target aarch64-unknown-linux-gnu

# Windows x86_64 (native, no Docker)
cargo xwin build --release --target x86_64-pc-windows-msvc
cargo xwin build --release --features desktop --bin cagire-desktop --target x86_64-pc-windows-msvc

Building All Targets

# Interactive (prompts for platform/target selection):
uv run scripts/build.py

# Non-interactive:
uv run scripts/build.py --platforms macos-arm64,linux-x86_64 --targets cli,desktop
uv run scripts/build.py --all

Builds selected targets, producing binaries in 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. build.py handles AppImage creation automatically for Linux targets.

Notes

• Custom Dockerfiles in scripts/cross/ install the native libraries for Linux cross-compilation (ALSA, JACK, X11, cmake, libclang, etc.). Cross.toml maps each Linux target to its Dockerfile.
• The first Linux cross-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) run under QEMU emulation and are significantly slower.
• Windows cross-compilation via cargo-xwin runs natively on the host (no Docker) and uses real Windows SDK headers, ensuring correct ABI and struct layouts.