mod domain

module domain

Domain types for EasyBuild stack selection.

Variables

const STACK_LOCK_SCHEMA_VERSION: u32

Schema version written into every StackLock.

Functions

fn install_version_stem(versionprefix: Option<&str>, version: &str) -> String

EasyBuild install stem from a prefix and bare version.

fn solver_timestamp() -> String

RFC 3339 time written into a lock.

SOURCE_DATE_EPOCH, when it is a decimal number of seconds since the Unix epoch, is that time in UTC. Two solves of the same inputs then write the same timestamp. Anything else, including an empty or non-numeric value, is the current time.

Enums

enum Criterion

One optimisation criterion, applied in order until it decides.

Package selection is an optimisation problem, not a satisfaction problem: many assignments satisfy the constraints and the interesting question is which one a stated preference picks. Stating that preference as an ordered list is the design the package-solving literature settled on, in OPIUM (doi:10.1109/icse.2007.59), apt-pbo (doi:10.1145/1858996.1859087) and the CUDF criteria the MISC competitions ran on, and it is what Spack encodes declaratively (doi:10.1109/sc41404.2022.00040).

The spelling is CUDF’s, -name for “minimise the count of”, because the vocabulary is already understood and inventing another one buys nothing. eb-stack has two axes, which is exactly the point at which an unordered pair of booleans stops saying what it means.

MinimiseChanged

Minimise packages moved off the version the baseline already installed. A rebuild nobody asked for costs hours of a partition.

MinimiseNotUptodate

Minimise packages held below the newest candidate available to them.

Implementations

impl Criterion

Functions

fn as_str(self) -> &'static str

The CUDF spelling, which is what the lock records.

fn parse(spelling: &str) -> Result<Self, String>

Parse the CUDF spelling. Unknown criteria are refused rather than ignored: a criterion silently dropped is a solve optimising for something other than what the policy asked for.

Traits implemented

impl std::fmt::Display for Criterion

Structs and Unions

struct Candidate

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

Identity is name, version, versionprefix, toolchain and versionsuffix together; two easyconfigs differing in any of those are separate candidates. version is the upstream bare version from the recipe; the EasyBuild install stem is Candidate::install_version_stem and is never folded back into version.

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.

versionprefix: Option<String>

EasyBuild versionprefix. None when the recipe sets none (or empty). Old JSON without this field deserializes as 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.

easyblock: Option<String>

Easyblock class the recipe names. None means EasyBuild derives EB_<name> and refuses to start when that class is not installed.

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 install_version_stem(&self) -> String

EasyBuild install stem: versionprefix + bare version.

Pure field projection used by module keys, filenames, robot full versions, and dependency matching. Does not mutate Self::version, which stays the upstream bare recipe version for SBOM and metadata.

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.

criteria: Vec<String>

Optimisation criteria in precedence order, CUDF spelling. Empty means derive them from objective and prefer_installed, which is what every policy written before this field did; see Policy::criteria.

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 criteria(&self) -> Vec<Criterion>

The criteria this policy optimises, in the order they are applied.

Explicit criteria wins. Otherwise they are derived, and the derivation is what the solver already did before the field existed: with prefer_installed, staying put outranks moving to the newest, because a candidate favoured for being installed is tried first and the solver takes the first that works. Without it, newest is the only preference expressed. So the default is not a new policy, it is the old one written down.

An unparseable criterion is dropped here rather than refused, because this is on the read path; Policy::validate_criteria is what a caller uses to reject a policy that names one.

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.

fn validate_criteria(&self) -> Result<(), String>

Error text for the first criterion this policy names that is not known, so a typo fails the solve instead of quietly changing what it optimises.

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.

criteria: Vec<String>

Optimisation criteria the solve applied, in precedence order, CUDF spelling. Recorded so a reader can see why this assignment beat another rather than only that it was reproducible. Empty in locks written before the field existed.

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 identity_label(&self) -> String

Identity label: system for SYSTEM/dummy, otherwise Self::label.

fn is_system(&self) -> bool

EasyBuild SYSTEM / historical dummy, regardless of version spelling.

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.