248 lines
13 KiB
Markdown
248 lines
13 KiB
Markdown
# 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).
|