pulp CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What Is This

Pulp is a cross-platform audio plugin and application framework. MIT-licensed. C++20 core, Swift on Apple, JS-scripted GPU UIs via Dawn/Skia/QuickJS. See VISION.md for the full picture.

---

Build & Test Commands

Build type — Release is the default

Always build Release unless you're actively investigating a bug. A Debug build of a JS-scripted GPU UI is dramatically slower than its Release equivalent (no -O3, no NDEBUG, asserts live, no inlining of canvas / Skia / Yoga / QuickJS) — slow enough that a UX-perceived regression in a Debug build is almost always the build type, not the code. The Codify-Release work made pulp build default to Release; match that convention when reaching for raw cmake too.

Rules of thumb:

• Default: cmake -S . -B build -DCMAKE_BUILD_TYPE=Release. Use pulp build (the CLI) when possible — it pins Release for you and refuses to silently flip.
• Flip to Debug only when: stepping in a debugger, capturing fresh runtime::log_info traces, repro'ing a sanitizer hit, or running validate-build.sh for a clean detached reconfigure pass. Restore Release immediately when the investigation ends.
• Reconfigure gotcha: a bare cmake -S . -B build (no build-type flag) usually preserves the cache value, BUT something in the shipyard / pre-push gate / rebase paths can silently reset the cache to Debug. Pass -DCMAKE_BUILD_TYPE=Release every reconfigure, or use pulp build.
• Verify before reporting a build is Release: BOTH grep '^CMAKE_BUILD_TYPE' build/CMakeCache.txt (should print Release) AND grep '^CXX_FLAGS ' build/<dir>/CMakeFiles/<target>.dir/flags.make (should contain -O3 -DNDEBUG) must check out. Checking only the cache field is necessary-but-not-sufficient — it has been wrong by itself.
• A struct-layout change must compile EVERYWHERE before shipping: when a change alters the field layout of a struct that is brace-initialized positionally (adding/removing a field, swapping a bool for an enum), run a FULL pulp build over ALL targets — not just the named feature/parity targets — and run it in the background (a full build exceeds a short foreground budget). This is the longest build anyone runs, so it is the one that most needs to take a governed share of the machine rather than every core; pulp build (or tools/ci/governed-build.sh cmake --build build) does that, a raw cmake --build … -j$(sysctl -n hw.ncpu) does not. Stray positional inits in unrelated test files fail closed at compile time, so they are safe, but only a full build surfaces them; building a subset and shipping pushes the discovery to CI. A uniform build failure across macOS/Linux/Windows is the tell for a real compile miss, versus the macOS-only stale-build-dir ODR the pulp-runner-ops skill handles.