|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## About This Project |
| 6 | + |
| 7 | +This project is derived from the [Pamplejuce](https://github.com/sudara/pamplejuce) template — a JUCE audio plugin template using CMake, C++23, and modern CI/CD. It builds cross-platform (macOS, Windows, Linux) with support for multiple plugin formats (VST3, AU, AUv3, CLAP, Standalone). |
| 8 | + |
| 9 | +The template provides the build system, CI/CD, and project structure. The plugin-specific logic lives in `source/`. |
| 10 | + |
| 11 | +## Build Commands |
| 12 | + |
| 13 | +```bash |
| 14 | +# Configure (run once, or after CMakeLists.txt changes) |
| 15 | +cmake -B Builds -DCMAKE_BUILD_TYPE=Release |
| 16 | + |
| 17 | +# Build |
| 18 | +cmake --build Builds --config Release |
| 19 | + |
| 20 | +# Run tests (from project root) |
| 21 | +ctest --test-dir Builds --verbose --output-on-failure |
| 22 | + |
| 23 | +# Or run tests directly |
| 24 | +./Builds/Tests |
| 25 | + |
| 26 | +# Run a single test by name |
| 27 | +./Builds/Tests "[test name]" |
| 28 | + |
| 29 | +# Run benchmarks |
| 30 | +./Builds/Benchmarks |
| 31 | +``` |
| 32 | + |
| 33 | +For faster builds, add Ninja: `cmake -B Builds -G Ninja -DCMAKE_BUILD_TYPE=Release` |
| 34 | + |
| 35 | +On macOS for universal binary: `-DCMAKE_OSX_ARCHITECTURES="arm64;x86_64"` |
| 36 | + |
| 37 | +## Project Structure |
| 38 | + |
| 39 | +- `source/` - Plugin source code (PluginProcessor, PluginEditor) |
| 40 | +- `tests/` - Catch2 test files |
| 41 | +- `benchmarks/` - Catch2 benchmark files |
| 42 | +- `cmake/` - CMake modules (Tests.cmake, Benchmarks.cmake, Assets.cmake, etc.) |
| 43 | +- `modules/` - Git submodules: clap-juce-extensions, melatonin_inspector |
| 44 | +- `JUCE/` - JUCE framework (git submodule) |
| 45 | +- `assets/` - Binary resources (auto-included via juce_add_binary_data) |
| 46 | +- `packaging/` - Installer resources and scripts |
| 47 | + |
| 48 | +## Architecture |
| 49 | + |
| 50 | +**SharedCode Library**: The `SharedCode` INTERFACE library links plugin source code to both the main plugin target and the Tests target, avoiding ODR violations. |
| 51 | + |
| 52 | +**CMake Modules**: |
| 53 | +- `PamplejuceVersion.cmake` - Reads VERSION file, optional auto-bump patch level |
| 54 | +- `Assets.cmake` - Auto-includes all files in assets/ as binary data |
| 55 | +- `Tests.cmake` - Configures Catch2 test target |
| 56 | +- `Benchmarks.cmake` - Configures Catch2 benchmark target |
| 57 | +- `PamplejuceIPP.cmake` - Intel IPP integration (optional) |
| 58 | + |
| 59 | +**Test Discovery**: Uses `catch_discover_tests()` with `PRE_TEST` discovery mode for Xcode compatibility. |
| 60 | + |
| 61 | +## Key Configuration |
| 62 | + |
| 63 | +Edit `CMakeLists.txt` to customize: |
| 64 | +- `PROJECT_NAME` - Internal name (no spaces) |
| 65 | +- `PRODUCT_NAME` - Display name in DAWs (can have spaces) |
| 66 | +- `COMPANY_NAME` - Used for bundle name |
| 67 | +- `BUNDLE_ID` - macOS bundle identifier |
| 68 | +- `FORMATS` - Plugin formats to build (Standalone AU VST3 AUv3) |
| 69 | +- `PLUGIN_MANUFACTURER_CODE` / `PLUGIN_CODE` - 4-character plugin IDs |
| 70 | + |
| 71 | +Version is read from the `VERSION` file in project root. |
| 72 | + |
| 73 | +## Code Quality |
| 74 | + |
| 75 | +Always resolve any compile warnings encountered during builds. Warnings should be treated as errors and fixed before considering a task complete. |
| 76 | + |
| 77 | +Note: LSP/clangd often reports false positive diagnostic errors (like "undeclared identifier", "file not found") because it doesn't have full context of the JUCE module system. Ignore these unless the actual build fails. |
| 78 | + |
| 79 | +## Includes |
| 80 | + |
| 81 | +JUCE modules include common standard library headers (`<vector>`, `<algorithm>`, `<string>`, `<memory>`, etc.) so you don't need to add those explicitly in JUCE code. Adding them is harmless but redundant. |
| 82 | + |
| 83 | +## Realtime Safety |
| 84 | + |
| 85 | +For anything in the audio thread / hot DSP path (e.g. `processBlock`): |
| 86 | +- Allocate in constructors or `prepareToPlay`, not while rendering audio |
| 87 | +- Avoid dynamic allocations and container growth (`std::vector::push_back`, map insertion, string building) |
| 88 | +- Prefer fixed-size storage (`std::array`, preallocated buffers, fixed-capacity queues) |
| 89 | +- Keep operations deterministic and lock-free where possible |
| 90 | + |
| 91 | +## Code Style |
| 92 | + |
| 93 | +Uses `.clang-format` with Allman-style braces, 4-space indentation, no column limit. |
0 commit comments