xtc/docs/BUILD.md

# Build baseline

Phase 0 retains the existing layout: 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. Phase 2 adds optional
JACK support, 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.

## Phase 2 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.

## Phase 3 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.

## Phase 4 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.

## Phase 5 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.

Phase 6 will add audio assets and recording. Silent arrangement regions, fixed
tempo/4/4, no undo, no persisted GUI layout, and unverified physical-device
playback/endurance remain explicit limits.


## Phase 6 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.

## Phase 7 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.

## Phase 8 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 Phase 8 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.

## Phase 9 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.

Phase 9 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.

## Phase 10 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.

## Phase 11 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.

## Phase 12 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).

Phase 14/15 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`.