Policy JSON schema

A policy is the input that turns a universe of parsed easyconfig candidates into one selection. It is a JSON object matching the Policy struct in src/domain.rs.

1 Full shape

{
  "toolchain": {"name": "foss", "version": "2025b"},
  "roots": ["GROMACS"],
  "root_priority": ["GROMACS"],
  "pins": [
    {"name": "OpenBLAS", "version_req": "==0.3.24"}
  ],
  "forbid": ["OpenMPI-4.1.5-foss-2025b.eb"],
  "objective": "prefer_newer",
  "require_upgrade": {"name": "GROMACS", "relative_to_baseline": true}
}

Only toolchain and roots are required; every other field defaults as noted below.

2 Fields

toolchain

{"name": string, "version": string}. Required. Selects which candidates from the parsed tree participate: the policy toolchain, every member of its hierarchy, and SYSTEM. A recipe at GCC takes CMake from GCCcore and a licence file from SYSTEM, so an exact match on the policy toolchain alone cannot satisfy its own dependencies.

roots

Array of package names. Required, non-empty. Every dependency (runtime and build-time) a root needs co-selects automatically; the solve fails if any named root has no candidate at all.

root_priority

Optional array of package names. Declares which root wins the newest-version tie-break when two or more roots share a dependency with conflicting requirements. Defaults to roots list order when omitted or empty. Any root missing from an explicit root_priority is appended in roots order, so every root always participates. Reordering roots does not change the effective priority once root_priority is set explicitly. See the how-to and why this exists.

pins

Optional array of {"name": string, "version_req": string}. Restricts a package to candidates whose version matches the requirement string (grammar below). A pin on a package with no matching candidate fails the solve at policy-construction time, before any Boolean satisfiability (SAT) solving happens. A pin on a package the trees have only outside the policy toolchain’s hierarchy fails the same way, and the message names the toolchains the trees have it on.

forbid

Optional array of strings. Each entry matches either a full easyconfig_path or a bare package name; matching candidates are excluded from the universe entirely before solving.

prefer_installed

Optional bool, default false. When true, a package present in the baseline stays at that version unless a pin, a forbid, or require_upgrade says otherwise. The derived criteria are then ["-changed", "-notuptodate"]: staying put outranks moving to newest.

objective

Optional string, default "prefer_newer". The only objective the solver implements: among jointly feasible assignments, prefer the newest version of each root (in priority order), then the newest version of every other co-selected package.

criteria

Optional array of Common Upgradeability Description Format (CUDF) criterion names, in precedence order. Empty means derive them: ["-notuptodate"] by default, or ["-changed", "-notuptodate"] when prefer_installed is true. An explicit list wins. Known names are -changed (minimise packages moved off the baseline version) and -notuptodate (minimise packages held below the newest candidate). Any other name fails the solve. The applied list is recorded on the lock as solver.criteria.

require_upgrade

Optional {"name": string, "relative_to_baseline": bool}, or an array of those objects. When relative_to_baseline is true, the named package’s solved version must be strictly newer than its version in the baseline lock (--baseline-easyconfigs or --baseline-easystack). No baseline, or no baseline entry for that package, fails the solve with an explicit error instead of skipping the requirement without a warning.

3 versionreqgrammar

Used by both pins[].version_req and parsed easyconfig dependency requirements (==X, >=X, <=X, >X, <X, or a bare X for an exact match). Version comparison is EasyBuild-shaped, not semver: digit runs compare numerically, letter runs compare lexicographically, and a trailing letter run with nothing on the other side sorts as a pre-release (2025a < 2025b, 1.0rc1 < 1.0).

4 Effective root priority

def effective_root_priority(policy):
    order = policy.root_priority or policy.roots
    order = [r for r in order if r in policy.roots]     # only real roots
    for r in policy.roots:
        if r not in order:
            order.append(r)                             # never drop a root
    return order

This is a description of Policy::effective_root_priority in src/domain.rs, not a separate implementation; it is shown here because the outcome of a multi-root solve depends entirely on this order.

5 Where policies are consumed

  • eb-stack stack solve --stack-policy POLICY.json

See how to solve a consistent stack lock.