Build and package troubleshooting

Treat a package failure as a reproducibility problem first: use a clean source checkout at the documented revision, a fresh build directory, and an isolated install prefix. Do not mix generated package files from an earlier build with a new source tree.

Package discovery and version mismatch

The consumer must request the exact documented package and version:

find_package(TreefallSDK 0.9.0 EXACT REQUIRED CONFIG)

If CMake reports that the package cannot be found, set CMAKE_PREFIX_PATH to the clean install prefix (or pass TreefallSDK_DIR to its package directory). Inspect the configure trace to confirm that the requested package config came from that prefix, not a system installation. If the version differs, remove the build directory and configure again against the pinned install; do not weaken EXACT to conceal drift.

A package can be found while a target is absent. Inspect share/treefall/installed-targets.json and the generated imported targets under the same prefix. The catalog is a compatibility artifact over one target graph; it is not a promise that every platform or optional target exists in every configuration.

Missing SndFile::sndfile

The documented evidence build requires the real SndFile provider. Configure with:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release \
  -DORPHEUS_ENABLE_REALTIME=ON \
  -DORPHEUS_BUILD_TESTS=OFF \
  -DORPHEUS_SNDFILE_PROVIDER=SndFile \
  -DCMAKE_INSTALL_PREFIX="$PWD/install"

If configuration cannot resolve SndFile::sndfile, install a supported libsndfile development package or point CMake at its package configuration, then start from a fresh build directory. Do not select Auto or None: without the required provider, the audio-file path is not evidenced and the build must remain a prerequisite failure.

Absent conditional targets

Platform targets appear only when their platform and dependencies permit generation. The absence of Treefall::audio_driver_coreaudio on a non-Apple host is expected. The generated WASAPI entry records source/fake-test capability only and does not make the backend release-supported. Optional JUCE targets require their feature flag and all listed JUCE dependencies. Verify target presence with CMake package discovery rather than constructing a target name from the host platform.

Clean-prefix diagnosis

1. Delete only the consumer build directory and point CMAKE_PREFIX_PATH at the intended install prefix.
2. Confirm the package version and source revision metadata in that prefix.
3. Confirm the requested target is listed in share/treefall/installed-targets.json.
4. Check that linked headers come from the same prefix as the imported target files.
5. If generated files disagree, rebuild and install the SDK into a new empty prefix; never patch generated package files by hand.

The evidence bundle is pinned to revision 0238eac1721d820d16ba5390e0e4641391be1d59. A clean-prefix diagnosis can explain local drift, but it cannot turn this preview into a statement about later development revisions.

Source authority

• CMakeLists.txt
• cmake/Dependencies.cmake
• cmake/TreefallSDKConfig.cmake.in
• cmake/installed-targets.json.in