Core modernization and single-resolve dependency management

.github/workflows/build-puredata-plugins-with-pd-lib-builder.yml

@@ -56,13 +56,15 @@ jobs:
 
       - name: Set up Conan
         run: |
-          pip install conan
+          pip install "conan>=2.13,<3"
           conan profile detect
 
+      # Resolved at the repo root so this wrapper and zerr_core share one profile;
+      # puredata/Makefile reads ../build/conandeps.mk by default.
       - name: Configure Conan
-        working-directory: puredata
         run: |
-          conan install . --output-folder=build --build=missing
+          conan install . --output-folder=build --build=missing \
+            -pr:h=profiles/macos -pr:b=profiles/macos
 
       - name: Build & Install
         working-directory: puredata
@@ -108,13 +110,13 @@ jobs:
 
       - name: Set up Conan
         run: |
-          pip install conan
+          pip install "conan>=2.13,<3"
           conan profile detect
 
       - name: Configure Conan
-        working-directory: puredata
         run: |
-          conan install . --output-folder=build --build=missing
+          conan install . --output-folder=build --build=missing \
+            -pr:h=profiles/linux -pr:b=profiles/linux
 
       - name: Build & Install
         working-directory: puredata
@@ -220,14 +222,13 @@ jobs:
 
       - name: Set up Conan
         run: |
-          pip install conan
+          pip install "conan>=2.13,<3"
           conan profile detect --force
 
+      # mingw-profile.txt moved to profiles/mingw alongside the other profiles.
       - name: Install Dependencies
-        working-directory: puredata
         run: |
-          mkdir build
-          conan install . -pr:h=./mingw-profile.txt -pr:b=./mingw-profile.txt --output-folder=build --build=missing
+          conan install . -pr:h=profiles/mingw -pr:b=profiles/mingw --output-folder=build --build=missing
 
       - name: Build External
         shell: bash

.github/workflows/build-zerr-core-static-library.yml

@@ -7,6 +7,13 @@ on:
       - main
     paths:
       - "core/**"
+      - "conanfile.txt"
+      - "profiles/**"
+
+# Dependencies are resolved once at the repo root (see /conanfile.txt) using a
+# committed profile, so CI and local builds share one dependency configuration.
+# conan is pinned below the next major: a bare `pip install conan` would float to
+# conan 3.x and break these jobs with no change on our side.
 
 jobs:
   macOS:
@@ -17,21 +24,21 @@ jobs:
 
       - name: Set up Conan
         run: |
-          pip install conan
+          pip install "conan>=2.13,<3"
           conan profile detect
 
       - name: Install Dependencies
-        working-directory: core
         run: |
-          conan install . --output-folder=build --build=missing
+          conan install . --output-folder=build --build=missing \
+            -pr:h=profiles/macos -pr:b=profiles/macos
 
       - name: Build Static Library
-        working-directory: core
         run: |
-          cd build/
-          cmake .. -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release
-          cmake --build .
-          make install
+          cmake -S core -B core/build \
+            -DCMAKE_TOOLCHAIN_FILE="$GITHUB_WORKSPACE/build/conan_toolchain.cmake" \
+            -DCMAKE_BUILD_TYPE=Release
+          cmake --build core/build
+          cmake --install core/build
 
       - name: Upload zerr-core library
         uses: actions/upload-artifact@v4
@@ -48,22 +55,22 @@ jobs:
 
       - name: Set up Conan
         run: |
-          pip install conan
+          pip install "conan>=2.13,<3"
           conan profile detect
 
       - name: Install Dependencies
-        working-directory: core
         run: |
-          conan install . --output-folder=build --build=missing
+          conan install . --output-folder=build --build=missing \
+            -pr:h=profiles/linux -pr:b=profiles/linux
 
       - name: Build Static Library
-        working-directory: core
         run: |
           export CXXFLAGS="-fPIC"
-          cd build/
-          cmake .. -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release
-          cmake --build .
-          make install
+          cmake -S core -B core/build \
+            -DCMAKE_TOOLCHAIN_FILE="$GITHUB_WORKSPACE/build/conan_toolchain.cmake" \
+            -DCMAKE_BUILD_TYPE=Release
+          cmake --build core/build
+          cmake --install core/build
 
       - name: Upload zerr-core library
         uses: actions/upload-artifact@v4
@@ -85,29 +92,30 @@ jobs:
 
       - name: Set up Conan
         run: |
-          pip install conan
+          pip install "conan>=2.13,<3"
           conan profile detect --force
 
+      # Deliberately keeps its inline settings rather than -pr:h=profiles/mingw:
+      # this job builds natively with "MinGW Makefiles" on windows-latest, whereas
+      # profiles/mingw additionally pins compiler_executables for the
+      # cross-compiling PureData job. Switching it is untested — see docs/design.
       - name: Install Dependencies
-        working-directory: core
         run: |
-          mkdir build
           conan install . --output-folder=build --build=missing `
             -s compiler=gcc `
             -s compiler.version=13 `
             -s compiler.libcxx=libstdc++11 `
             -s build_type=Release
 
       - name: Build Static Library
-        working-directory: core
         run: |
-          cmake -S . -B build `
+          cmake -S core -B core/build `
             -G "MinGW Makefiles" `
-            -DCMAKE_TOOLCHAIN_FILE="build/conan_toolchain.cmake" `
+            -DCMAKE_TOOLCHAIN_FILE="${{ github.workspace }}/build/conan_toolchain.cmake" `
             -DCMAKE_BUILD_TYPE=Release `
             -DCMAKE_CXX_STANDARD=17
-          cmake --build build --config Release
-          cmake --install build
+          cmake --build core/build --config Release
+          cmake --install core/build
 
       - name: Upload zerr-core library
         uses: actions/upload-artifact@v4

.github/workflows/deploy-doxygen.yml

@@ -0,0 +1,53 @@
+name: Deploy Doxygen documentation
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    paths:
+      - "core/include/**"
+      - "docs/**"
+
+permissions:
+  # Specifying any permissions sets every unlisted scope to `none`, so
+  # actions/checkout needs contents: read stated explicitly -- without it the
+  # checkout has no repo read scope and the deploy breaks the moment the repo is
+  # private or default token permissions tighten.
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v3
+        with:
+          submodules: true
+
+      - name: Install Doxygen
+        run: sudo apt-get install -y doxygen
+
+      - name: Generate documentation
+        run: doxygen docs/Doxyfile
+
+      - name: Configure Pages
+        uses: actions/configure-pages@v4
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/build/html
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -26,6 +26,7 @@ fftw3/
 yaml-cpp/
 
 # Documentation output
+docs/build/
 html/
 latex/
 

.gitmodules

@@ -9,3 +9,6 @@
 [submodule "maxmsp/source/min-lib"]
 	path = maxmsp/source/min-lib
 	url = https://github.com/Cycling74/min-lib.git
+[submodule "doxygen-awesome-css"]
+	path = docs/doxygen-awesome-css
+	url = https://github.com/jothepro/doxygen-awesome-css.git

CLAUDE.md

@@ -10,25 +10,43 @@ Reference paper: "Autogenous Spatialization for Arbitrary Loudspeaker Setups" (I
 
 ## Build Commands
 
+### Dependencies (resolved once, at the repo root)
+
+Declared in the root `conanfile.txt` and installed into a single shared `build/` folder that every
+target consumes: core and Max/MSP via `build/conan_toolchain.cmake`, PureData via
+`build/conandeps.mk`. Committed profiles in `profiles/` (`macos`, `linux`, `mingw`) pin the settings
+that must be reproducible across machines. Recipe revisions are pinned in `conanfile.txt` because both
+libraries need a ConanCenter revision that supports CMake 4. The macOS deployment target is set in
+`core/CMakeLists.txt` and `maxmsp/CMakeLists.txt`, not in the profile.
+
+```bash
+conan install . --output-folder=build --build=missing \
+  -pr:h=profiles/macos -pr:b=profiles/macos   # or profiles/linux, profiles/mingw
+```
+
+`build.sh` does this automatically on first use. Conan is only needed when dependencies actually
+need resolving — a tree with a populated `build/` still builds without it.
+
 ### Core Library (must be built first — other targets depend on `libzerr_core.a`)
 
 ```bash
-cd core
-conan install . --output-folder=build --build=missing
-cd build
-cmake .. -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release
-cmake --build .
-make install  # Installs to core/lib
+cmake -S core -B core/build \
+  -DCMAKE_TOOLCHAIN_FILE="$PWD/build/conan_toolchain.cmake" -DCMAKE_BUILD_TYPE=Release
+cmake --build core/build
+cmake --install core/build   # Installs to core/lib
 ```
 
 ### Using the build script (recommended)
 
 ```bash
+./build.sh deps              # Resolve dependencies only
+./build.sh -c deps           # Discard resolved dependencies
+./build.sh core              # Build core library
 ./build.sh puredata          # Build PureData externals (auto-builds core if needed)
 ./build.sh -i puredata       # Build and install
 ./build.sh maxmsp            # Build Max/MSP externals
 ./build.sh -i maxmsp         # Build and install
-./build.sh jack              # JACK client (in development)
+./build.sh jack              # JACK client — currently broken, see docs/design/repo-audit-2026-07-30.md
 ```
 
 ### Code Formatting
@@ -78,10 +96,17 @@ YAML files defining speaker positions in Cartesian coordinates (x, y, z). Exampl
 - **Namespace**: `zerr`, features in `zerr::feature`
 - **Custom types** (`types.h`): `Sample` = double, `Param` = float, `Index` = int
 - **Naming**: PascalCase classes, camelCase methods, `_prefixed` private methods
-- **Dependencies**: Conan 2.x manages fftw3 and yaml-cpp
+- **Dependencies**: Conan 2.x manages fftw3 and yaml-cpp, declared once in the root `conanfile.txt`
 
 ## Platform Notes
 
 - **macOS**: Supports Intel + Apple Silicon (fat binaries with Xcode 12+)
 - **Linux**: Requires `-fPIC` for static library builds
-- **Windows**: MinGW-w64 gcc 13 for PureData; uses `puredata/mingw-profile.txt` Conan profile
+- **Windows**: MinGW-w64 gcc 13 for PureData; uses the `profiles/mingw` Conan profile. `build.sh`
+  runs from an MSYS2 MINGW64 / Git Bash shell — it pins the `MinGW Makefiles` generator and prefers
+  `mingw32-make`. Max/MSP is not buildable there (`.mxe64` needs MSVC, which cannot link a
+  MinGW-built core); `build.sh maxmsp` refuses with a message
+
+Before changing any `find_package` call, the `CONAN_*` variables in `puredata/Makefile`, or
+`conanfile.txt`, read `docs/design/dependency-fallbacks.md` — it records which non-conan resolve
+routes are viable and what each one breaks (target names, static/shared, deployment target, CMake 4).

README.md

@@ -42,13 +42,19 @@ Otherwise, you can also build it for your own machine.
 #### Dependencies
 
 - Zerr* uses [Conan](https://docs.conan.io/2/tutorial.html) for dependency management, please refer to its documentation for details
-- The core library of Zerr* depends only on [yaml-cpp](https://github.com/jbeder/yaml-cpp) and [fftw3](https://www.fftw.org/). Use the following Conan command to install them
+- The core library of Zerr* depends only on [yaml-cpp](https://github.com/jbeder/yaml-cpp) and [fftw3](https://www.fftw.org/). Both are declared once in the root `conanfile.txt` and resolved into a single shared `build/` folder that every target consumes — the core and Max/MSP via `build/conan_toolchain.cmake`, PureData via `build/conandeps.mk`
 
 ```bash
-conan install . --output-folder=build --build=missing
+# from the repo root; pick the profile matching your host
+conan install . --output-folder=build --build=missing \
+  -pr:h=profiles/macos -pr:b=profiles/macos
 ```
 
-- You can also edit the paths in MakefIle/CMakeLists.txt to point to your own 
+- Committed profiles live in `profiles/` (`macos`, `linux`, `mingw`), so dependency resolution is reproducible instead of depending on each machine's `~/.conan2` default. Recipe revisions are pinned in `conanfile.txt` because both libraries need a ConanCenter revision that supports CMake 4. Read `profiles/macos` before changing either — it records which settings are deliberately *not* pinned, and why
+- The macOS deployment target is set in `core/CMakeLists.txt` (and `maxmsp/CMakeLists.txt`), not via the Conan profile — see the comment in `profiles/macos` for the reasoning
+- `./build.sh` resolves dependencies automatically on first use, so the command above is only needed for a manual or non-default build. `./build.sh deps` re-runs just the resolve step, and `./build.sh -c deps` discards it
+- Conan is only required when dependencies actually need resolving; a tree with a populated `build/` folder still builds without it
+- You can also edit the paths in Makefile/CMakeLists.txt to point to your own 
 
 #### For Puredata
 
@@ -64,6 +70,29 @@ conan install . --output-folder=build --build=missing
 ./build.sh -i puredata
 ```
 
+#### On Windows
+
+`build.sh` runs on Windows as well, from an **MSYS2 MINGW64** or Git Bash shell. It detects the host
+and selects `profiles/mingw`, pins CMake to the `MinGW Makefiles` generator — without that, CMake
+picks Visual Studio whenever one is installed and compiles with MSVC against a MinGW toolchain — and
+uses `mingw32-make` in preference to the MSYS `make`. There is no `.bat`/PowerShell equivalent;
+native `cmd.exe` is not supported.
+
+```bash
+# in an MSYS2 MINGW64 shell, with MinGW-w64 gcc 13 on PATH
+./build.sh deps
+./build.sh core
+./build.sh puredata
+```
+
+pd-lib-builder needs to find your Pd installation for `m_pd.h`; set `PDDIR` if it does not locate it
+on its own.
+
+Max/MSP cannot be built on Windows from this script — a `.mxe64` requires an MSVC toolchain, whose
+runtime and C++ ABI cannot link against the MinGW-built `libzerr_core.a` that `profiles/mingw`
+produces. `./build.sh maxmsp` reports this and exits rather than failing inside Min-DevKit. See
+[`docs/design/dependency-fallbacks.md`](docs/design/dependency-fallbacks.md) §3.7.
+
 #### For Jack
 
 ```bash