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.

Bundled ONNX Runtime

Linux release builds include ONNX Runtime for Silero VAD by default. The build helper downloads the official Linux CPU archive into .cache/onnxruntime/ for the current target architecture and stages libonnxruntime.so into the app bundle.

To pin a specific ONNX Runtime release, export:

export CHANORA_ONNXRUNTIME_VERSION=1.26.0

To use a local shared library instead of downloading the archive, 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

The Debian helper verifies that libonnxruntime.so was actually bundled before packaging.