`mod package`¶

module package¶

Canonical package artifacts shared by foreign imports, bumps, solving, and EasyBuild emission.

Variables

const PACKAGE_SCHEMA_VERSION: u32¶: Schema version of a package plan document.

const PROFILE_LOCK_SCHEMA_VERSION: u32¶: Schema version of a per-profile dependency lock.

const STACK_POLICY_SCHEMA_VERSION: u32¶: Schema version of a stack policy document.

Functions

fn materialize_profile(plan: &PackagePlan, profile_name: &str, environment: &ProfileEnvironment) -> Result<MaterializedProfile, PackageError>¶

Resolve one profile’s conditions against an environment.

Every conditional dependency, source and rule is evaluated, so the result describes exactly what will be built. Fails when the profile does not exist rather than falling back to the default.

fn package_plan_to_bom(plan: &PackagePlan) -> Result<Bom, PackageError>¶

Build a CycloneDX BOM describing what the plan intends to install.

This records intent. It is not evidence of what a build produced, and it carries a checksum only where the plan had one.

fn package_plan_to_cyclonedx(plan: &PackagePlan) -> Result<Value, PackageError>¶: The planned BOM as JSON.

Enums

enum ConditionExpr¶

A condition gating a dependency, source, or rule.

Foreign selectors are lowered into this tree so they can be evaluated per profile. Anything that could not be lowered becomes Self::Opaque rather than being dropped or guessed at.

Always¶: Always true, the default for an unconditional item.

Never¶: Never true, which excludes the item entirely.

Predicate(ConditionPredicate)¶: A single predicate.

All(Vec<ConditionExpr>)¶: True when every branch is.

Any(Vec<ConditionExpr>)¶: True when any branch is.

Not(Box<ConditionExpr>)¶: Negation.

Opaque¶

A selector that could not be lowered. Preserved verbatim so a reviewer sees what was not understood instead of a silent drop.

source: String¶: The selector text as written.

Implementations

impl ConditionExpr¶

Functions

fn evaluate(&self, context: &ConditionContext) -> bool¶: Whether this condition holds in context.

fn specialize_package_version(&self, package_version: &str) -> Self¶: Resolve package-version predicates while preserving conditions that depend on a profile, toolchain, platform, or dependency selection.

enum ConditionPredicate¶

One testable fact about the build being configured.

PackageVersion¶

The package version satisfies a requirement.

requirement: String¶: Version requirement to test.

Feature¶

A profile feature flag has a given value.

name: String¶: Feature name.

enabled: bool¶: Value it must have.

DependencyFeature¶

A dependency was built with a feature flag set a given way.

dependency: String¶: Dependency carrying the flag.

name: String¶: Feature name.

enabled: bool¶: Value it must have.

Compiler¶

The compiler matches, optionally at a version.

name: String¶: Compiler name.

version: Option<String>¶: Version to match, or any version when absent.

Toolchain¶

The toolchain matches, optionally at a version.

name: String¶: Toolchain name.

version: Option<String>¶: Version to match, or any version when absent.

Platform¶

The target platform matches.

name: String¶: Platform name.

Architecture¶

The target architecture matches.

name: String¶: Architecture name.

VariableComparison¶

A context variable compares as stated.

left: String¶: Variable name or literal on the left.

operator: String¶: Comparison operator.

right: String¶: Value on the right.

Implementations

impl ConditionPredicate¶

enum Confidence¶

How sure the extractor is that it read a value correctly.

Exact¶: Read directly; no interpretation was involved.

Derived¶: Inferred from surrounding context, and worth a reviewer’s eye.

Ambiguous¶: Could not be resolved to one meaning. Treat as needing review.

enum DependencyRole¶

When a dependency is needed.

Build¶: Needed to build, not at run time.

Host¶: Needed on the build host, for a cross build.

Run¶: Needed at run time.

Test¶: Needed only to run the test suite.

enum EasyconfigValue¶

A value written verbatim into an easyconfig parameter.

Bool(bool)¶: A Python bool.

Integer(i64)¶: A Python int.

String(String)¶: A Python string.

List(Vec<EasyconfigValue>)¶: A Python list.

Concat(EasyconfigStringConcat)¶: A string built by concatenation.

Table(BTreeMap<String, EasyconfigValue>)¶: A Python dict.

enum PackageError¶

Why a package plan could not be read or rendered.

UnsupportedSchema(u32)¶: The plan declares a schema this build does not read.

ProfileNotFound(String)¶: The named profile is not in the plan.

Json(serde_json::Error)¶: The plan is not valid JSON, or does not match the schema.

CycloneDx(String)¶: The SBOM could not be serialized.

enum PackageOrigin¶

Ecosystem a package definition came from.

CondaForge¶: A conda-forge meta.yaml or recipe.yaml.

Spack¶: A Spack package.py.

EasyBuild¶: An EasyBuild easyconfig.

Pypi¶: Offline PyPI metadata or a requirements.txt.

Cran¶: A CRAN DESCRIPTION file or package list.

Cargo¶: A Cargo.toml or crates.io JSON document.

Luarocks¶: A LuaRocks rockspec.

Raku¶: A Raku META6.json.

enum PackageRuleKind¶

Whether a rule forbids a combination or demands one.

Conflict¶: The combination must not occur.

Requirement¶: The combination is required.

enum ResidualSeverity¶

How much attention a residual needs.

Mechanical¶: A mechanical gap; a tool could close it.

Judgment¶: Needs a human decision.

Blocking¶: Must be resolved before the result can be trusted.

enum ResidualStage¶

Which step of the pipeline left work behind.

Parse¶: Reading the foreign recipe.

Normalize¶: Lowering it into the canonical plan.

Resolve¶: Selecting dependencies.

Emit¶: Writing the easyconfig.

Build¶: Building the package.

Verify¶: Verifying the installed build.

enum StackPinMode¶

How strictly a stack pin binds the solve.

Preferred¶: Take this version when it is available, otherwise fall back and say so.

Locked¶: Take this version or fail; no fallback is acceptable.

Structs and Unions

struct BuildSpec¶

How the package is built, independent of profile.

toolchain: Toolchain¶: Toolchain the build targets.

easyblock: Option<String>¶: EasyBuild easyblock class.

build_systems: Vec<String>¶: Build systems detected or configured.

source_root: Option<String>¶: Subdirectory of the unpacked source to build from.

config_options: Vec<String>¶: Configure flags common to every profile.

moduleclass: Option<String>¶: EasyBuild moduleclass.

patches: Vec<PatchArtifact>¶: Patches applied before configuring.

easyconfig_parameters: BTreeMap<String, EasyconfigValue>¶: Raw easyconfig parameters written through verbatim.

struct CandidateExclusion¶

A candidate the solve must not choose, and why.

name: String¶: Package excluded.

version_requirement: String¶: Versions excluded, as a requirement expression.

reason: String¶: Why it is excluded. Recorded in the lock so a reader is not left guessing why an obvious candidate was skipped.

scope: Option<String>¶: Where the exclusion applies, when it is not global.

struct ConditionContext¶

What a condition is evaluated against for one profile.

package_version: String¶: Version of the package being built.

features: BTreeMap<String, bool>¶: Feature flags of the profile.

dependency_features: BTreeMap<String, BTreeMap<String, bool>>¶: Feature flags of each selected dependency.

compiler: Option<NamedVersion>¶: Compiler in use, when known.

toolchain: Option<Toolchain>¶: Toolchain in use, when known.

platform: Option<String>¶: Target platform, when known.

architecture: Option<String>¶: Target architecture, when known.

variables: BTreeMap<String, String>¶: Free-form variables a comparison predicate may reference.

struct DependencyIntent¶

One dependency the recipe declares, before any solve.

id: String¶: Stable identifier within the plan, so a rule can refer to it.

name: String¶: Name as the foreign recipe spells it.

eb_name: Option<String>¶: EasyBuild’s name for the same thing, when they differ.

constraint: Option<String>¶: Version requirement, or None for any version.

toolchain: Option<Toolchain>¶: Explicit EasyBuild dependency toolchain after generation retargeting. None keeps minimal-toolchain selection within the output hierarchy.

roles: Vec<DependencyRole>¶: When it is needed. Empty means the recipe never said.

condition: ConditionExpr¶: When this dependency applies. Defaults to always.

virtual_capability: Option<String>¶: Capability this satisfies, when it stands in for a virtual package.

solver_excluded: bool¶: True when the solve must skip it, because the toolchain already provides it.

provenance: Vec<Provenance>¶: Where this dependency was read from.

struct EasyconfigStringConcat¶

Python data values accepted by public EasyBuild package policy.

Expressions are deliberately absent: package configuration describes easyblock inputs without becoming an arbitrary Python execution surface. A value built by joining strings, kept in parts so they stay reviewable.

concat: Vec<String>¶: Fragments joined in order.

struct LockedDependency¶

One dependency as resolved into a lock.

name: String¶: Package name.

version: String¶: Version selected.

versionsuffix: Option<String>¶: Versionsuffix of the selected variant, when it has one.

toolchain: Toolchain¶: Toolchain the selected easyconfig builds against.

easyconfig_path: String¶: Easyconfig the selection came from.

build: bool¶: True for a build-time-only dependency, so a consumer can tell the runtime closure from the build closure.

struct MaterializedProfile¶

One profile with every condition resolved: what will actually be built.

package: PackageMetadata¶: Package identity and metadata.

build: BuildSpec¶: Build system and easyconfig parameters.

sources: Vec<SourceArtifact>¶: Source artifacts this profile downloads.

profile: ProductProfile¶: The profile this was materialized from.

versionsuffix: String¶: Concatenated versionsuffix for the emitted recipe.

dependencies: Vec<DependencyIntent>¶: Dependencies whose conditions held for this profile.

rules: Vec<PackageRule>¶: Rules whose conditions held for this profile.

struct NamedVersion¶

A name paired with a version, used where a full toolchain is too much.

name: String¶: Name, e.g. a compiler.

version: String¶: Version string.

struct OutputRequest¶

A request to emit one profile against one stack.

profile: String¶: Profile to emit.

stack: String¶: Stack policy to solve against.

struct OverlayExtension¶

One leftover PyPI package installed in the same PythonBundle as the root.

name: String¶: Extension name, as the ecosystem publishes it.

version: String¶: Exact version EasyBuild will download.

checksum: Option<String>¶: Checksum from the repository index, tagged with its algorithm.

struct PackageMetadata¶

Package identity as it will appear in the emitted recipe.

name: String¶: Package name, in EasyBuild’s spelling.

version: String¶: Version the emitted recipe declares.

upstream_version: Option<String>¶: Version identity used by the foreign recipe when it differs from the emitted EasyBuild version.

homepage: Option<String>¶: Project homepage.

description: Option<String>¶: Short description for the module.

license: Option<String>¶: License string, as the recipe declares it.

struct PackagePlan¶

The canonical description of a package: the shape every ingest lowers to and every emitter reads.

schema_version: u32¶: Must equal PACKAGE_SCHEMA_VERSION.

origin: PackageOrigin¶: Ecosystem the definition came from.

package: PackageMetadata¶: Package identity and metadata.

sources: Vec<SourceArtifact>¶: Artifacts the build downloads or checks out.

dependencies: Vec<DependencyIntent>¶: Dependencies declared, before any solve.

rules: Vec<PackageRule>¶: Constraints beyond the dependency list.

build: BuildSpec¶: How the package is built.

profiles: Vec<ProductProfile>¶: Build variants.

outputs: Vec<OutputRequest>¶: Profile and stack combinations to emit.

residuals: Vec<Residual>¶: Work left for a human, carried rather than dropped.

overlay_extensions: Vec<OverlayExtension>¶: Language run dependencies the robot does not ship. Emitted as extra exts_list entries on the leftover bundle, not as SAT holes.

package_index: std::collections::BTreeMap<String, crate::ecosystem::IndexEntry>¶: Package name to version for the ecosystem, when the caller supplied an index. A dependency written as a bare name is normal in CRAN and on PyPI, and an exts_list entry still needs one concrete version.

Implementations

impl PackagePlan¶

Functions

fn from_json_str(input: &str) -> Result<Self, PackageError>¶: Parse a plan from JSON and check its schema version.

fn validate_schema(&self) -> Result<(), PackageError>¶: Reject a plan whose schema this build does not read.

struct PackageRule¶

A constraint the recipe states beyond its dependency list.

id: String¶: Stable identifier within the plan.

kind: PackageRuleKind¶: Whether this forbids or requires.

spec: String¶: The combination, in the foreign recipe’s own spelling.

when: Option<String>¶: Original when= text, kept for review alongside the lowered form.

condition: ConditionExpr¶: When the rule applies, lowered from the selector.

message: Option<String>¶: Message to show when the rule fires.

provenance: Provenance¶: Where the rule was read from.

struct PatchArtifact¶

A patch the build applies.

filename: String¶: Filename EasyBuild references. A bare name, never a path.

sha256: Option<String>¶: SHA-256 of the patch bytes.

url: Option<String>¶: Exact remote patch URL accepted by EasyBuild’s patches parameter.

source: Option<String>¶: Local path to copy the patch from.

condition: ConditionExpr¶: When this patch applies.

resolved_source: Option<PathBuf>¶: Where the patch was found on disk, resolved relative to the layer that named it. Not serialized: it is a detail of this run.

struct ProductProfile¶

One build variant of the package.

name: String¶: Profile name, unique within the plan.

default: bool¶: Whether this is chosen when no profile is named. Exactly one profile must be the default.

versionsuffix: Vec<String>¶: Versionsuffix fragments, concatenated in order.

platform: Option<String>¶: Platform this profile is restricted to.

architecture: Option<String>¶: Architecture this profile is restricted to.

features: BTreeMap<String, bool>¶: Feature flags, which conditions test.

parameters: BTreeMap<String, String>¶: Free-form parameters conditions may reference.

toolchain_options: BTreeMap<String, bool>¶: EasyBuild toolchain options such as pic or openmp.

config_options: Vec<String>¶: Configure flags for this profile, on top of the build-level set.

easyconfig_parameters: BTreeMap<String, EasyconfigValue>¶: Raw easyconfig parameters for this profile.

verification_commands: Vec<VerificationCommand>¶: Commands proving this variant works.

struct ProfileEnvironment¶

The conditions a profile evaluates against.

dependency_features: BTreeMap<String, BTreeMap<String, bool>>¶: Feature flags per dependency, keyed by dependency then flag.

compiler: Option<NamedVersion>¶: Compiler in play, when a condition depends on it.

platform: Option<String>¶: Target platform, when a condition depends on it.

architecture: Option<String>¶: Target architecture, when a condition depends on it.

variables: BTreeMap<String, String>¶: Free-form variables conditions may test.

struct ProfileLock¶

The reproducible dependency selection for one profile.

schema_version: u32¶: Must equal PROFILE_LOCK_SCHEMA_VERSION.

package: String¶: Package this lock belongs to.

version: String¶: Package version.

profile: String¶: Profile name.

toolchain: Toolchain¶: Toolchain the profile targets.

versionsuffix: String¶: Versionsuffix of the emitted recipe.

dependencies: Vec<LockedDependency>¶: Every dependency selected, build and runtime alike.

pin_outcomes: Vec<StackPinOutcome>¶: What each policy pin achieved.

exclusions: Vec<CandidateExclusion>¶: Exclusions the policy applied.

solver: String¶: Solver that produced the lock.

struct Provenance¶

The trail from an extracted value back to the text it came from.

Carried so a reviewer can check a translated recipe against its source rather than trusting the extraction.

span: SourceSpan¶: Text the value was read from.

extractor: String¶: Which extractor produced it.

original: String¶: The original text, before any normalisation.

confidence: Confidence¶: How much the extractor trusts the reading.

struct Residual¶

Work the pipeline could not do mechanically, recorded rather than dropped so nothing is silently lost in translation.

id: String¶: Stable identifier within the plan.

stage: ResidualStage¶: Step that produced it.

category: String¶: Short machine-readable category.

severity: ResidualSeverity¶: How much attention it needs.

summary: String¶: One-line description for a reviewer.

evidence: Option<String>¶: Supporting text, such as the source that was not understood.

provenance: Option<Provenance>¶: Where in the recipe it arose.

struct SourceArtifact¶

One thing the build downloads or checks out.

A downloaded file carries url and sha256; a checkout carries git with a tag or commit. The two are alternatives, and a checkout has no artifact checksum to verify.

url: Option<String>¶: Download URL, for a fetched artifact.

filename: Option<String>¶: Local filename to save as, when it differs from the URL basename.

sha256: Option<String>¶: SHA-256 of the downloaded bytes. Only meaningful for a download, and only valid for the artifact class that URL serves.

git: Option<String>¶: Remote to clone, for a checkout instead of a download.

tag: Option<String>¶: Tag to check out.

commit: Option<String>¶: Commit to check out, which pins more tightly than a tag.

target_directory: Option<String>¶: Subdirectory to unpack into, when the build expects one.

condition: ConditionExpr¶: When this artifact applies. Defaults to always.

provenance: Vec<Provenance>¶: Where this artifact was read from.

struct SourceSpan¶

Where in a foreign recipe a value came from.

path: String¶: Recipe file, as given to the parser.

start_line: u32¶: First line of the span, 1-based.

start_column: u32¶: First column, 1-based.

end_line: u32¶: Last line of the span, 1-based.

end_column: u32¶: Last column, 1-based.

struct StackPin¶

A version constraint the site imposes on one dependency.

name: String¶: Package the pin applies to.

version_requirement: String¶: Version requirement, e.g. an exact version or a range.

toolchain: Option<Toolchain>¶: Restrict the pin to one toolchain. None matches any.

versionsuffix: Option<String>¶: Restrict the pin to one versionsuffix. None matches any.

mode: StackPinMode¶: Whether a fallback is permitted when the pin cannot be met.

source: Option<String>¶: Where the pin came from, carried through for auditability.

struct StackPinOutcome¶

What a pin actually achieved, recorded per solve.

name: String¶: Package the pin named.

requested: String¶: Version requirement as requested.

requested_toolchain: Option<Toolchain>¶: Toolchain requested, when the pin restricted one.

requested_versionsuffix: Option<String>¶: Versionsuffix requested, when the pin restricted one.

selected_version: Option<String>¶: Version chosen. None when nothing satisfied the pin.

selected_toolchain: Option<Toolchain>¶: Toolchain of the chosen candidate.

selected_versionsuffix: Option<String>¶: Versionsuffix of the chosen candidate.

fallback: bool¶: Whether the solve had to fall back off the pin. Only a Preferred pin can reach this; a Locked pin fails the solve instead.

fallback_reason: Option<String>¶: Why the fallback happened, when one did.

struct StackPolicy¶

Site rules a dependency solve must respect.

schema_version: u32¶: Must equal STACK_POLICY_SCHEMA_VERSION.

name: String¶: Policy name, for messages and provenance.

toolchain: Toolchain¶: Toolchain generation the policy governs.

pins: Vec<StackPin>¶: Version constraints imposed on individual packages.

exclusions: Vec<CandidateExclusion>¶: Candidates the solve must not choose.

struct StackPolicySolve¶

The result of applying a stack policy to a candidate set.

selected: Vec<Candidate>¶: Candidates the policy allows, after pins and exclusions.

pin_outcomes: Vec<StackPinOutcome>¶: One outcome per pin, including the ones that fell back.

exclusions: Vec<CandidateExclusion>¶: Exclusions that were applied, echoed for the lock.

struct VerificationCommand¶

A command that proves the installed build works.

program: String¶: Program to run.

args: Vec<String>¶: Arguments passed to it.

mod package¶

`mod package`¶