hanez/xtc
2
1
Fork 1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Phase 2.

Browse source
This commit is contained in:
Johannes Findeisen 2026-10-26 23:32:04 +01:00
commit 577d80f018
16 changed files with 1100 additions and 41 deletions
Download patch file Download diff file Expand all files Collapse all files

49
docs/BUILD.md
View file

@ -15,7 +15,8 @@ make gui
```
`all` builds the static C library and startup check. `test` runs the existing
core and offline graph tests plus the startup check. `debug` builds and tests separately in
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
@ -29,7 +30,7 @@ Compiler, flags, `BUILD_DIR`, `PKG_CONFIG`, `FLTK_CONFIG`, and installation
| 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) | Candidate backend; not linked yet |
| 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 |
@ -39,18 +40,44 @@ the Makefile tries pkg-config first, then `fltk-config`.
## Dependencies and licensing
No new dependencies are introduced. The core needs the C runtime and math
library. The repository is MIT licensed. The optional GUI uses maintained
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. JACK and ALSA remain candidates only; backend
selection and license review belong to Phase 2. No packages or system settings
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 1 implements compiled offline plans, preallocated buffers, oscillator,
gain, meter/output nodes and routing tests; see AUDIO_ENGINE.md. Phase 2 adds
a hardware backend and safe cross-thread plan publication/retirement. Public
project persistence declarations remain unimplemented. Hardware playback and
interactive GUI behavior are not verified by the offline tests.
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.