# Building RIVET on Fedora

## Dependencies

Phase 1 requires C++20, CMake 3.22+, Qt 6.7+ Widgets, pkg-config and JACK headers /
library. Ninja is used in the commands below. Qt 6.7 is the minimum because file
logging uses `QStandardPaths::StateLocation`.

```sh
sudo dnf install gcc-c++ cmake ninja-build pkgconf-pkg-config qt6-qtbase-devel pipewire-jack-audio-connection-kit-devel
```

Runtime audio needs the user PipeWire session and its JACK compatibility library
(`pipewire-jack-audio-connection-kit`). A native JACK server is also supported by
the API but has not been integration-tested here. RIVET never starts a server.

Dependency inspection on this machine:

| Component | Detected |
| --- | --- |
| OS | Fedora Linux 44, KDE Plasma, x86_64 |
| GCC C++ | 16.2.1 |
| CMake | 4.3.0 |
| Ninja | 1.13.2 |
| Qt Widgets/Core | 6.11.2 |
| pkg-config | 2.5.1 |
| PipeWire runtime + JACK compatibility | 1.6.8 |
| JACK pkg-config API version, system development package | 3.1608.0 |
| PipeWire/JACK development package | 1.6.8 (now installed) |
| ALSA development package | 1.2.16.1 (now installed) |
| ALSA runtime | 1.2.16.1 |
| libsndfile runtime | 1.2.2 |
| SQLite runtime | 3.51.2 |

System development packages initially missing: PipeWire/JACK, ALSA, libsndfile,
SQLite and native PipeWire headers. **Only JACK headers are required for this
phase.** JACK MIDI is the implemented backend; direct ALSA MIDI is deferred.
The owner subsequently installed `pipewire-jack-audio-connection-kit-devel` and
`alsa-lib-devel`; both were verified with RPM and pkg-config. All current Phase 1
build dependencies are now available from system packages.
Later phases may need `alsa-lib-devel`, `libsndfile-devel`, `sqlite-devel` or
`pipewire-devel`. These are not linked or advertised as current features.

## Normal build

```sh
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug -DRIVET_REQUIRE_JACK=ON
cmake --build build -j 4
ctest --test-dir build --output-on-failure
./build/rivet
```

Use `-DCMAKE_BUILD_TYPE=Release` in a separate build directory for a release
build. `rivet` is the executable name. Installation is optional:

```sh
cmake --install build --prefix "$PWD/local-install"
```

`VERSION` is validated at configure time and generates the application version
header. Rebuilding after a version edit triggers CMake regeneration. Check the
result with `QT_QPA_PLATFORM=offscreen ./build/rivet --version`.

In this workspace, the original `build/` and `build-release/` directories retain
temporary dependency paths in their CMake caches. Fresh system-package builds
use `build-system/` (Debug) and `build-system-release/` (Release): substitute those
names for `build` in the commands above. No custom pkg-config environment is
needed for these fresh builds.

Without JACK development files, default CMake configuration permits a limited
UI/core-only build. Its UI explicitly says audio is unavailable. Pass
`-DRIVET_REQUIRE_JACK=ON` for a real audio build; missing headers then fail
configuration rather than silently weakening audio support.

## Historical temporary development setup

The initial attempted system installation could not authenticate through sudo. Instead,
Fedora's development RPM was downloaded and extracted under `/tmp/rivet-devel`,
then linked to the already installed PipeWire JACK runtime. No system package
was installed by that workaround, and no substitute implementation was used.
The owner has since installed the required development packages; this workaround
is no longer necessary.

Exact successful extraction/build commands on this machine:

```sh
mkdir -p /tmp/rivet-devel/rpms /tmp/rivet-devel/root
# Download from Fedora repositories; no root required.
dnf --setopt=cachedir=/tmp/rivet-devel/cache --setopt=logdir=/tmp/rivet-devel/log download --destdir=/tmp/rivet-devel/rpms pipewire-jack-audio-connection-kit-devel
rpm2cpio /tmp/rivet-devel/rpms/pipewire-jack-audio-connection-kit-devel-1.6.8-1.fc44.x86_64.rpm | cpio -idmu -D /tmp/rivet-devel/root
ln -s /usr/lib64/pipewire-0.3/jack/libjack.so.0 /tmp/rivet-devel/root/usr/lib64/pipewire-0.3/jack/libjack.so.0
PKG_CONFIG_SYSROOT_DIR=/tmp/rivet-devel/root PKG_CONFIG_PATH=/tmp/rivet-devel/root/usr/lib64/pkgconfig cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug -DRIVET_REQUIRE_JACK=ON
cmake --build build -j 4
```

The versioned RPM path describes this session, not an evergreen package version.
The local headers disappear when `/tmp` is cleared. Install the normal system
package for durable development and configure a fresh build directory (for
example `build-system`) to avoid cached temporary pkg-config paths. Existing
binaries link to the installed `libjack.so.0`, also available in the system
loader cache; the temporary files are build dependencies.

## Tests

```sh
ctest --test-dir build --output-on-failure
./build/rivet_jack_check
python3 tests/isolated_audio.py
```

CTest runs deterministic DSP/MIDI tests and an offscreen Qt startup/settings /
shutdown check. JACK integration is deliberately separate: it needs access to a
live server and returns 77 if no server is available. It creates capture and
MIDI-source clients and never connects test sound to physical playback ports.
The Python helper needs `pipewire` and Python 3. It creates its own temporary
socket, tests real audio/MIDI and disconnect recovery, then terminates only its
own daemon to verify shutdown handling. It does not control the desktop daemon.

Sandboxed runs may require permission to access the desktop audio socket or
create the private test-server socket. Such access failures are not successful
audio tests.

For a UI capture:

```sh
QT_QPA_PLATFORM=offscreen ./build/rivet --screenshot /tmp/rivet.png
QT_SCALE_FACTOR=2 QT_QPA_PLATFORM=offscreen ./build/rivet --smoke-test
```

## Sample rate and buffer size

PipeWire's `PIPEWIRE_RATE=1/48000 ./build/rivet` requests a rate; the server may
retain its current rate if the graph is busy or the requested rate is not
allowed. Native JACK uses server configuration. The UI always displays the
actual negotiated rate. Supported DSP rates are 8–384 kHz; invalid rates produce
silence. See [PipeWire's JACK configuration reference](https://docs.pipewire.org/page_man_pipewire-jack_conf_5.html).

The buffer selector issues a real `jack_set_buffer_size` request while RIVET is
inactive. It can affect other clients, can be rejected, and can be superseded
by server policy. Select **Follow server** if a request fails. RIVET adapts to
callback rate/quantum changes without reallocating DSP buffers.

## Settings and logs

Qt stores preferences in the user's standard configuration directory
(typically `~/.config/Retrace/RIVET.conf`). Logs use Qt's state location
(typically `~/.local/state/Retrace/RIVET/rivet.log`), shown in the status bar.
A log over 1 MiB is rotated at the next launch. Settings/log I/O never runs in
RIVET's audio callback. Failure to persist settings logs a warning; failure to
open a log falls back to stderr. Tests redirect both locations into build or
temporary directories.