325 lines
15 KiB
Markdown
325 lines
15 KiB
Markdown
# Build Baseline
|
|
|
|
The existing layout is retained: 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. Optional JACK support is
|
|
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.
|
|
|
|
---
|
|
|
|
## Backend 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.
|
|
|
|
---
|
|
|
|
## GUI Shell 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.
|
|
|
|
---
|
|
|
|
## Graph Editor 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.
|
|
|
|
---
|
|
|
|
## Project 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.
|
|
|
|
Audio assets and recording are supported. Silent arrangement regions, fixed
|
|
tempo/4/4, no undo, no persisted GUI layout, and unverified physical-device
|
|
playback/endurance remain explicit limits.
|
|
|
|
---
|
|
|
|
## Audio 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.
|
|
|
|
---
|
|
|
|
## MIDI 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.
|
|
|
|
---
|
|
|
|
## Mixer 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 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.
|
|
|
|
---
|
|
|
|
## 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.
|
|
|
|
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.
|
|
|
|
---
|
|
|
|
## 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.
|
|
|
|
---
|
|
|
|
## 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.
|
|
|
|
---
|
|
|
|
## 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).
|
|
|
|
Parameter-processor and plugin checks:
|
|
`make test-processor test-plugins test-gui-plugins`. The latter two need the
|
|
system LADSPA development header; real-plugin acceptance is separate
|
|
(`make test-plugins-real`, paths listed in PLUGIN_HOSTING.md). With no
|
|
`ladspa.h`, the ordinary core/GUI still builds and plugin operations return
|
|
UNSUPPORTED; existing plugin metadata can still be loaded/saved. To exercise
|
|
that configuration explicitly, use a fresh BUILD_DIR with
|
|
`CPPFLAGS=-DXTC_DISABLE_LADSPA JACK_AVAILABLE=`. No dependency is downloaded.
|
|
Link static consumers with `-lm -ldl` plus the backend dependencies when used.
|
|
See LICENSES.md for header/plugin licensing and decision 0009 for rationale.
|
|
Recording stress/recovery is available with `make test-recording`.
|
|
|
|
Developer qualification: `make check-development` runs the core build,
|
|
regressions, scale/virtual endurance, benchmark-gate checks, Clang analysis and
|
|
ASan/UBSan. Run `make benchmark benchmark-project` separately without contention
|
|
or sanitizers for timing reports. Optional `make test-stress-plugins` requires
|
|
installed LADSPA headers; `make test-stress` supports minimal builds too.
|
|
|
|
---
|
|
|
|
## Installation Layouts
|
|
|
|
`make test-install test-install-layout` verifies default and custom layouts in
|
|
throwaway staging directories, C/C++ installed consumers, examples and exact
|
|
removal. Override `PREFIX`, `exec_prefix`, `bindir`, `libdir`, `includedir`,
|
|
`datarootdir`, `datadir`, `docdir`, `pkgconfigdir`, `licensedir`, `examplesdir`
|
|
or `desktopdir` as needed. `DESTDIR` adds staging separately; pass the same
|
|
layout to uninstall. See RELEASING.md for commands and RELEASE_NOTES.md for
|
|
upgrades.
|
|
|
|
Modern plugin adapters build in C99 using the pinned header-only CLAP and VST3 C
|
|
APIs under third_party; there is no network build or SDK runtime. VST2
|
|
compatibility uses original ABI declarations. `make test-modern-plugins` runs
|
|
original shared-library fixtures without a server;
|
|
`make test-gui-modern-plugins` adds GUI/browser/undo/reopen tests under Xvfb.
|
|
The fixtures also run in `make test` and therefore in sanitizer/release builds.
|
|
Notices are installed with LICENSE.
|
|
|
|
The GUI uses a header-only FLTK theme and existing drawing primitives; no new
|
|
GUI dependency or generated asset is required. `make test-gui-instruments` also
|
|
exercises sidebar track creation, rollback, undo/reopen and minimum/large
|
|
layouts. See WORKSPACE.md for the default size and manual visual verification.
|