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

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

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

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

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

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

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

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

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

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 for ownership, audit findings, full verification commands and remaining limits.