# 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:

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

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

When set, the Flutter Linux bundle will include:

```text
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:

```bash
./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:

```bash
./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:

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