Investigate imported-target workaround in downstream consumers; fix or simplify

[joshkamm]

ZEST's CMakeLists (CMakeLists.txt:45-118) contains ~74 lines of diagnostics and find_library fallback for SlaterGPU::io and SlaterGPU::cintw, with comments suggesting these targets sometimes appear without IMPORTED_LOCATION. XCtera's CMakeLists (CMakeLists.txt:38-49) has a slimmer version of the same fallback.

SlaterGPU's actual install/export setup (src/CMakeLists.txt:13-30) does correctly install SlaterGPU, io, and cintw to EXPORT SlaterGPUTargets. So the fallback may be vestigial defensive code from a past defect.

Goal

Determine the truth of the matter and act on it.

Investigation steps

1. Build ZEST against a clean SlaterGPU install. Inspect the actual values of IMPORTED_LOCATION, IMPORTED_LOCATION_RELEASE, and IMPORTED_IMPLIB on SlaterGPU::io and SlaterGPU::cintw — the message(STATUS ...) calls at ZEST/CMakeLists.txt:53-92 already print these — read them.
2. If properties are populated correctly: open follow-up PRs in ZEST and XCtera to delete the fallback (this issue closes as "no source fix needed; consumers will be simplified separately").
3. If properties are missing: identify the install/export step that's incomplete (likely something about SHARED libs missing the LIBRARY DESTINATION interaction, or build-type-specific IMPORTED_LOCATION_<CONFIG> not being set). Fix in SlaterGPU.

Legacy workflow impact

Low. Paul's Makefile doesn't use find_package(SlaterGPU). Manual CMake builds (no pixi) benefit from any source fix.

Acceptance

• Either: SlaterGPU's exported imported targets carry IMPORTED_LOCATION correctly, and ZEST/XCtera CMakeLists drop the fallback in their respective follow-up PRs.
• Or: confirmed working as-is and the workaround is documented as removable; follow-up cleanup PRs are filed against ZEST and XCtera.

Context

Part of a broader dependency-infrastructure effort tracked in ZimmermanGroup/XCtera (umbrella tracking issue will be linked once filed).

[joshkamm]

Plan: Resolve imported-target workaround

This is sub-task A1 of the umbrella effort tracked in XCtera#13. Question: is the ~74-line IMPORTED_LOCATION fallback at ZEST/CMakeLists.txt L45-118 (plus the slim copy at XCtera/CMakeLists.txt L38-49) solving a real SlaterGPU defect, or vestigial?

Scope: filing the ZEST + XCtera cleanup PRs is the deliverable of this issue, not deferred. ZEST#87's Out of scope explicitly pushes the workaround removal back here ("but if that lands first, drop the workaround block as part of this PR" — i.e. B only inherits it if #88 hasn't already done it).

Why the code exists (best-guess; to be confirmed/refuted by step 2)

The workaround was added 2025-07-01 alongside cross-repo SlaterGPU↔ZEST integration — almost certainly fixing a real error. Hypotheses, leading first:

1. Consumer Debug build hitting a per-config gap. SlaterGPU installs only `SlaterGPUTargets-release.cmake` (no Debug variant). If ZEST was configured with `CMAKE_BUILD_TYPE=Debug` (or unset, depending on the generator and pixi-build-cmake version at the time), CMake's link logic would search for `IMPORTED_LOCATION_DEBUG`, find nothing, and either auto-fall-back through `IMPORTED_CONFIGURATIONS` (works in newer CMake for SHARED imports) or error with `"imported target SlaterGPU::io has no location"`. The workaround sidesteps the config-matching machinery entirely by `find_library`-ing the on-disk `.so` — which works in any build type. This is the strongest fit because ZEST does explicitly support Debug (CMakeLists.txt L165-166, generator expressions toggle `-O0 -g` vs `-O3 -g`).
2. Conditional `cintw` install with inconsistent DO_GTO. SlaterGPU's src/CMakeLists.txt L18-24 adds `cintw` to EXPORT only under `DO_GTO`. If `DO_GTO` was inconsistent at the time, `SlaterGPU::cintw` would be missing — `if(TARGET ...)` + `find_library` lets ZEST proceed. However, this is theatrical: ZEST's public headers unconditionally `#include "cintwrapper.h"` (include/hartree.h L36), so a DO_GTO=OFF SlaterGPU breaks ZEST at C++ compile regardless.

The diagnostic prints all three of `IMPORTED_LOCATION`, `IMPORTED_LOCATION_RELEASE`, `IMPORTED_IMPLIB` — that's shotgunning, consistent with not having pinned the root cause at the time.

What this means for Debug/Release support

What "Debug ZEST" actually means here: SlaterGPU's pixi install always builds Release. ZEST being in Debug doesn't trigger a SlaterGPU rebuild — ZEST just links against the pre-installed Release `.so`s. So ZEST's own source compiles with `-O0 -g` while linking optimized SlaterGPU symbols. Standard pattern (e.g. debugging a Python C extension against an installed scipy). The shim discussed below doesn't change SlaterGPU's build type; it only tells CMake's link logic, "when a Debug consumer asks for `SlaterGPU::io`, use the only-available Release artifact." Actually debugging into SlaterGPU symbols would require building SlaterGPU with `CMAKE_BUILD_TYPE=Debug` — out of scope.

• Today (with workaround): Debug ZEST builds work trivially because the `find_library`-of-`.so` path is config-agnostic.
• After workaround removal (status quo SlaterGPU): Debug works only if CMake's auto-fallback through `IMPORTED_CONFIGURATIONS` succeeds. Empirically true for SHARED imports in modern CMake, but undocumented as guaranteed and silently breaks on weirder configurations.
• Conditional fix: add the following shim only if step 3 shows Debug consumers fail without it. In SlaterGPUConfig.cmake.in, after the `include(...SlaterGPUTargets.cmake)` line:
  ```cmake
  foreach(_target SlaterGPU::SlaterGPU SlaterGPU::io SlaterGPU::cintw)
  if(TARGET ${_target})
  set_target_properties(${_target} PROPERTIES
  MAP_IMPORTED_CONFIG_DEBUG Release
  MAP_IMPORTED_CONFIG_RELWITHDEBINFO Release
  MAP_IMPORTED_CONFIG_MINSIZEREL Release)
  endif()
  endforeach()
  ```
  Don't add it preemptively — only if step 3 surfaces an actual link failure. Premature inclusion is the same flavor of defensive shim that motivated this whole investigation; add only with evidence.

Scope summary: #88 is "consumer cleanup PRs + (conditionally) a small SlaterGPU `Config.cmake.in` shim if Debug breaks." Likely just the cleanup PRs.

DO_GTO=OFF: not actually supported today

ZEST's public headers unconditionally include `cintwrapper.h`. SlaterGPU defaults `DO_GTO=True` (CMakeLists.txt L29-30). The workaround pretends to handle missing `cintw` but ZEST source would fail to compile regardless. Cleanup PRs can unconditionally link `SlaterGPU::cintw`; no DO_GTO conditional needed in ZEST. (Real DO_GTO=OFF ZEST support is a separate ZEST source change — `#ifdef`-guard the `cintwrapper.h` includes — and out of scope here.)

Current static findings

• `SlaterGPUTargets-release.cmake` (generated, lines 20-34) sets `IMPORTED_LOCATION_RELEASE` + `IMPORTED_SONAME_RELEASE` on `io` and `cintw`; for `cintw` also `IMPORTED_LINK_DEPENDENT_LIBRARIES_RELEASE "SlaterGPU::cint"` (the libcint transitive link).
• Plain `IMPORTED_LOCATION` (no `_`) is never set — intrinsic CMake behavior, not a SlaterGPU bug.
• Removal is a fix, not just cleanup. The link expression at ZEST/CMakeLists.txt L102 branches on plain `IO_LOCATION` (always empty), so today it links the raw `find_library` path, not `SlaterGPU::io`/`SlaterGPU::cintw`. That silently bypasses `IMPORTED_LINK_DEPENDENT_LIBRARIES_RELEASE` (the cint link), surviving only because cint arrives via the static `libSlaterGPU.a` / `.so` `DT_NEEDED`. Linking the imported targets directly restores intended wiring.

Provisional conclusion (steps 1-3 will confirm/refute): delete the workaround in ZEST and XCtera, link the imported targets directly. Add the `MAP_IMPORTED_CONFIG_*` mapping to SlaterGPU's `Config.cmake.in` only if step 3 surfaces an actual Debug-consumer failure.

Execution steps

1. Empirically confirm the diagnosis (workaround still in place). Clean-build ZEST against the current SlaterGPU install with `pixi clean --build && pixi install`. Read the `STATUS`/`WARNING` lines from the workaround block. Expect: targets found, plain `IMPORTED_LOCATION` ``, `IMPORTED_LOCATION_RELEASE` a real `libio.so`/`libcintw.so` path, and the `find_library` fallback reporting it found the libs. Capture verbatim.
2. Probe original failure in Release. In a throwaway scratch branch (no commit), comment out the ZEST workaround block and replace the conditional generator-expression link with `target_link_libraries(ZEST PRIVATE SlaterGPU::SlaterGPU SlaterGPU::io SlaterGPU::cintw)`. Rebuild. Builds + `ldd` clean → proceed. Fails → capture error; original failure resurfacing; stop and re-evaluate.
3. Probe Debug-consumer behavior. Same scratch branch. Force `CMAKE_BUILD_TYPE=Debug` for ZEST. Rebuild. Pass → done, no SlaterGPU change needed, skip step 4. Fail with "no location" → proceed to step 4.
4. SlaterGPU PR (only if step 3 fails). Add the `MAP_IMPORTED_CONFIG_*` block to `SlaterGPUConfig.cmake.in`. Verify with downstream Debug ZEST build. Open PR; merge before consumer cleanup PRs land.
5. ZEST cleanup PR. (Only after steps 2-3 pass.) Apply scratch-branch deletions as a real commit. Verify Release + Debug, `ldd` shows `libio.so`/`libcintw.so`/`libcint.so` in both.
6. XCtera cleanup PR. Same approach for XCtera/CMakeLists.txt L38-49: drop the `find_library` fallback, link `SlaterGPU::io`/`SlaterGPU::cintw` directly. Verify both Release and Debug; XCtera CI matrix covers Release.
7. Document & close Investigate imported-target workaround in downstream consumers; fix or simplify #88. Comment here with: empirical log from step 1, step-2/3 results, the cint-bypass + DO_GTO findings, and links to the (up to three) PRs.
8. Update umbrella tracker XCtera#13: tick A1.

Out of scope

• Per-config Debug install on SlaterGPU side (shipping actual `SlaterGPUTargets-debug.cmake` with Debug-built `.so`s).
• ZEST source change to `#ifdef`-guard `cintwrapper.h` includes for real DO_GTO=OFF support.
• ZEST library refactor (B / ZEST#87), XCtera-adds-ZEST (C / XCtera#11), run-exports (#89).

[joshkamm]

Diagnosis update — step 1 results, both Phase-1 hypotheses wrong

Just ran the empirical confirmation (clean ZEST build with workaround in place). Both leading hypotheses (Debug per-config gap, DO_GTO inconsistency) are wrong. The actual root cause is simpler:

The real shadow

ZEST ships its own cmake/FindSlaterGPU.cmake (49 lines, added 2025-06-18 in commit 14cff5e during initial CMake bring-up). Because ZEST's find_package(SlaterGPU REQUIRED) call lacks the CONFIG keyword, CMake defaults to module mode and uses this hand-rolled module — SlaterGPUConfig.cmake is never consulted.

The hand-rolled module:

• Declares only SlaterGPU::SlaterGPU (static archive)
• Does NOT declare SlaterGPU::io or SlaterGPU::cintw
• Leaves SlaterGPU_INCLUDE_DIRS empty (the include-path block is commented out)

When io + cintw were added to SlaterGPU's exports later that month, ZEST's link broke with "SlaterGPU::io target not found". The workaround block was added 2025-07-01 (ZEST commit 5d11cbb) to compensate by find_library-ing the .sos directly — papering over the fact that the imported targets simply don't exist in ZEST's namespace.

Empirical confirmation (today's clean build)

-- SlaterGPU_FOUND: TRUE
-- SlaterGPU_LIBRARIES: $PREFIX/lib/libSlaterGPU.a    # FindSlaterGPU.cmake's value, NOT Config.cmake's targets list
CMake Warning at CMakeLists.txt:68 (message):
  SlaterGPU::io target not found
CMake Warning at CMakeLists.txt:90 (message):
  SlaterGPU::cintw target not found
-- SlaterGPU_INCLUDE_DIRS:                            # empty

XCtera has the same shadow

XCtera/cmake/FindSlaterGPU.cmake (34-line slimmer copy). Its workaround comment even names the symptom: "the imported targets sometimes ship without IMPORTED_LOCATION" — close, but wrong: the targets aren't defined, not lacking a property.

Revised fix shape

Cleaner than the original plan. In each of ZEST and XCtera:

1. Delete cmake/FindSlaterGPU.cmake
2. Change find_package(SlaterGPU REQUIRED) → find_package(SlaterGPU CONFIG REQUIRED)
3. Delete the workaround block
4. Link SlaterGPU::SlaterGPU, SlaterGPU::io, SlaterGPU::cintw directly

Implications for the rest of the plan

• No change to scope: still three potential PRs (ZEST cleanup, XCtera cleanup, conditional SlaterGPU shim).
• DO_GTO=OFF observation still stands: ZEST's headers unconditionally #include \"cintwrapper.h\", so DO_GTO=OFF was never actually supported.
• Cint-bypass observation still stands: the workaround links raw find_library paths, silently bypassing IMPORTED_LINK_DEPENDENT_LIBRARIES_RELEASE. Switching to CONFIG mode + direct target links restores intended wiring.
• Debug-consumer probe is still required before deciding whether SlaterGPU needs the MAP_IMPORTED_CONFIG_* shim. Once we actually use the SHARED imported targets (which we don't today), Debug consumers may hit the IMPORTED_LOCATION_DEBUG gap that the Phase-1 hypothesis described — now as a future risk rather than a historical explanation.

Proceeding to step 2 (scratch-branch probe of the actual fix in Release).

[joshkamm]

Status update: diagnosis was partially wrong; PRs filed

The empirical probe (clean-build ZEST against current SlaterGPU, then probe-removal of the workaround) surfaced a different root cause than the original plan comment hypothesized. The workaround was actually masking two distinct bugs:

1. ZEST/XCtera shadow CONFIG mode with a hand-rolled find module

Both ZEST/cmake/FindSlaterGPU.cmake and XCtera/cmake/FindSlaterGPU.cmake existed. Without the CONFIG keyword, CMake's default find_package search order picks up Find<pkg>.cmake from CMAKE_MODULE_PATH before falling through to <pkg>Config.cmake. The hand-rolled modules only declared SlaterGPU::SlaterGPU (the static archive), so SlaterGPU::io and SlaterGPU::cintw were undefined — which is why the workaround had to find_library them.

Direct evidence from the step-1 capture:

CMake Warning at CMakeLists.txt:68 (message):
  SlaterGPU::io target not found
CMake Warning at CMakeLists.txt:90 (message):
  SlaterGPU::cintw target not found

The original plan's Debug-build and DO_GTO hypotheses were both wrong. The diagnostic shotgunning was shotgunning, but for a much simpler reason: the targets just didn't exist at all.

2. SlaterGPUConfig.cmake.in has a broken consumer-side libcint probe

Once we deleted the shadow modules and forced CONFIG mode, a second failure surfaced:

-- Checking for module 'libcint>=5.3.0'
--   No package 'libcint' found
CMake Error at FindPkgConfig.cmake (... SlaterGPUConfig.cmake:25 (pkg_check_modules) ...)

The pkg_check_modules(LIBCINT REQUIRED libcint>=5.3.0) call had no functional value (its LIBCINT_* output vars were never wired into SlaterGPU_LIBRARIES or any target), and it broke in pixi consumer environments where libcint isn't on pkg-config path. libcint is already carried transitively via IMPORTED_LINK_DEPENDENT_LIBRARIES_RELEASE → SlaterGPU::cint (auto-promoted during install(EXPORT)).

Filed PRs

1. Drop consumer-side libcint pkg-config probe from Config.cmake.in #92 (this repo) — drop the consumer-side libcint pkg-config probe from SlaterGPUConfig.cmake.in. Must merge first.
2. ZimmermanGroup/ZEST#93 — delete cmake/FindSlaterGPU.cmake, delete the ~74-line workaround, link imported targets directly. Net: -135/+2.
3. ZimmermanGroup/XCtera#16 — same shape as ZEST. Net: -49/+2.

Verification

• Release: pixi build of ZEST and XCtera both clean against Drop consumer-side libcint pkg-config probe from Config.cmake.in #92; ldd shows full transitive chain (libio.so, libcintw.so, libcint.so.5)
• Debug: cmake -DCMAKE_BUILD_TYPE=Debug configure of ZEST against Drop consumer-side libcint pkg-config probe from Config.cmake.in #92 produces a clean link.txt with all four artifacts via IMPORTED_CONFIGURATIONS auto-fallback. No MAP_IMPORTED_CONFIG_* shim needed, contrary to the original plan.

Closing this issue once all three PRs merge.

Latent bug worth a follow-up issue

Linking the raw find_library paths on the workaround's conditional branch (rather than the imported targets) silently bypassed CMake's IMPORTED_LINK_DEPENDENT_LIBRARIES_RELEASE chain. The cint transitive link was surviving only via libcintw.so's own DT_NEEDED — a build-time accident, not a CMake-intended dependency. Linking the imported targets directly restores the intended wiring. So removal is a fix, not just cleanup.

[joshkamm]

Closing — all three PRs merged:

• SlaterGPU#92 — drop consumer-side libcint pkg-config probe
• ZimmermanGroup/ZEST#93 — delete cmake/FindSlaterGPU.cmake + workaround block (-135/+2)
• ZimmermanGroup/XCtera#16 — mirror of ZEST cleanup (-49/+2)

End-to-end verification: CI green on all three (both Release CPU and GPU configurations); local Debug-consumer probe confirmed IMPORTED_CONFIGURATIONS auto-fallback works without a MAP_IMPORTED_CONFIG_* shim. See the diagnosis-correction comment for full details on the two distinct bugs the workaround had been masking.