KernelId

Enum KernelId 

Source
pub enum KernelId {
    Path(PathBuf),
    Version(String),
    CacheKey(String),
    Range {
        start: String,
        end: String,
        syntax_inclusive: bool,
    },
    Git {
        url: String,
        git_ref: String,
        ref_kind: GitRefKind,
    },
    Package {
        path: PathBuf,
    },
    Distro {
        kind: DistroKind,
        release: Option<String>,
    },
}
Expand description

Kernel identifier: filesystem path, version string, cache key, stable-release range, or git source.

Parsing heuristic (see KernelId::parse):

Variants§

§

Path(PathBuf)

Filesystem path to kernel source/build directory.

§

Version(String)

Kernel version string (e.g. “6.14.2”, “6.15-rc3”).

§

CacheKey(String)

Cache key (e.g. “6.14.2-tarball-x86_64-kc…”).

§

Range

Inclusive range of stable kernel versions, expanded against kernel.org’s release index at resolve time. start and end are both KernelId::Version-shaped strings (e.g. “6.10”, “6.13”); the resolver fans this out to every release in [start, end] inclusive on both endpoints regardless of whether the parser saw .. or ..=. A version present in the range but missing from the upstream index is a hard error before any boot — partial expansions are not silently dropped. The syntax_inclusive flag preserves the original separator for round-trip std::fmt::Display and operator-facing error messages; it does not change resolution semantics.

Fields

§start: String

Inclusive lower bound, version-shaped.

§end: String

Inclusive upper bound, version-shaped.

§syntax_inclusive: bool

true when the parser saw ..= (or the construction site asked for it); false for the .. form. Both are resolved as inclusive ranges; the flag exists so std::fmt::Display and the inverted-range error message round-trip the operator’s typed form.

§

Git

Git source: acquire the source at git_ref per ref_kind (tag / branch / sha), chosen explicitly by the operator’s #tag= / #branch= / #sha= fragment — no DWIM. Stored verbatim by KernelId::parse with no remote contact. At cache-resolution time resolve_git_kernel obtains the peeled commit from the exact gix fetch’s single prepared ref-map, probes the content-addressed cache, and receives the pack only for the elected builder.

Acquisition is routed by host (see resolve_git_kernel / crate::fetch):

  • Tag and Branch use one uniform, kind-directed, depth-one in-process gix fetch on every host. Annotated tags peel to the commit while their selected tag object is retained.
  • An explicit immutable GitHub Sha uses its codeload snapshot. Sha is unsupported off GitHub because the remote generally does not allow fetching an unadvertised bare commit.

Fields

§url: String

Remote URL. Branches/tags are fetched verbatim through gix; an explicit GitHub SHA uses codeload.

§git_ref: String

The ref value after kind= (verbatim, no refs/ prefix) for Tag / Branch / Sha; the whole unrecognized fragment for Unknown. For ref_kind == Sha this is the 40-hex commit id.

§ref_kind: GitRefKind

Which git namespace git_ref names, from the explicit #tag= / #branch= / #sha= selector. Unknown marks a bare #REF or unrecognized selector that validate rejects.

§

Package

Local kernel package: an .rpm, .deb, or pacman .pkg.tar.zst file on disk, to be unpacked for its prebuilt kernel image and modules. Classified by KernelId::parse on the case-sensitive .rpm / .deb / .pkg.tar.zst suffix ahead of the path check, so ./foo.rpm, /abs/foo.deb, and a bare foo.rpm all land here rather than as KernelId::Path. The path is ~-expanded identically to the Path variant.

Fields

§path: PathBuf

Path to the .rpm / .deb / .pkg.tar.zst file.

§

Distro

Distro-provided prebuilt kernel: download a specific build for a named distribution and (optional) release. A bare distro name (fedora) leaves release None — the resolver picks the distro’s default; an explicit release (fedora-44, f44, ubuntu-24.04, amazonlinux-2023, al2023, steamos-3.8, gke-129) pins one. The release string’s grammar is distro-specific and enforced by KernelId::validate, not parse: a distro name with a malformed release parses to this variant and is rejected at validate time (mirroring the git arm’s parse/validate split), never silently demoted to KernelId::CacheKey.

Fields

§kind: DistroKind

Which distribution.

§release: Option<String>

Release identifier (e.g. “44”, “24.04”, “2023”), or None for the distro’s default.

Implementations§

Source§

impl KernelId

Source

pub fn parse(s: &str) -> Self

Parse a string into a kernel identifier.

Recognizes (in order):

  • git+-prefixed → KernelId::Git. ANY git+… string is a Git source (the git+ prefix takes precedence over the range and /-contains tests below), so a typo such as a missing #fragment never silently becomes a Path. The fragment selects the ref kind: #tag=NAME / #branch=NAME / #sha=<40-hex>; a missing/empty fragment or unrecognized selector yields GitRefKind::Unknown, and an empty URL an empty url — both of which KernelId::validate rejects with an actionable error rather than the resolver later reporting a confusing “path not found”.
  • .rpm/.deb/.pkg.tar.zst-suffixed → KernelId::Package. Checked ahead of the path test so ./foo.rpm, /abs/foo.deb, and a bare foo.rpm all classify as a package rather than a path.
  • START..=END or START..END where both endpoints are version-shaped → KernelId::Range. The endpoints are ALWAYS inclusive — both .. and ..= spellings produce a closed range, regardless of Rust’s exclusive-.. / inclusive-..= distinction. Both forms are accepted so test authors and CLI users can write whichever feels natural.
  • /-containing or ./~-prefixed → KernelId::Path.
  • Version-shaped → KernelId::Version.
  • A distro name (fedora / ubuntu / amazonlinux / steamos, an explicit-release NAME-REL, or shorthand f44 / al2023) → KernelId::Distro. The release grammar is checked by validate, not here — a malformed release still classifies as Distro (not CacheKey) so validate can reject it.
  • Anything else → KernelId::CacheKey.
Source

pub fn parse_list(s: &str) -> Vec<KernelId>

Parse a comma-separated list of kernel specs into a vector of identifiers. Empty entries are silently skipped (so trailing commas or repeated separators are forgiving). Each non-empty segment is fed through KernelId::parse verbatim — so parse_list("6.10,git+URL#branch=main,/srv/linux") returns three distinct variants. Deduplication is the resolver’s responsibility (after canonicalization to a cache key); this function preserves order and duplicates as written.

Source

pub fn validate(&self) -> Result<(), String>

Validate a parsed KernelId for resolve-time legality. Returns Err(message) when the identifier carries a structural problem the parser couldn’t catch on its own — currently:

  • KernelId::Range with start > end after numeric component-wise comparison. The parser cannot reject this at parse time because both endpoints are valid version strings in isolation; the inversion only surfaces when the two are compared.
  • KernelId::Git with an Unknown ref kind, an empty url/ref, or a #sha= that isn’t a full 40-hex id.
  • KernelId::Distro whose explicit release does not match the distro’s grammar (Fedora \d{2,3}, Ubuntu YY.MM, Amazon Linux \d{4}, SteamOS \d{1,2}.\d{1,2}). As with git, the parser defers the release check here so a malformed release classifies as Distro rather than silently becoming a CacheKey.

The remaining variants (Path, Version, CacheKey, Package) always return Ok(()) — this is a hook for per-variant invariants, not a general-purpose validator. Use Result<(), String> rather than anyhow::Result because this file is included from build.rs (see file header rule #1, no non-std imports outside cfg(test)).

Comparison semantics: each endpoint decomposes to a (major, minor, patch, rc) tuple where missing patch maps to 0 and missing -rc maps to u64::MAX so a release (6.10) sorts strictly above any pre-release (6.10-rc3) of the same major.minor.patch. Inverted ranges include 7.0..6.99, 6.10..6.5, 6.10..6.10-rc3 (release > rc), and 6.10-rc3..6.10-rc1. Equal endpoints (6.10..6.10) pass validation as a single-element range.

Trait Implementations§

Source§

impl Clone for KernelId

Source§

fn clone(&self) -> KernelId

Returns a duplicate of the value. Read more
1.0.0 · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for KernelId

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl Display for KernelId

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl PartialEq for KernelId

Source§

fn eq(&self, other: &KernelId) -> bool

Tests for self and other values to be equal, and is used by ==.
1.0.0 · Source§

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
Source§

impl Eq for KernelId

Source§

impl StructuralPartialEq for KernelId

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
§

impl<Q, K> Equivalent<K> for Q
where Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

§

fn equivalent(&self, key: &K) -> bool

Checks if this value is equivalent to the given key. Read more
§

impl<Q, K> Equivalent<K> for Q
where Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

§

fn equivalent(&self, key: &K) -> bool

Compare self to key and return true if they are equal.
§

impl<Q, K> Equivalent<K> for Q
where Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

§

fn equivalent(&self, key: &K) -> bool

Checks if this value is equivalent to the given key. Read more
§

impl<Q, K> Equivalent<K> for Q
where Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

§

fn equivalent(&self, key: &K) -> bool

Checks if this value is equivalent to the given key. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
§

impl<T> Pointable for T

§

const ALIGN: usize

The alignment of pointer.
§

type Init = T

The type for initializers.
§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
§

impl<T> PolicyExt for T
where T: ?Sized,

§

fn and<P, B, E>(self, other: P) -> And<T, P>
where T: Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns [Action::Follow] only if self and other return Action::Follow. Read more
§

fn or<P, B, E>(self, other: P) -> Or<T, P>
where T: Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns [Action::Follow] if either self or other returns Action::Follow. Read more
Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T> ToString for T
where T: Display + ?Sized,

Source§

fn to_string(&self) -> String

Converts the given value to a String. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

impl<T> MaybeSend for T
where T: Send,

§

impl<T> MaybeSend for T
where T: Send,