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.