xtc/docs/BUILD.md

# Build Baseline

The existing layout is retained: public C headers in `include/xtc`, C
implementation modules under `src`, optional C++ GUI under `src/gui`, and tests
under `tests`. `src/main.c` is a minimal headless startup/shutdown check; it
does not initialize audio devices or open a GUI.

---

## Commands

```sh
make clean all test
./build/xtc-check
make debug
make gui
```

`all` builds the static C library and startup check. `test` runs the existing
core/offline tests, concurrent plan-handoff stress, JACK fault injection (when
JACK headers are available), and the startup check. `debug` builds and tests
separately in `build/debug`. `gui` builds the FLTK shell with backend controls
and status. The shell starts with a silent graph and never connects physical
ports. Generated files remain under `build` and header changes trigger rebuilds.
Compiler, flags, `BUILD_DIR`, `PKG_CONFIG`, `FLTK_CONFIG`, and installation
`PREFIX` can be overridden through Make variables. C uses C99; GUI uses C++17.

---

## Inspected Linux Toolchain (2026-10-26)

| Component | Available version | Role |
| --- | --- | --- |
| GCC / G++ | 16.2.1 | C core and optional C++ GUI |
| GNU Make | 4.4.1 | Build and test driver |
| pkg-config | 3.0.10 | Development package discovery |
| FLTK | 1.4.5 | Optional GUI; discovered through `fltk-config` |
| JACK | 3.1609.0 (pkg-config) | Optional JACK backend (PipeWire compatibility library) |
| ALSA | 1.2.16.1 (pkg-config) | Future MIDI candidate; not linked yet |
| Clang | 23.1.3 | Alternative compiler / diagnostics |

Valgrind is also available. The core tests use a small in-tree C test harness
and require no external test framework. FLTK has no `fltk.pc` on this host; the
Makefile tries pkg-config first, then `fltk-config`.

---

## Dependencies and Licensing

The offline core needs the C runtime and math library. Optional JACK support is
selected with pkg-config; missing JACK does not prevent core/tests from
building. Realtime publication uses GCC/Clang lock-free atomic builtins in C99.
Tests also use POSIX threads. Backend consumers must link JACK explicitly;
backend objects are pulled from the static library only when used. The
repository is MIT licensed. The optional GUI uses maintained FLTK 1.4 (LGPL with
FLTK's static-linking exception); its platform link flags come from the
installed package. Distribution still requires review of all linked dependencies
and notices. The installed PipeWire JACK library is MIT; traditional JACK client
libraries use LGPL licensing. See decision 0004 for the dependency choice and
caveats. ALSA remains a future MIDI candidate. No packages or system settings
are changed by these build commands.

---

## Backend Verification

```sh
make all test gui debug
make test-jack
# Extended live run after building the integration binary:
./build/test_jack 30
# Verify optional build without JACK metadata, in a separate directory:
make BUILD_DIR=build/nojack PKG_CONFIG=false all test
# Address/undefined sanitizers (non-realtime tests only):
make BUILD_DIR=build/sanitize CC=clang CFLAGS='-O1 -g -std=c99 -Wall -Wextra -Wpedantic -Wconversion -Wshadow -Iinclude -fsanitize=address,undefined -fno-omit-frame-pointer' LDFLAGS='-fsanitize=address,undefined' all test
# Thread sanitizer for publication/reclamation:
make BUILD_DIR=build/tsan CC=cc CFLAGS='-O1 -g -std=c99 -Wall -Wextra -Wpedantic -Wconversion -Wshadow -Iinclude -fsanitize=thread' LDFLAGS='-fsanitize=thread' build/tsan/test_realtime
./build/tsan/test_realtime
```

Normal, sanitizer and no-JACK tests pass. ThreadSanitizer reports no race in
2,000 concurrent submissions. The 30-second live loopback test passed at 48 kHz
with zero xruns and ten restart cycles; see tests/integration/README.md. Live
server termination/format changes were not performed on the shared server;
fault-injection tests cover those notification paths. No packages installed or
system/device configuration changed. Sanitizers are not enabled in the live
callback qualification run.

---

## GUI Shell Verification

```sh
make clean all test gui debug test-gui test-gui-jack
```

`test-gui` needs Xvfb and `xvfb-run`, uses a fake C backend and requires no JACK
server. `test-gui-jack` needs a running server; it creates no physical routes.
Both passed, including repeated active-client close and reconnect. The GUI also
builds without JACK metadata and reports unsupported backend support at startup.
A live keyboard/visual smoke run passed under Xvfb. Clang ASan/UBSan GUI tests
passed with a suppression limited to the installed fontconfig library's
exit-time font allocations; see tests/integration/README.md for the distinction
and command. No compiler warnings remain with GCC or Clang. Core/backend tests
pass with unsuppressed ASan/UBSan. No packages or system configuration changed.

---

## Graph Editor Verification

```sh
make clean all test gui debug test-gui test-gui-jack
make BUILD_DIR=build/nojack PKG_CONFIG=false all test gui test-gui
```

The normal suite adds test_graph_edits for stable IDs, dense snapshots,
transactional rejection/deletion/disconnect and known rendered samples before
and after edits. Core/backend/realtime tests pass under unsuppressed Clang
ASan/UBSan; ThreadSanitizer passes the concurrent handoff test with revision-to-
gain checks. GUI ASan/UBSan tests pass with the existing fontconfig-only leak
suppression. Live GUI tests build a connected graph, adopt accepted edits during
playback, reject cycles, reconnect and close active clients. Mouse/visual smoke
checks cover node creation, wiring, cycle rejection, dragging and deletion. No
physical routes, new dependencies or system changes are introduced.

---

## Project Verification

```sh
make clean all test gui debug test-gui test-gui-jack
make BUILD_DIR=build/nojack PKG_CONFIG=false all test gui test-gui
```

The suite adds test_project: track/clip limits, stable IDs, trims, integer
transport conversion, exact file roundtrip with graph rendering, exhaustive
fixture truncations, byte mutations, failed saves and temporary cleanup. GUI
tests cover region gestures, zoom, save/load and backend rollback. Live JACK
tests verify playhead advance, pause and resume without creating routes. The
updated core and GUI tests pass Clang ASan/UBSan (the GUI uses the existing
fontconfig-only LSan suppression). An Xvfb/xdotool visual check created a track
and region, moved it one bar and zoomed the canvas. No dependencies were added.

Audio assets and recording are supported. Silent arrangement regions, fixed
tempo/4/4, no undo, no persisted GUI layout, and unverified physical-device
playback/endurance remain explicit limits.

---

## Audio Verification

```sh
make all test gui debug test-gui test-gui-jack test-jack-audio
make BUILD_DIR=build/nojack PKG_CONFIG=false all test gui test-gui
make BUILD_DIR=build/tsan CC=cc CFLAGS='-O1 -g -std=c99 -Wall -Wextra -Wpedantic -Wconversion -Wshadow -Iinclude -fsanitize=thread' LDFLAGS='-fsanitize=thread' build/tsan/test_audio build/tsan/test_realtime
./build/tsan/test_audio
./build/tsan/test_realtime
```

No new dependency is required for WAV import, recording or playback. New audio
sources remain C99; only GUI controls use C++/FLTK. test_audio covers decoder
samples, truncations/nonfinite/unsupported input, resampling, trim/overlap,
missing assets and concurrent recording. test_backend records known callback
input, saves/reopens and checks exact graph output. Project tests cover v1
migration and 1024 maximum-length asset paths in a valid v2 file.

The live test-jack-audio target connects only its software clients and checks
record -> WAV -> saved/reopened project -> graph playback. GUI/JACK tests also
record, finalize, save and reopen a take without hardware routing. Clang
ASan/UBSan passes the core and GUI tests (GUI retains the existing
fontconfig-only LSan suppression). ThreadSanitizer passes the concurrent
recorder and existing realtime handoff tests. Hardware capture/playback, disk
endurance and real server loss during recording remain unverified. See
AUDIO_FILES.md.

---

## MIDI Verification

```sh
make all test gui debug test-gui test-gui-jack test-jack-audio test-jack-midi
make BUILD_DIR=build/nojack PKG_CONFIG=false all test gui test-gui
```

`test_midi` adds exact sample scheduling, trim/seek/panic, block independence,
voice capacities, stable notes and v3 malformed-file/roundtrip/v2 migration
coverage. Backend fault injection checks event offsets, dropped/malformed input,
disconnection, xruns, missing output buffers and stop/restart cleanup. GUI tests
draw/move/resize notes, save/reopen and render them. The live MIDI target
connects only software clients and checks on/off, panic, disconnect, and
saved-note playback/seek. It needs an existing JACK-compatible server. No
hardware routes or system changes are made. MIDI recording/SMF and physical
devices are deferred.

A fresh `build/verify` build passed all targets above with no compiler warnings.
The no-JACK core/GUI suite and Clang ASan/UBSan core/GUI suite also passed; GUI
leak checking uses only the existing fontconfig suppression documented in the
integration README. Physical MIDI and audio devices remain unverified.

---

## Mixer Verification

```sh
make all test gui debug test-gui test-gui-jack test-jack-audio test-jack-midi
make BUILD_DIR=build/nojack PKG_CONFIG=false all test gui test-gui
```

`test_mixer` covers stereo gain/pan, mute/solo, sample automation, block
independence, WAV and graph routing, v4 persistence failures and bounded
history. GUI tests add automation mouse edits, mixer keys, history
rollback/branching and save/reopen. The existing live MIDI test now uses two
software capture ports and checks hard-right saved-note playback and output
meter snapshots; mono audio record/play acceptance remains covered. A native
Xvfb mouse smoke check confirms sliders and automation drawing. See MIXER.md for
capacities and deferred features.

The fresh verification build, no-JACK core/GUI suite and Clang ASan/UBSan
core/GUI suite passed without compiler warnings. GUI leak checking retains only
the existing fontconfig suppression. ThreadSanitizer also passed the recorder
concurrency and realtime publication tests. Physical devices and long-running
stereo performance remain unverified.

---

## Release Preparation

```sh
make all test gui debug test-gui test-gui-jack test-jack test-jack-audio test-jack-midi
make test-install test-recovery test-performance
make test-release
```

Core test now includes native ABI/lifecycle/retirement and the native-gain
example. Optional release tests use Python 3.12+ standard library, Git for
indexed source exports, GNU/LLVM deterministic ar and temporary directories. No
live prefix is installed. test-install checks core/GUI files, a prefix
containing spaces, headless CLI, pkg-config C/C++ consumers, exact/idempotent
uninstall and preservation of unrelated files. test-release compares two clean
exported optimized builds and repacked archives byte-for-byte. test-recovery
kills private child writers and forces a child-local write limit, checking
complete finalized destinations and explicit orphan temporaries. Performance
timings are reported, not used as a universal realtime guarantee. See
RELEASING.md, RECOVERY.md and PERFORMANCE.md.

Verification passed a fresh warning-enabled core/debug/GUI build, all software
JACK targets, staged install/uninstall, recovery and performance tests. No-JACK
core/GUI/install checks and Clang ASan/UBSan core/GUI checks also passed (the
GUI retains only its existing fontconfig leak suppression). TSan recorder and
realtime-handoff checks passed. Two independent optimized source exports and
their repacked source archives were byte-identical on this toolchain.

---

## Reliability Audit

Run `make test-reliability` for the core suites, allocation-failure sweep,
callback allocation/free guard and native reclamation checks. Run
`make test-sanitize` for Clang ASan/UBSan/leak checks and `make analyze` for
Clang static analysis of all core sources. These need installed development
tools; the allocation guard uses a GNU-compatible linker. See
[RELIABILITY.md](RELIABILITY.md) for ownership, audit findings, full
verification commands and remaining limits.

---

## Workflow Acceptance

`make test-workflow` requires FLTK/JACK development files, Xvfb and an existing
JACK-compatible server. It does not start/configure the server or connect
physical devices. See [WORKFLOW.md](WORKFLOW.md) for the full GUI composition
acceptance sequence and transport semantics.

---

## Audio Quality

`make test-quality` runs exact timing, source-boundary, gain-ramp, event-order
and numeric/layout tests (also included in `make test`). `make quality-preview`
builds the C example and writes raw/smoothed listening WAVs into BUILD_DIR
without playing them or configuring devices. See
[AUDIO_QUALITY.md](AUDIO_QUALITY.md).

Parameter-processor and plugin checks:
`make test-processor test-plugins test-gui-plugins`. The latter two need the
system LADSPA development header; real-plugin acceptance is separate
(`make test-plugins-real`, paths listed in PLUGIN_HOSTING.md). With no
`ladspa.h`, the ordinary core/GUI still builds and plugin operations return
UNSUPPORTED; existing plugin metadata can still be loaded/saved. To exercise
that configuration explicitly, use a fresh BUILD_DIR with
`CPPFLAGS=-DXTC_DISABLE_LADSPA JACK_AVAILABLE=`. No dependency is downloaded.
Link static consumers with `-lm -ldl` plus the backend dependencies when used.
See LICENSES.md for header/plugin licensing and decision 0009 for rationale.
Recording stress/recovery is available with `make test-recording`.

Developer qualification: `make check-development` runs the core build,
regressions, scale/virtual endurance, benchmark-gate checks, Clang analysis and
ASan/UBSan. Run `make benchmark benchmark-project` separately without contention
or sanitizers for timing reports. Optional `make test-stress-plugins` requires
installed LADSPA headers; `make test-stress` supports minimal builds too.

---

## Installation Layouts

`make test-install test-install-layout` verifies default and custom layouts in
throwaway staging directories, C/C++ installed consumers, examples and exact
removal. Override `PREFIX`, `exec_prefix`, `bindir`, `libdir`, `includedir`,
`datarootdir`, `datadir`, `docdir`, `pkgconfigdir`, `licensedir`, `examplesdir`
or `desktopdir` as needed. `DESTDIR` adds staging separately; pass the same
layout to uninstall. See RELEASING.md for commands and RELEASE_NOTES.md for
upgrades.

Modern plugin adapters build in C99 using the pinned header-only CLAP and VST3 C
APIs under third_party; there is no network build or SDK runtime. VST2
compatibility uses original ABI declarations. `make test-modern-plugins` runs
original shared-library fixtures without a server;
`make test-gui-modern-plugins` adds GUI/browser/undo/reopen tests under Xvfb.
The fixtures also run in `make test` and therefore in sanitizer/release builds.
Notices are installed with LICENSE.

The GUI uses a header-only FLTK theme and existing drawing primitives; no new
GUI dependency or generated asset is required. `make test-gui-instruments` also
exercises sidebar track creation, rollback, undo/reopen and minimum/large
layouts. See WORKSPACE.md for the default size and manual visual verification.