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,
-namefor “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
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.
versionis the upstream bare version from the recipe; the EasyBuild install stem isCandidate::install_version_stemand is never folded back intoversion.- name: String¶
Package name.
- version: String¶
Package version.
- versionsuffix: Option<String>¶
Suffix distinguishing variants of one version, e.g.
-CUDA-12.6.0.Nonewhen the easyconfig sets none.
- versionprefix: Option<String>¶
EasyBuild
versionprefix.Nonewhen the recipe sets none (or empty). Old JSON without this field deserializes asNone.
- easyconfig_path: String¶
Path the candidate was parsed from. Empty for an in-memory parse.
- builddependencies: Vec<DepReq>¶
Build-time-only requirements (
builddependenciesin the easyconfig). SameDepReqsemantics as runtimedependencies; kept separate so lock/SBOM/serialized outputs can distinguish build vs runtime roles.
- easyblock: Option<String>¶
Easyblock class the recipe names.
Nonemeans 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+ bareversion.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)safter resolve). When set, selection treats it as part of the requirement identity.
- 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.
- 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.
- 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::rootslist order. Explicit priority is independent of reorderingrootsin 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.
- forbid: Vec<String>¶
Package names the solve must not select at any version.
- objective: String¶
Optimisation objective.
prefer_newerwhen 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
objectiveandprefer_installed, which is what every policy written before this field did; seePolicy::criteria.
- require_upgrade: Vec<RequireUpgrade>¶
Packages that must be strictly newer than baseline (when
relative_to_baselineis 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
criteriawins. Otherwise they are derived, and the derivation is what the solver already did before the field existed: withprefer_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_criteriais what a caller uses to reject a policy that names one.
- fn effective_root_priority(&self) -> Vec<String>¶
Effective root priority: explicit
root_prioritywhen non-empty, otherwiserootsorder. Any root missing from the priority list is appended inrootsorder 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
namemust 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.
- 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, orNonewhen 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 EasyBuildSYSTEMtoolchain appears here assystem.
- version: String¶
Generation string, e.g.
2026.1.systemfor the system toolchain.
Implementations
- impl Toolchain¶
Functions
- fn identity_label(&self) -> String¶
Identity label:
systemfor SYSTEM/dummy, otherwiseSelf::label.
- fn is_system(&self) -> bool¶
EasyBuild
SYSTEM/ historicaldummy, regardless of version spelling.
- fn label(&self) -> String¶
name-version, the form used in easyconfig filenames and messages.