Chapter 1

Install

Set up your machine to build truce plugins. Three things: Rust, a system C/C++ compiler, and the cargo truce CLI.

First-timer path. This chapter covers the minimum needed to build CLAP and VST3 — the two formats that work on every OS, that every modern host loads, and that scaffolded plugins enable by default. Other formats (AU, AAX, signed installers, hot-reload sccache) layer on top; their setup lives in extra setup at the bottom and in the reference.

#Rust

Install Rust 1.92+ via rustup.rs. If you already have it, rustup update.

#Platform compiler

Pick the one for your OS — this is the only platform-specific step.

macOS

xcode-select --install

Installs the Xcode command-line tools (clang, system headers). All system frameworks (Cocoa, AudioToolbox, …) come with macOS — no package manager needed.

Windows

Install Visual Studio 2019+ with the "Desktop development with C++" workload. The Windows SDK and MSVC toolchain come with it. WSL users: install Rust on Windows itself, not in WSL — plugin hosts can't load ELF binaries from WSL paths.

To ship a universal x64 + ARM64 installer, see Dual-arch on Windows.

Linux

# Ubuntu / Debian
sudo apt install build-essential pkg-config

# Fedora
sudo dnf install @development-tools pkgconf-pkg-config

That's enough for a headless CLAP/VST3 plugin. For a plugin with a GUI, also install the X11 + GL + Vulkan + font dev libraries (every truce GUI backend goes through baseview):

# Ubuntu / Debian
sudo apt install \
  libx11-dev libx11-xcb-dev libxcb1-dev libxcb-icccm4-dev libxcursor-dev \
  libxkbcommon-dev libxkbcommon-x11-dev libxrandr-dev \
  libgl1-mesa-dev libvulkan-dev mesa-vulkan-drivers \
  libfontconfig1-dev libfreetype-dev

(Standalone-host audio adds ALSA + JACK; see extra setup.)

Vizia GUI backend additionally needs the EGL and Wayland-EGL dev libraries — Vizia renders with Skia, whose build links -lEGL and -lwayland-egl. The runtime .so.N files are usually already present; these dev packages add the bare .so symlinks the linker needs (a missing one shows up as rust-lld: error: unable to find library -lwayland-egl):

# Ubuntu / Debian
sudo apt install libegl1-mesa-dev libwayland-dev

The other GUI backends (egui, iced, slint, the built-in renderer) don't link Skia and don't need these.

#Install the CLI

cargo install cargo-truce

Pulls cargo-truce from crates.io. Cargo picks it up as the cargo truce subcommand. To upgrade later, run with --force.

#Sanity check

cargo truce doctor

Reports what's present and what's missing — Rust version, compiler, optional SDKs, validator binaries. Green rows are ready; yellow are optional; red block something. Run doctor any time a build behaves oddly — it's usually faster than reading the error.

You're ready for chapter 2 → first-plugin.

#Extra setup

You don't need any of this to build CLAP+VST3 plugins. Pull these in only when you actually need them.

#Standalone host audio (Linux)

The cargo truce run standalone host needs ALSA + JACK headers (or the PipeWire JACK shim) on Linux. macOS and Windows have these in the OS:

# Ubuntu / Debian
sudo apt install libasound2-dev libjack-jackd2-dev pipewire-jack libspa-0.2-jack

# Fedora
sudo dnf install alsa-lib-devel jack-audio-connection-kit-devel

Modern PipeWire distros: install pipewire-jack and don't also run jackd2 — they fight for the same socket. The shim replaces libjack.so.0.

#AU v2

Ships with macOS — no extra setup. Just opt in: cargo truce install --au2.

#AU v3 (macOS only)

Needs full Xcode (not just CLI tools) — xcodebuild builds the .appex. Switch the active developer directory once:

sudo xcode-select -s /Applications/Xcode.app

AU v3 also requires a real Developer ID for Apple to load the appex — see cargo-config.

#AAX

Needs the Avid AAX SDK (point AAX_SDK_PATH at it) plus PACE/iLok for retail Pro Tools releases. macOS and Windows only. Details in formats/aax.

#Signed installers (cargo truce package)

  • macOS: signing identities + Apple notary credentials. See cargo-config.
  • Windows: Inno Setup 6 for ISCC.exe, plus an Authenticode source (Azure Trusted Signing, cert thumbprint, or .pfx). See cargo-config.
  • Linux: no signed-installer support yet.

#Dual-arch on Windows

cargo truce package ships a universal x64 + ARM64 installer by default. You need two things:

  1. The Rust target: rustup target add aarch64-pc-windows-msvc
  2. The MSVC cross-tools: VS Installer → Modify → Individual components → check "MSVC v143 - VS 2022 C++ ARM64/ARM64EC build tools" (or v145 on VS 2026).

cargo truce doctor reports whether both are in place. Pass --host-only to cargo truce package if you want to skip ARM64 for a quick iteration build.

#sccache

If sccache is on PATH, cargo truce auto-uses it as RUSTC_WRAPPER — significant rebuild speed-up. doctor reports when it's active. Set TRUCE_DISABLE_SCCACHE=1 to skip.

#Pin a specific CLI version

cargo install cargo-truce --version X.Y.Z              # exact version from crates.io
cargo install --git https://github.com/truce-audio/truce \
              --tag vX.Y.Z cargo-truce                 # exact git tag

#What's next

  • Chapter 2 → first-plugin — cargo truce new, a tour of the generated files, install into your DAW, hear it work.
  • Format details — per-format prerequisites, host coverage, and gotchas in formats/.
  • Environment variables — every signing, SDK, notary, and hot-reload variable in cargo-config.