chanora/docs/release/linux-build.md

Chanora Linux build notes

This document covers the current Linux desktop build and packaging flow for apps/chanora_flutter.

Prerequisites

• Linux host with desktop Flutter support enabled
• Rust stable
• Flutter stable on PATH
• CMake 3.13+
• pkg-config
• GTK3 development headers
• Opus development headers that expose the opus pkg-config module used by tsclientlib/audiopus for Linux audio encode/decode
• PipeWire development headers that expose the libpipewire-0.3 and libspa-0.2 pkg-config modules used by the primary Linux voice backend
• PulseAudio development headers for the fallback Linux voice backend
• clang and gcc
• sibling checkout of oboe-rs at ../oboe-rs

Install opus-devel on Fedora-style hosts or libopus-dev on Debian/Ubuntu. The workspace does not vendor or patch Opus for Linux; the normal Linux build links the system libopus through pkg-config.

For Linux audio specifically, the product uses PipeWire directly as the primary backend and PulseAudio directly as the fallback. If you want a fast preflight, these are the package checks that matter:

pkg-config --modversion gtk+-3.0
pkg-config --modversion opus
pkg-config --modversion libpipewire-0.3
pkg-config --modversion libspa-0.2
pkg-config --modversion libpulse
pkg-config --modversion libpulse-simple

Use libpipewire-0.3, not pipewire-0.3. The latter probe will fail even on a correctly provisioned host because it is not the module name exported by the PipeWire development package.

Optional: bundle ONNX Runtime

If you want the Linux bundle to include ONNX Runtime for Silero VAD, export:

export CHANORA_ONNXRUNTIME_SHARED_LIB=/absolute/path/to/libonnxruntime.so

When set, the Flutter Linux bundle will include:

build/linux/x64/<mode>/bundle/lib/libonnxruntime.so

and the Linux runner will set ORT_DYLIB_PATH to that bundled file at app startup when the variable is not already present.

Build helper

From the repository root:

./tools/build-linux.sh

The Flutter Linux CMake bundle now owns staging libchanora_bridge.so into bundle/lib/. A plain flutter build linux will build the host-profile Rust bridge automatically; tools/build-linux.sh exports CHANORA_BRIDGE_SHARED_LIB so release bundles use the already-built targeted artifact instead of duplicating the copy logic in shell.

Useful variants:

./tools/build-linux.sh --no-rust
./tools/build-linux.sh --regenerate-bindings
./tools/build-linux.sh --version v0.2.0-beta.1

Debian package helper

To build a .deb package:

./tools/build-linux-deb.sh

If CHANORA_ONNXRUNTIME_SHARED_LIB is set, the Debian helper now verifies that libonnxruntime.so was actually bundled before packaging.