Docs file normalization.
This commit is contained in:
parent
dd32143bf8
commit
619c2d0808
46 changed files with 3587 additions and 2579 deletions
233
docs/BUILD.md
233
docs/BUILD.md
|
|
@ -1,9 +1,11 @@
|
|||
# Build baseline
|
||||
# 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.
|
||||
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
|
||||
|
||||
|
|
@ -15,14 +17,17 @@ 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.
|
||||
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)
|
||||
---
|
||||
|
||||
## Inspected Linux Toolchain (2026-10-26)
|
||||
|
||||
| Component | Available version | Role |
|
||||
| --- | --- | --- |
|
||||
|
|
@ -35,24 +40,29 @@ Compiler, flags, `BUILD_DIR`, `PKG_CONFIG`, `FLTK_CONFIG`, and installation
|
|||
| 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`.
|
||||
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
|
||||
---
|
||||
|
||||
## 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
|
||||
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
|
||||
---
|
||||
|
||||
## Backend Verification
|
||||
|
||||
```sh
|
||||
make all test gui debug
|
||||
|
|
@ -72,11 +82,13 @@ 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
|
||||
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
|
||||
---
|
||||
|
||||
## GUI Shell Verification
|
||||
|
||||
```sh
|
||||
make clean all test gui debug test-gui test-gui-jack
|
||||
|
|
@ -92,7 +104,9 @@ 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
|
||||
---
|
||||
|
||||
## Graph Editor Verification
|
||||
|
||||
```sh
|
||||
make clean all test gui debug test-gui test-gui-jack
|
||||
|
|
@ -106,10 +120,12 @@ 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.
|
||||
checks cover node creation, wiring, cycle rejection, dragging and deletion. No
|
||||
physical routes, new dependencies or system changes are introduced.
|
||||
|
||||
## Project verification
|
||||
---
|
||||
|
||||
## Project Verification
|
||||
|
||||
```sh
|
||||
make clean all test gui debug test-gui test-gui-jack
|
||||
|
|
@ -118,10 +134,10 @@ 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
|
||||
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.
|
||||
|
||||
|
|
@ -129,8 +145,9 @@ 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
|
||||
## Audio Verification
|
||||
|
||||
```sh
|
||||
make all test gui debug test-gui test-gui-jack test-jack-audio
|
||||
|
|
@ -150,12 +167,15 @@ 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.
|
||||
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
|
||||
---
|
||||
|
||||
## MIDI Verification
|
||||
|
||||
```sh
|
||||
make all test gui debug test-gui test-gui-jack test-jack-audio test-jack-midi
|
||||
|
|
@ -166,17 +186,20 @@ make BUILD_DIR=build/nojack PKG_CONFIG=false all test gui test-gui
|
|||
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.
|
||||
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
|
||||
---
|
||||
|
||||
## Mixer Verification
|
||||
|
||||
```sh
|
||||
make all test gui debug test-gui test-gui-jack test-jack-audio test-jack-midi
|
||||
|
|
@ -184,20 +207,23 @@ 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.
|
||||
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.
|
||||
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
|
||||
---
|
||||
|
||||
## Release Preparation
|
||||
|
||||
```sh
|
||||
make all test gui debug test-gui test-gui-jack test-jack test-jack-audio test-jack-midi
|
||||
|
|
@ -205,54 +231,63 @@ 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.
|
||||
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.
|
||||
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
|
||||
---
|
||||
|
||||
## 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.
|
||||
[RELIABILITY.md](RELIABILITY.md) for ownership, audit findings, full
|
||||
verification commands and remaining limits.
|
||||
|
||||
## Workflow acceptance
|
||||
---
|
||||
|
||||
## 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
|
||||
---
|
||||
|
||||
## 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).
|
||||
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
|
||||
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
|
||||
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.
|
||||
|
|
@ -264,23 +299,27 @@ 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
|
||||
---
|
||||
|
||||
## 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.
|
||||
`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.
|
||||
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.
|
||||
exercises sidebar track creation, rollback, undo/reopen and minimum/large
|
||||
layouts. See WORKSPACE.md for the default size and manual visual verification.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue