pulp: Instructions file for Claude Code

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. A fresh pulp build/dev/loop configure pins -G Ninja (when on PATH), -DCMAKE_BUILD_TYPE=${PULP_BUILD_TYPE:-Release}, and, in the source checkout, -DPULP_BUILD_EXAMPLES=OFF unless --examples (pulp design turns them on); an EXISTING dir keeps its generator and non-empty cached build type.

Rules of thumb:

• Default: pulp build, or cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release.
• Focused by default in a source checkout: pulp build/dev/loop/test build and run only what the working diff affects (pulp affected --json shows it) behind a loud FOCUSED: building 3/1708 targets … line. --all restores everything, --target wins, PULP_BUILD_FOCUS=0 disables, and it widens to all (saying why) for an empty diff, a build-system change, an unmapped C/C++ file, or >40% of the graph. Focused green is not landing green — pre-push and Shipyard build all; rules: docs/reference/cli.md#affected.
• 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; restore Release when the investigation ends.
• Reconfigure gotcha: shipyard / pre-push / rebase paths can silently reset a cache to Debug, and pulp build keeps a non-empty cached type; pass -DCMAKE_BUILD_TYPE=Release (or PULP_BUILD_TYPE=Release pulp build).
• Verify before reporting a build is Release: BOTH grep '^CMAKE_BUILD_TYPE' build/CMakeCache.txt (prints Release) AND grep '^CXX_FLAGS ' build/<dir>/CMakeFiles/<target>.dir/flags.make (contains -O3 -DNDEBUG) must check out; the cache field alone 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 --all — not just the named feature/parity targets — in the background (it exceeds a short foreground budget). It is the longest build anyone runs, so it most needs a governed share of the machine, not 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 pushes the discovery to CI. A uniform macOS/Linux/Windows failure is the tell for a real compile miss, versus the macOS-only stale-build-dir ODR the pulp-runner-ops skill handles.