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 a silent engine 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.

Next milestone

Phase 4 implements the modular graph editor and submits validated graph edits through the C API. Physical playback/endurance, project persistence and sequencing remain unverified/unimplemented as applicable.