Enum KernelId 

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,
    },
}

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

Parsing heuristic (see KernelId::parse):

• Contains / (without a git+ prefix) or starts with . or ~: KernelId::Path
• Starts with git+: KernelId::Git (form git+URL#tag=NAME / git+URL#branch=NAME / git+URL#sha=<40-hex>)
• Contains .. between two version-shaped tokens: KernelId::Range (inclusive on both endpoints)
• Matches MAJOR.MINOR[.PATCH][-rcN]: KernelId::Version
• 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

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 resolves git_ref to its full commit hash (a kind-directed ls-remote) and probes the cache before fetching, so a re-run against an unchanged tip skips the download.

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

• GitHub (github.com/OWNER/REPO): a codeload tar.gz snapshot of the RESOLVED COMMIT (the ls-remote-resolved commit for a tag/branch, the sha itself for a sha) — no clone; the exact-commit snapshot matches the cache key even if a branch tip moves mid-resolve. A tag/branch whose ls-remote resolution fails falls back to the clone path below (like a non-GitHub source).
• Non-GitHub: a kind-directed shallow clone — Tag fetches refs/tags/{git_ref} (annotated tags peel to the commit), Branch fetches refs/heads/{git_ref}. Sha is unsupported off GitHub (gix cannot fetch a bare commit and the remote lacks allow-sha-in-want) and errors.

Fields

url: String

Remote URL (https or git@). GitHub sources are fetched from codeload; non-GitHub sources are shallow-cloned from here.

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.

Implementations

impl KernelId

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”.
• 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.
• Anything else → KernelId::CacheKey.

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.

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.

All other variants always return Ok(()) — this is a hook for future 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 Clone for KernelId

fn clone(&self) -> KernelId

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for KernelId

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

Formats the value using the given formatter.

impl Display for KernelId

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

Formats the value using the given formatter.

impl PartialEq for KernelId

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

Tests for self and other values to be equal, and is used by ==.

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

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

impl Eq for KernelId

impl StructuralPartialEq for KernelId