# 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 existing placeholder shell; it does not produce
audio. 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.

## Next milestone

Phase 3 connects the FLTK shell to the backend C API for engine controls,
status/error reporting and clean shutdown. Physical playback and endurance,
project persistence and sequencing remain unverified/unimplemented as applicable.