Cagire/BUILDING.md

# Building Cagire

## Quick Start

```bash
git clone 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

## System Dependencies

### macOS

```bash
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)

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

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

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

### Linux (Arch)

```bash
sudo pacman -S cmake gcc pkgconf alsa-lib jack2
```

For the desktop build:

```bash
sudo pacman -S libxkbcommon libx11 libxcursor libxrandr libxi wayland mesa
```

### Linux (Fedora)

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

For the desktop build:

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

```bash
cargo build --release
```

Desktop (egui window):

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

```bash
cargo run --release -- [OPTIONS]
```

Desktop (egui window):

```bash
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

[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 `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 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.