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):
- Starts with
git+:KernelId::Git(formgit+URL#tag=NAME/git+URL#branch=NAME/git+URL#sha=<40-hex>) - Ends with
.rpm,.deb, or.pkg.tar.zst:KernelId::Package - Contains
/(without agit+prefix) or starts with.or~:KernelId::Path - Contains
..between two version-shaped tokens:KernelId::Range(inclusive on both endpoints) - Matches
MAJOR.MINOR[.PATCH][-rcN]:KernelId::Version - A distro name (
fedora/ubuntu/amazonlinux/steamos/gke, an explicit-releaseNAME-REL, or shorthandf44/al2023):KernelId::Distro - Otherwise:
KernelId::CacheKey
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
syntax_inclusive: booltrue 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):
TagandBranchuse 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
Shauses its codeload snapshot.Shais unsupported off GitHub because the remote generally does not allow fetching an unadvertised bare commit.
Fields
url: StringRemote URL. Branches/tags are fetched verbatim through gix; an explicit GitHub SHA uses codeload.
git_ref: StringThe 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: GitRefKindWhich 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.
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: DistroKindWhich distribution.
Implementations§
Source§impl KernelId
impl KernelId
Sourcepub fn parse(s: &str) -> Self
pub fn parse(s: &str) -> Self
Parse a string into a kernel identifier.
Recognizes (in order):
git+-prefixed →KernelId::Git. ANYgit+…string is a Git source (thegit+prefix takes precedence over the range and/-contains tests below), so a typo such as a missing#fragmentnever silently becomes aPath. The fragment selects the ref kind:#tag=NAME/#branch=NAME/#sha=<40-hex>; a missing/empty fragment or unrecognized selector yieldsGitRefKind::Unknown, and an empty URL an emptyurl— both of whichKernelId::validaterejects 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 barefoo.rpmall classify as a package rather than a path.START..=ENDorSTART..ENDwhere 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-releaseNAME-REL, or shorthandf44/al2023) →KernelId::Distro. The release grammar is checked byvalidate, not here — a malformed release still classifies asDistro(notCacheKey) sovalidatecan reject it. - Anything else →
KernelId::CacheKey.
Sourcepub fn parse_list(s: &str) -> Vec<KernelId>
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.
Sourcepub fn validate(&self) -> Result<(), String>
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::Rangewithstart > endafter 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::Gitwith anUnknownref kind, an empty url/ref, or a#sha=that isn’t a full 40-hex id.KernelId::Distrowhose explicit release does not match the distro’s grammar (Fedora\d{2,3}, UbuntuYY.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 asDistrorather than silently becoming aCacheKey.
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§
impl Eq for KernelId
impl StructuralPartialEq for KernelId
Auto Trait Implementations§
impl Freeze for KernelId
impl RefUnwindSafe for KernelId
impl Send for KernelId
impl Sync for KernelId
impl Unpin for KernelId
impl UnwindSafe for KernelId
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
key and return true if they are equal.§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
§impl<T> Instrument for T
impl<T> Instrument for T
§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self>
fn into_either(self, into_left: bool) -> Either<Self, Self>
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 moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
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