chapar-buildcache

name	chapar-buildcache
description	Modify or debug Chapar buildcache or shared ccache behavior, migration, quarantine, index refresh, and cache publication for hpcsim or future Spack environments. Use for docs/buildcache.md, ci/push-buildcache.sh, release helper migration, or buildcache CI failures.

Chapar Buildcache

Use this playbook for ${CHAPAR_BUILDCACHE_ROOT}/<os>, ${CHAPAR_CCACHE_ROOT}/<os>, and cache logic used by Chapar Spack environments. The current release-helper implementation is hpcsim-specific, but the cache policy is project-wide and should remain usable by future environments.

Non-Negotiable Policy

• Do not make normal release/build workflows auto-import legacy buildcaches.
• Legacy migration must be explicit and one-shot only. Today that command is envs/hpcsim/release.sh migrate-buildcache for hpcsim.
• Do not delete legacy caches during migration.
• Do not overwrite destination payloads during migration.
• Unmarked or incompatible cache payloads must be quarantined before normal builds use the cache.
• Keep layout marker checks aligned with INSTALL_TREE_PADDED_LENGTH and BUILDCACHE_LAYOUT_VERSION where those helpers are used.
• Preserve per-OS cache roots; do not cross-copy Rocky 9/Rocky 10 caches unless explicitly validated by the user.
• Future environments should reuse the per-OS Chapar cache and ccache roots unless the user explicitly designs a separate cache namespace.
• Site-specific cache paths, groups, and publication policy belong in ignored envs/hpcsim/hpcsim-site.env, not tracked YAML.

Key Files

docs/buildcache.md
envs/hpcsim/release.sh              # current hpcsim release/cache helper
ci/push-buildcache.sh
.github/workflows/incus-spack-build.yml
etc/system/rocky9/mirrors.yaml
etc/system/rocky10/mirrors.yaml
envs/hpcsim/hpcsim-site.env.example

For future environments, inspect their workflow/build helper before assuming the hpcsim paths or variable names apply.

Inspection Commands

source ./etc/init.sh
ENV_PATH=envs/hpcsim        # or envs/<future-env>
spack mirror list
spack config blame mirrors
spack -e "${ENV_PATH}" config blame mirrors

For hpcsim release-helper cache status:

OS_NAME=rocky9 bash envs/hpcsim/release.sh status

Index and Payload Checks

A cache with payloads but no index is invisible to Spack reuse. Build helpers should refresh indexes before concretization when needed.

Do not run destructive cache cleanup. If cleanup is requested, require explicit confirmation and document what will be removed.

Validation

bash -n envs/hpcsim/release.sh
bash -n ci/push-buildcache.sh
git diff --check

If the change targets a future environment helper, validate that helper with bash -n as well.

If documentation is updated with behavior changes, keep docs in the same commit only when they explain the behavior change; otherwise split commits with chapar-commit.