Tauri Sidecar Target Triples

Tauri v2 — Sidecar Target Triples

Tauri picks the sidecar binary by exact filename match against the current build target's Rust triple. Get one character wrong and tauri build fails with binary not found. This skill is the reference for the triples you'll ship, how Tauri resolves them, and how to script the build so the right files land in src-tauri/binaries/ before tauri build runs.

See [[tauri-sidecar]] for the broader sidecar story and [[tauri-bundling]] for what happens to these binaries inside the installer.

The naming rule

For every entry in tauri.conf.json > bundle.externalBin, a file must exist at src-tauri/<path>-<TARGET_TRIPLE> (plus .exe on Windows). Examples:

externalBin: ["binaries/myproxy"]
→ src-tauri/binaries/myproxy-aarch64-apple-darwin
→ src-tauri/binaries/myproxy-x86_64-apple-darwin
→ src-tauri/binaries/myproxy-x86_64-pc-windows-msvc.exe
→ src-tauri/binaries/myproxy-x86_64-unknown-linux-gnu

The .exe extension goes after the triple, not before. myproxy.exe-... is wrong; myproxy-...-msvc.exe is right. There is no fallback search and no glob — Tauri concatenates basename + "-" + triple [+ ".exe"] and opens that exact path.

How tauri build resolves the triple

Get the host triple yourself:

rustc --print host-tuple   # Rust >= 1.84
rustc -vV | grep '^host:'  # older toolchains

Reference: triples by OS

macOS

For a single universal binary, build both then merge:

lipo -create \
  binaries/myproxy-aarch64-apple-darwin \
  binaries/myproxy-x86_64-apple-darwin \
  -output binaries/myproxy-universal-apple-darwin

Tauri also accepts the two non-universal files and will do the lipo itself when you pass --target universal-apple-darwin.

Windows

Always .exe after the triple. Tauri's MSI/NSIS bundler will not auto-add it.

Linux

glibc baseline matters. The binary inherits the glibc version of the build host. A sidecar compiled on Ubuntu 24.04 (glibc 2.39) will refuse to load on Ubuntu 20.04 (glibc 2.31). For broad reach, build inside the oldest distro you intend to support — manylinux containers or an Ubuntu 20.04 LTS runner are the standard choices. If you can't pin a baseline, ship the musl triple instead.

Mobile

Sidecars on iOS/Android are unusual — the OS sandbox limits process spawn heavily and the App Store rejects most cases. Confirm the use case before investing.

The build-script pattern

Producing the right files reliably is the whole game. The repo's scripts/build-sidecar.ts is a working example for a Bun-compiled proxy: it derives the host triple from rustc -vV, maps it to a bun build --compile --target=<bun-target> argument, mtime-skips when nothing under src/ has changed, sweeps interrupted bun build temp files, and writes atomically to shell/src-tauri/binaries/maximal-<triple>.

The shape is portable to any compiler. See templates/build-sidecar.ts in this skill's directory for a generalised version that:

1. Resolves the host triple (or a --target override).
2. Picks the right compiler invocation (cargo build --release --target for Rust, bun build --compile --target for Bun, go build for Go, pkg --target for Node).
3. Compiles to a .tmp path under src-tauri/binaries/.
4. chmod +x then atomic rename() over the final filename.
5. Refuses to ship if the produced file is < 1 KB (catches silent compiler failures that exit 0 but leave a stub behind).

CI matrix

A release pipeline typically runs one job per (OS runner × arch) pair, each producing its slice of src-tauri/binaries/. The simplest layout:

The macOS universal bundle is then a separate job that downloads the two arch artefacts and runs lipo. Pin the Ubuntu version explicitly — the default ubuntu-latest floats forward and silently raises your glibc baseline.

Verification

Before merging a sidecar change:

ls src-tauri/binaries/
file src-tauri/binaries/myproxy-aarch64-apple-darwin   # → Mach-O 64-bit arm64
file src-tauri/binaries/myproxy-x86_64-pc-windows-msvc.exe  # → PE32+ x86_64

Then tauri build once per target you ship. The bundler prints Embedding external binaries lines — confirm yours appears.

Gotchas

• Stale temp files. Compilers (especially bun build --compile) write to a hex-suffixed temp file and rename. An interrupted build leaves a 60+ MB orphan in CWD. The template sweeps .<hex>-<n>.bun-build and *.tmp on every run.
• tauri dev doesn't always need every triple — only the host one. Release matrices need all of them. CI failures here are usually a forgotten --force on the sidecar build before tauri build.
• universal-apple-darwin is not a real Rust triple. Don't pass it to cargo build or rustc. It only exists inside Tauri's CLI as the signal to lipo two real outputs together.
• Windows ARM64. aarch64-pc-windows-msvc exists, but ARM64 WebView2 has historically shipped late. Test before promising the SKU.