theallelectricsmartgrid

Building and reclaiming worktree output

Use the existing worktree and reuse its builds across edits, reviews, and retries. Commands below run from the checkout root. From elsewhere, use make -C /absolute/path/to/worktree <target> or make -f /absolute/path/to/worktree/Makefile <target>; paths are resolved from the Makefile, not the caller’s working directory. The app Makefile also supports make -C JUCE/SmartGridOne <app-target> and an absolute -f path.

Shared build cache

Make builds use ~/.cache/theallelectricsmartgrid by default, or $XDG_CACHE_HOME/theallelectricsmartgrid when XDG_CACHE_HOME is set. Set SMARTGRID_BUILD_CACHE_DIR to an absolute directory to choose another location. Use the same writable directory in every worktree. Add that directory to the active Codex permission profile for sandboxed builds. To use a cache local to one worktree, set SMARTGRID_BUILD_CACHE_DIR="$PWD/build/cache".

The cache holds Lean toolchains, compiled Lake artifacts, downloaded Mathlib archives, and JUCE source snapshots. CMake, Xcode, and Lake keep their build directories under each worktree’s build/, so branches can build independently.

JUCE

App builds, ios-deploy (and deploy-ios), clang-tidy, and the MIDI and visualizer test targets use a shared JUCE source snapshot keyed by the pinned submodule commit. The first build uses the main checkout’s Git objects when available, or fetches that commit from the submodule URL. make juce-deps prepares the snapshot and prints the source path. Treat the snapshot as read-only.

For JUCE development, Projucer, or opening the Xcode projects directly, run:

make juce-setup

This checks out the pinned submodule in the current worktree. Make builds prefer an existing local JUCE checkout, including any local JUCE edits.

Build and test

Command Default output directory
make build / make run build/xcode/macos/Release/
make build-sanitized / make run-sanitized build/xcode/macos/Debug/
make ios-build / make ios-install / make ios-deploy build/xcode/ios/Release/
make core-test build/core/RelWithDebInfo/
make perf-build / make perf-test / make perf-run / make perf-sgrec / make perf-responses build/tools/perf/Release/ (results in build/results/)
make perf-ipad-build / make perf-ipad build/tools/perf-ipad/Release/ (results in ~/Documents/SmartGridOne/perf.sqlite3)
make visualizers-test build/visualizers/Release/
make midi-test build/midi/Release/
make clang-tidy build/clang-tidy/report.txt
make lean-test build/lean/
make lean-dsp-test build/lean/
make lean-dsp-codegen / make lean-dsp-codegen-test build/lean/generated/, build/lean/codegen-test/
make lean-dsp-generate Updates the headers in formal/DSP/generated/ from build-tree generation
make perf-ladder-build / make perf-ladder PERF_ARGS="9 4194304" Builds/runs the ladder comparison in build/tools/perf/Release/
make perf-comb-build / make perf-comb PERF_ARGS="9 8388608" Builds/runs only the generated stereo/quad comb benchmark in build/tools/perf/Release/

The CMake families also expose core-configure / core-build, visualizers-configure / visualizers-build, and midi-configure / midi-build. Each build reconfigures the same cache and builds incrementally; test targets build first and run CTest with failure output. Use JOBS=6 to change CMake build parallelism (default 4), and CMAKE_ARGS='...' for additional configure options. The core requires CMake, a C++17 compiler, Python 3, pkg-config, and libFLAC. JUCE tests require macOS. When ccache is on PATH, the core, MIDI, visualizer, and desktop performance builds use it automatically. Its default store is ccache/ under the shared cache directory, and CCACHE_DIR overrides it. Use CCACHE= to disable the launcher. Hits depend on the compiler flags and paths in the compile command, including the debug-info configuration.

Use CORE_CONFIG=Debug, VISUALIZERS_CONFIG=Debug, or MIDI_CONFIG=Debug for separate debug test builds. Core tests default to RelWithDebInfo with assertions enabled; do not disable assertions to speed up validation. Do not use CMAKE_ARGS to override the configuration or binary directory behind Make’s back. For a focused core run after make core-build:

build/core/RelWithDebInfo/smartgrid_tests --test-case='SequencerUI:*'

Native app targets use CONFIG=Release by default; CONFIG=Debug selects a separate build. Sanitized targets always use the project’s Debug configuration, which enables AddressSanitizer. Each Xcode configuration contains DerivedData/, Intermediates/ (including precompiled headers), and Products/SmartGridOne.app. Make explicitly supplies these paths, including the product directory that the generated Xcode projects otherwise override. Use these Make targets for the contained command-line workflow; opening a project directly in Xcode uses the IDE’s own DerivedData preferences. XCODE_FLAGS='...' passes additional Xcode options. Keep the path settings intact. Xcode app and iPad performance builds compile into their worktree’s own build directories.

ios-install uses the selected configuration’s existing app and fails if it is missing. ios-deploy builds successfully before installing and launching; deploy-ios is its alias. Direct scripts/ios_deploy.py defaults to the canonical iOS Release product; pass --app for another configuration. Device overrides and setup are described in ipad-tools.md.

Run only one build/test at a time per output directory, including across separate Make processes. Use separate configurations or an explicitly chosen build directory for simultaneous builds with different options. A fresh build or an output location outside the worktree needs a concrete technical reason; do not create a new /tmp tree for each edit, review, or retry. Historical audit and experiment documents retain their original commands and evidence paths.

Performance benchmarks

make perf-test builds the separate optimized Release harness and smoke-tests component, encoder matrix replay, and full SynthRig workloads. make perf-run records serial repeated timings in ms CPU/sec audio, without launching the app. See the benchmark guide for workload selection, input captures, measurement boundaries, and before/after comparisons. These targets do not change the core tests’ assertion-enabled configuration.

For an SGREC performance investigation, run make perf-sgrec SGREC_ARGS='"/path/to/jam.sgrec" --callback-frames 512'. This validates and replays the whole control timeline, saving CPU/wall timings for each callback-sized window and percentile/worst-callback summaries. Supply the callback size from the app’s audio route log; SGREC storage blocks are not device callbacks. See the SGREC benchmark guide for duration limits, serial repeats, output files and interpretation limits.

Lean specifications

Run make lean-setup once per cache and pinned toolchain version. You can run make lean-cache to prefetch the pinned Mathlib proof cache. make lean-test checks the reusable DSP filter proofs, encoder and phase-time Lean/Veil state machines, contract proofs, proof axioms, and C++ source references. Elan installs the pinned toolchain under elan/ in the shared cache. Lake’s artifact cache reuses compiled modules across worktrees when their inputs match. Mathlib downloads go into the shared mathlib/ directory. Dependency checkouts and restored outputs live under build/lean/ in each worktree, and the small Lake configuration cache lives at .lake/. Setup requirements, model coverage and proof boundaries are documented in formal/DSP/README.md, formal/Encoder/README.md and formal/PhaseTime/README.md.

make lean-dsp-test runs the DSP proofs and axiom audit plus a native executable smoke test of the generic one-pole, SVF, morph and ladder filters with Float (and Float32 for the one-poles). The full lean-test target also includes this executable check. The filter arithmetic and state updates are shared by the executable cores and the real-number proofs; the smoke test does not establish floating-point error bounds. It also checks the standalone C++ processor generator, compares native Lean/C++ execution, and verifies the saved generated headers are current. Both scalar headers and Generic<Number, Size> headers are checked; the latter use the app’s MultiChannelNumber at widths 1, 2, 3 and 4 with float and double. Run make lean-dsp-generate to refresh those headers for review. See the codegen guide for the supported Lean subset and the distinction between model proofs and code-generation tests.

The app’s delay/reverb damping filters and SVF consumers include the checked-in generated TPT headers. CMake targets and both Xcode projects include formal/DSP/generated and compile with -fno-fast-math -ffp-contract=off, matching the codegen arithmetic contract. Explicit FusedMultiplyAdd calls remain fused. App builds consume the checked-in C++ headers without invoking Lean.

Cleanup and completion

When keeping a worktree, make clean removes these complete disposable trees, including every configuration, CMake cache, generated JUCE overlay, Xcode cache, intermediate, product, and clang-tidy report inside them:

build/core/             build/visualizers/       build/midi/
build/xcode/macos/      build/xcode/ios/         build/clang-tidy/
build/tools/

Cleanup does not invoke Xcode, accept output-path overrides, or remove the whole build/ directory. It checks all targets before deletion and refuses symlinked target directories or ancestors. Source files, pinned third_party/ dependencies, scripts/.venv-ios, legacy build directories, external /tmp output, global DerivedData, and other worktrees are outside its scope. Never run cleanup while a build/test uses those directories.

Keep unique experiment results, recordings, and logs worth preserving under build/results/ (ignored and preserved by make clean) or outside disposable build trees. Move any needed CTest logs out of their build tree before cleaning.

At completion, finish validation and land through the repository Git workflow. Preserve unique results and other needed ignored files outside the worktree, then archive/remove that worktree through its owning tool. Codex uses archive_worktree; its snapshot does not preserve ignored output. If this task initialized submodules, deinitialize those clean dependencies before archiving because the managed archive tool does not accept initialized submodules. Do not run a redundant make clean immediately before removing the checkout.