Building Guitar Prometheus

Requirements

macOS 11.0+ or Windows 10/11 (Linux build is best-effort; see CI for Ubuntu config).
Xcode Command Line Tools (macOS) or MSVC v143 + Windows SDK (see Building on Windows).
CMake 3.22 or newer.
rsvg-convert (from librsvg) on the host running the build. Install with brew install librsvg (macOS) or apt install librsvg2-bin (Linux). The build invokes it to rasterise the SVG app icon at configure time.

JUCE 8.0.13, pugixml, nlohmann_json, and Catch2 are fetched via FetchContent at configure time. No system-level JUCE installation is needed.

Configure

cmake -B build -S .

The first configure clones JUCE and the third-party libraries into build/_deps/. Subsequent configures reuse the cached copies.

CMake options

Option	Default	Description
`GP_ENABLE_SCORE_VIEWER`	`OFF`	Compiles the Phase 13 Verovio-based score viewer panel and its menu wiring. Off by default because the rendering pass has open layout / SMuFL issues; see the Wishlist. Enable for local development with `-DGP_ENABLE_SCORE_VIEWER=ON`.

Build

cmake --build build

Targets:

Target	Description
`GuitarPrometheus`	The desktop app bundle (`Guitar Prometheus.app` on macOS).
`GuitarPrometheusTests`	The Catch2 test runner.
`guitar_prometheus_core`	The static library every other target links against.
`format`	Runs clang-format in-place across the source tree (uses `.clang-format`).

Build a single target with cmake --build build --target <name>.

Run the App

open build/GuitarPrometheus_artefacts/Release/Guitar\ Prometheus.app

(or Debug, depending on the configure-time CMAKE_BUILD_TYPE).

Editor Setup

The repo ships a .clang-format matching the in-tree style. Any editor plugin that runs clang-format on save will keep your changes consistent with the existing tree.

clangd has the include paths it needs from compile_commands.json. Configure your editor to point at build/compile_commands.json so go-to-definition and diagnostics work.

Previewing Documentation Changes

scripts/preview-docs-site.sh mirrors the production Docker pipeline locally: it stages documentation/ into docs-site/src/content/docs/, generates the API reference via Doxygen + doxybook2, injects Starlight frontmatter, rewrites relative .md links, and runs pnpm install plus pnpm build. The output lands in docs-site/dist/.

Prerequisites:

brew install doxygen librsvg
# doxybook2 is not in homebrew; grab v1.5.0 from
# https://github.com/matusnovak/doxybook2/releases

Then:

scripts/preview-docs-site.sh
cd docs-site && pnpm preview     # serves on :4321

Use this before pushing any change under documentation/ — the production build at guitar-prometheus.nullfragment.dev runs the same pipeline, so passing locally is a strong signal CI will too.