mod domain

module domain

Domain types for EasyBuild stack selection.

Structs and Unions

struct Candidate

One installable variant the solver may choose: a parsed easyconfig.

Identity is name, version, toolchain and versionsuffix together; two easyconfigs differing in any of those are separate candidates.

name: String

Package name.

version: String

Package version.

toolchain: Toolchain

Toolchain this variant builds against.

versionsuffix: Option<String>

Suffix distinguishing variants of one version, e.g. -CUDA-12.6.0. None when the easyconfig sets none.

easyconfig_path: String

Path the candidate was parsed from. Empty for an in-memory parse.

dependencies: Vec<DepReq>

Runtime requirements, which must also be installed.

builddependencies: Vec<DepReq>

Build-time-only requirements (builddependencies in the easyconfig). Same DepReq semantics as runtime dependencies; kept separate so lock/SBOM/serialized outputs can distinguish build vs runtime roles.

exts_list: Vec<ExtEntry>

Bundled extensions (exts_list) resolved from the easyconfig.

moduleclass: Option<String>

What the recipe says the module is for. Carried so a regenerated or retargeted recipe can keep the class the tree already gives a package, which upstream metadata cannot tell you: archspec and cppy state no topic at all and upstream classes both as tools.

Implementations

impl Candidate

Functions

fn extension_parent_name(&self) -> Option<&str>

Parent bundle name, taken from the single exact dependency.

fn extension_parent_path(&self) -> Option<&str>

Easyconfig path of the bundle that provides this extension.

fn is_extension_provide(&self) -> bool

Whether this candidate was generated from a parent exts_list.

struct DepReq

One dependency an easyconfig declares, after template resolution.

name: String

Package name required.

version_req: String

Version field as written: an exact version, or a range such as >=1.2. Not normalised, because the easyconfig’s own spelling is what a maintainer will look for.

versionsuffix: Option<String>

Optional versionsuffix on this dependency (e.g. -CUDA-%(cudaver)s after resolve). When set, selection treats it as part of the requirement identity.

toolchain: Option<Toolchain>

Per-dependency toolchain override (None = inherit the dependent’s toolchain). Includes EasyBuild SYSTEM → {name: "system", version: "system"}.

struct ExtEntry

One bundled extension entry from an easyconfig exts_list.

name: String

Extension name as listed in exts_list.

version: String

Extension version. Empty when the entry gave none.

struct LockPackage

One selected variant as recorded in a lock.

name: String

Package name.

version: String

Version selected.

toolchain: Toolchain

Toolchain the selected easyconfig builds against.

versionsuffix: Option<String>

Versionsuffix of the selected variant, when it has one.

easyconfig_path: String

Easyconfig the selection came from, so a lock can be traced back to a file. Empty when the candidate was parsed from memory.

struct Pin

A constraint fixing one package to a version or range.

name: String

Package the pin applies to.

version_req: String

Version requirement the selection must satisfy, same spelling rules as DepReq::version_req.

struct Policy

What a solve is asked to produce: target toolchain, roots, and constraints.

toolchain: Toolchain

Toolchain generation to select for.

roots: Vec<String>

Application roots the stack exists to provide. Everything else is pulled in only because a root needs it.

root_priority: Option<Vec<String>>

Declared priority order over application roots for multi-root lexicographic newest selection. When omitted or empty, defaults to Self::roots list order. Explicit priority is independent of reordering roots in the policy JSON.

prefer_installed: bool

Keep what the baseline already installed when nothing requires moving.

The default objective is newest-wins, which is right for planning a new generation and wrong for maintaining one: on a site where a rebuild costs hours of a GPU partition, a solve that moves a package nobody asked to move spends that time for nothing. With this set, a package present in the baseline lock is preferred at the version it already has, unless a pin, an exclusion or a require_upgrade says otherwise. Those all remain hard constraints; this only decides between candidates that were all valid anyway.

pins: Vec<Pin>

Version constraints applied on top of what the candidates allow.

forbid: Vec<String>

Package names the solve must not select at any version.

objective: String

Optimisation objective. prefer_newer when unset, which is the only value the shipped solver implements.

require_upgrade: Vec<RequireUpgrade>

Packages that must be strictly newer than baseline (when relative_to_baseline is true). Accepts a single object or an array in JSON for backward compatibility.

Implementations

impl Policy

Functions

fn effective_root_priority(&self) -> Vec<String>

Effective root priority: explicit root_priority when non-empty, otherwise roots order. Any root missing from the priority list is appended in roots order so every application root is optimized.

struct RequireUpgrade

A demand that a package move forward relative to the baseline lock.

name: String

Package that must advance.

relative_to_baseline: bool

When true, the selected version of name must be strictly newer than the baseline lock’s version. When false, construction fails with a clear error (absolute require_upgrade is not silently ignored).

struct SolverMeta

Provenance of a solve, so a lock says what produced it.

engine: String

Solver that produced the lock, e.g. resolvo.

engine_version: String

Version of that solver.

timestamp: String

When the solve ran, as an RFC 3339 timestamp.

struct StackLock

A complete, reproducible selection: every package a stack installs.

schema_version: u32

Schema version of this lock document. Readers reject what they do not know rather than guessing at an unfamiliar shape.

toolchain: Toolchain

Toolchain the stack targets.

generation_label: Option<String>

Generation label carried from the universe, when one was given.

packages: Vec<LockPackage>

Selected packages, sorted by name for a stable diff.

solver: SolverMeta

What produced this lock.

Implementations

impl StackLock

Functions

fn package(&self, name: &str) -> Option<&LockPackage>

The locked entry for name, or None when the stack has no such package.

struct Toolchain

An EasyBuild toolchain: the compiler and library generation a build targets.

name: String

Toolchain name as EasyBuild spells it, e.g. foss, GCCcore. The EasyBuild SYSTEM toolchain appears here as system.

version: String

Generation string, e.g. 2026.1. system for the system toolchain.

Implementations

impl Toolchain

Functions

fn label(&self) -> String

name-version, the form used in easyconfig filenames and messages.

struct Universe

The candidate set a solve draws from, scoped to one toolchain generation.

toolchain: Toolchain

Toolchain the solve targets.

generation_label: Option<String>

Human label for the generation, when the caller supplied one. Carried into the lock for provenance; it does not affect selection.

candidates: Vec<Candidate>

Every variant available to choose from.