Enum KernelCommand 

pub enum KernelCommand {
    List {
        json: bool,
        kernel: Option<String>,
        include_eol: bool,
    },
    Build {
        kernel: Option<String>,
        force: bool,
        clean: bool,
        cpu_cap: Option<usize>,
        extra_kconfig: Option<PathBuf>,
        skip_sha256: bool,
        include_eol: bool,
    },
    Clean {
        keep: Option<usize>,
        force: bool,
        corrupt_only: bool,
    },
}

Shared kernel subcommand tree used by both ktstr and cargo ktstr. The two binaries embed this as ktstr kernel <subcmd> / cargo ktstr kernel <subcmd> and dispatch identically; defining the variants once means a new kernel subcommand (or a flag change) lands in both surfaces by construction.

Variants

List

List cached kernel images, or preview a range expansion without downloading or building.

Default mode (no --kernel): walks the local cache and reports every cached kernel image. --kernel START..END switches to PREVIEW mode: fetches kernel.org’s releases.json, expands the inclusive range against the stable / longterm releases, and prints the resulting version list. Preview mode performs no downloads or builds and ignores the local cache — operators can use it to answer “what does --kernel 6.12..6.16 actually cover?” before paying the network or cache-store cost of a real resolve.

Fields

json: bool

Output in JSON format for CI scripting.

kernel: Option<String>

Range to PREVIEW. When supplied, switches the subcommand from “list cached kernels” to “fetch releases.json and print the versions a START..END range expands to.” Format: MAJOR.MINOR[.PATCH][-rcN]..MAJOR.MINOR[.PATCH][-rcN], matching crate::kernel_path::KernelId::Range. Example: --kernel 6.12..6.14 → every stable/longterm release in [6.12, 6.14] inclusive. A non-range --kernel (a single version, path, or git source) is rejected — preview mode expands ranges only; to inspect a cached single kernel run kernel list without --kernel.

In preview mode the subcommand performs no cache reads or kernel.org tarball downloads — only the single releases.json fetch that crate::cli::expand_kernel_range already runs for real range resolves. --json (when also supplied) emits a JSON object with the literal range string and the expanded version array; without --json the versions are written one per line to stdout for shell pipelines.

include_eol: bool

See INCLUDE_EOL_HELP. Only affects a --kernel range preview; ignored in the default cache-listing mode (which reads no releases.json and enumerates no series).

Build

Download, build, and cache a kernel image.

Fields

kernel: Option<String>

Kernel to build (the unified --kernel grammar). Omitted, builds the latest stable release. See KERNEL_HELP_BUILD for the accepted shapes.

force: bool

Rebuild even if a cached image exists.

clean: bool

Run make mrproper before configuring. Only meaningful for a --kernel <path> source tree: version / range / git sources build from a fresh tarball or clone, so this flag prints a notice and is ignored for them.

cpu_cap: Option<usize>

extra_kconfig: Option<PathBuf>

Path to an additional kconfig fragment merged on top of the baked-in ktstr.kconfig.

Format

One declaration per line, same shapes the kernel itself uses:

# comment lines start with `#` and a space
CONFIG_FOO=y                  # boolean enable
CONFIG_FOO=m                  # build as module
CONFIG_FOO=n                  # disable (equivalent to is-not-set)
CONFIG_BAR="some value"       # string
CONFIG_BAR=42                 # integer / hex
# CONFIG_FOO is not set       # explicit disable directive

The baked-in fragment lives at ktstr.kconfig in the ktstr repository root. See EMBEDDED_KCONFIG for the const that loads it at compile time.

Conflict resolution

User values win on conflict — kbuild’s .config parser (scripts/kconfig/confdata.c::conf_read_simple) emits “override: reassigning to symbol X” and keeps the last-occurring assignment, so appending the user fragment AFTER the baked-in fragment makes user values take precedence. Non-conflicting user lines combine with the baked-in set verbatim.

Override warnings: kernel build emits one tracing::warn! per user line that overrides a baked-in symbol (format: “–extra-kconfig overrides baked-in CONFIG_FOO (was =y, now =n)”). The build proceeds; the warning lets the operator see they are shadowing a baked-in setting before make olddefconfig runs.

Dependency resolution

make olddefconfig runs after the merge to resolve any added symbols’ dependencies. Options whose deps are not met land as # CONFIG_X is not set in the final .config; those silent drops surface as tracing::warn! lines (not errors) so the operator sees the diagnostic without the build failing.

Critical-symbol protection

After build, super::validate_kernel_config rejects entries that disabled symbols required by ktstr (CONFIG_BPF_SYSCALL, CONFIG_DEBUG_INFO_BTF, CONFIG_FTRACE, CONFIG_SCHED_CLASS_EXT, etc.). The error names --extra-kconfig as the likely cause when extras were supplied. So a fragment with # CONFIG_BPF is not set will fail validate_kernel_config post-build with an actionable message — the override warning fires pre-build and the validation error fires post-build, giving the operator two chances to catch a fatal override.

Caching

The cache key suffix grows from kc{baked} to kc{baked}-xkc{extra} when extras are present (see crate::cache_key_suffix_with_extra). Two builds with distinct extra-kconfig content land at distinct cache entries (different content = cache miss; same content = cache hit on re-run). Builds with NO --extra-kconfig keep using the bare kc{baked} suffix, so existing cached kernels are not orphaned. An --extra-kconfig-built kernel is only addressable by a matching --extra-kconfig invocation or by an explicit --kernel <path> / KTSTR_KERNEL path — cargo ktstr test --kernel 6.14.2 (which doesn’t take --extra-kconfig) will not surface the extra-built artifact.

kernel list tags entries built with extras as (extra kconfig) so an operator can spot which cached kernels carry user modifications.

skip_sha256: bool

Skip SHA-256 verification of downloaded stable tarballs. Useful when cdn.kernel.org updates a tarball in-place (new point release reusing the same URL) and the sha256sums.asc manifest is stale or mismatched. Only affects a version / range --kernel (the tarball download): no effect on a --kernel <path> source tree (no download), a --kernel git+… source (no manifest), or RC tarballs (git.kernel.org dynamically generates RC archives and publishes no upstream manifest, so RC downloads always run unverified regardless of this flag). Bypassing verification is security-sensitive: a single --skip-sha256: bypassing checksum verification warning fires per affected download so the lost guarantee is visible alongside the verification-success line that would otherwise appear.

include_eol: bool

See INCLUDE_EOL_HELP. Only affects a --kernel START..END range (e.g. kernel build --kernel 6.11..6.14); ignored for a single version, path, or git source, none of which expand a range.

Clean

Remove cached kernel images.

Fields

keep: Option<usize>

Keep the N most recent VALID cached kernels. When absent, removes every valid entry. Corrupt entries are always candidates for removal regardless of this value — they waste disk space and serve no build — so a corrupt entry never consumes a keep slot.

force: bool

Skip the y/N confirmation prompt before deleting. Always required in non-interactive contexts: without --force the command bails on a non-tty stdin rather than hang waiting for input. In an interactive shell, omit --force to be prompted.

corrupt_only: bool

Remove only corrupt cache entries (metadata missing or unparseable, image file absent). Valid entries are left untouched regardless of --force. Useful for clearing broken entries after an interrupted build without risking the curated set of good kernels. Mutually exclusive with --keep: --corrupt-only never touches valid entries, so a keep budget would silently be ignored; rejecting at parse time surfaces the misunderstanding instead.

Trait Implementations

impl Debug for KernelCommand

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

Formats the value using the given formatter.

impl FromArgMatches for KernelCommand

fn from_arg_matches(__clap_arg_matches: &ArgMatches) -> Result<Self, Error>

Instantiate Self from [ArgMatches], parsing the arguments as needed.

fn from_arg_matches_mut( __clap_arg_matches: &mut ArgMatches, ) -> Result<Self, Error>

Instantiate Self from [ArgMatches], parsing the arguments as needed.

fn update_from_arg_matches( &mut self, __clap_arg_matches: &ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

fn update_from_arg_matches_mut<'b>( &mut self, __clap_arg_matches: &mut ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

impl Subcommand for KernelCommand

fn augment_subcommands<'b>(__clap_app: Command) -> Command

Append to [Command] so it can instantiate Self via [FromArgMatches::from_arg_matches_mut]

fn augment_subcommands_for_update<'b>(__clap_app: Command) -> Command

Append to [Command] so it can instantiate self via [FromArgMatches::update_from_arg_matches_mut]

fn has_subcommand(__clap_name: &str) -> bool

Test whether Self can parse a specific subcommand