biggy
05fd6440bd
Add root AGENT.md with project conventions, build verification steps, source layout, style rules, and real-time/concurrency requirements. Add per-module AGENT.md files for each existing and proposed source subdirectory. Add AUDIT_REPORT.md as a historical Phase 1 snapshot documenting memory management, error handling, concurrency model, naming conventions, and anti-pattern catalog.
84 lines
4.4 KiB
Markdown
84 lines
4.4 KiB
Markdown
# SerumAlt agent guidance
|
|
|
|
## Project
|
|
|
|
SerumAlt is a JUCE 7 wavetable synthesiser using C++17. Project metadata is in
|
|
`CMakeLists.txt`. Production formats are VST3 and Standalone on Linux, VST3/AU/Standalone
|
|
on macOS, and VST3 on Windows. First-party classes use `namespace serum`; executable
|
|
entry points and JUCE's `createPluginFilter` are outside that namespace.
|
|
|
|
## Build and verification
|
|
|
|
Read README.md's Building section before changing scripts, dependencies, or CMake.
|
|
It is the maintained source for prerequisites, options and artifact paths.
|
|
|
|
- Linux production: `./build_linux.sh`.
|
|
- macOS production, on a Mac: `./build_macos.sh`.
|
|
- Windows x64 VST3, cross-compiled on Linux: `./build_windows.sh`.
|
|
- Native QA build and execution: `./build_harness.sh --run`.
|
|
- Shell syntax: `for script in build_*.sh; do bash -n "$script"; done`.
|
|
|
|
Production scripts explicitly enable `SERUMALT_BUILD_PLUGIN` and disable
|
|
`SERUMALT_BUILD_TESTS`. The harness script does the reverse in a separate directory.
|
|
Building `SerumAltTest` alone does not execute it; `--run` invokes CTest.
|
|
When changing CMake, verify production has no `SerumAltTest` target and the
|
|
harness-only build has no `SerumAlt`, VST3, AU, or Standalone target.
|
|
|
|
Keep existing build trees and local changes intact. Use a new `BUILD_DIR` for
|
|
clean-build verification. Use a fresh Windows `OUTPUT_DIR` for distribution checks,
|
|
since staging does not remove extra files. Never edit generated CMakeCache.txt files.
|
|
The checked-in MinGW toolchain is the single source of cross-compiler configuration.
|
|
|
|
## Current source layout
|
|
|
|
`CMakeLists.txt` owns the explicit `SERUMALT_SOURCES` list and shared target setup.
|
|
`cmake/Plugin.cmake` owns production formats and MinGW link flags;
|
|
`cmake/Harness.cmake` owns the console harness and CTest registration.
|
|
The harness compiles the same processor/editor sources independently of the plugin.
|
|
|
|
Most C++ files still live directly under `Source/`. Existing implementation
|
|
subdirectories are `EffectUnits/`, `GUI/`, `Presets/`, `Resources/`, and `Tests/`.
|
|
`FXProcessor`, `PluginEditor`, `Resources`, and `RAVEButton` remain at the source root.
|
|
`RAVEButton.{h,cpp}` defines `RaveController`.
|
|
|
|
The lowercase `Source/engine`, `modulation`, `params`, `plugin`, and `synth`
|
|
directories currently hold guidance, not relocated implementations. Consult their
|
|
AGENT.md files when editing the related root-level sources. Consult the matching
|
|
AGENT.md when editing an existing implementation subdirectory.
|
|
`AUDIT_REPORT.md` is a historical audit and proposed refactor, not a pending
|
|
instruction to move files. Update the explicit source list and includes only when
|
|
an actual source move is part of the requested task.
|
|
|
|
## Style and ownership
|
|
|
|
Follow the surrounding file. Existing C++ generally uses four-space indentation,
|
|
`#pragma once`, PascalCase types, camelCase members without prefixes, `k`-prefixed
|
|
constants, scoped enums, and `noexcept` on cheap getters and DSP paths. Use `Count`
|
|
only for enums that need a size or iteration sentinel. Headers include JuceHeader;
|
|
implementation files normally include their own header first.
|
|
|
|
Prefer value members or `std::unique_ptr` for owned objects and attachments.
|
|
`addAndMakeVisible` does not transfer ownership or delete children. Raw allocations
|
|
returned by `createEditor` and `createPluginFilter` transfer ownership to JUCE callers.
|
|
Guard parameter lookups and invalid state data. Use `jassert` sparingly for programmer
|
|
errors and return `bool` from bounded inserts to report failure.
|
|
|
|
## Real-time and concurrency requirements
|
|
|
|
For new or changed audio paths, allocate buffers during preparation and avoid heap
|
|
allocation, blocking locks and I/O in `processBlock` or per-sample DSP. Account for
|
|
variable host block sizes without allocating in the callback. Keep GUI updates on
|
|
the JUCE message thread. Exchange GUI/audio state through a safe snapshot or bounded
|
|
handoff; a timer or a writer-only mutex does not make concurrent access safe.
|
|
|
|
These are requirements, not claims that the current code already satisfies them.
|
|
The historical audit records lazy wavetable allocation, per-block buffer resizing,
|
|
and unsynchronised modulation/LFO edits. When changing those paths, inspect the
|
|
current implementation and verify the fix separately. The QA smoke test does not
|
|
prove real-time safety or absence of data races.
|
|
|
|
## Scope of guidance
|
|
|
|
Module guidance refines this file for its related sources. Preserve the root
|
|
real-time and ownership requirements if an example conflicts with them.
|