Skip to main content

Crate cargo_kcfg

Crate cargo_kcfg 

Source
Expand description

§cargo-kcfg

Linux/Zephyr-style Kconfig for Rust crates.

Parse Kconfig definitions, load a *_defconfig, evaluate depends on / select / imply / choice / range, and emit typed CONFIG_* constants. An illegal configuration is a hard error: the tool does not silently repair user intent.

This package is the library, CLI, and optional build.rs helper. Firmware and application crates that only need constants should depend on cargo-kcfg-macros so nothing is compiled for the target.

§Installation

cargo install cargo-kcfg
cargo kcfg --help

The binary is named cargo-kcfg, so Cargo exposes it as a subcommand:

cargo kcfg check
cargo kcfg build
cargo kcfg test

Constants in your crate do not require the CLI. Use it to validate a tree or to write .config / config.rs by hand.

§Use in a crate

§1. Kconfig files

At the crate root (or the workspace root if you have several packages):

my-firmware/
  Cargo.toml
  Kconfig
  qemu_defconfig          # or configs/qemu_defconfig
  src/lib.rs
config FOO
	bool "Enable foo"
	default y

config BUFFER_SIZE
	int "Buffer size"
	range 1 4096
	default 128
	depends on FOO

config BOARD_NAME
	string "Board name"
	default "qemu"
# qemu_defconfig
CONFIG_FOO=y
CONFIG_BUFFER_SIZE=256
CONFIG_BOARD_NAME="qemu-virt"

The plugin looks for defconfig or exactly one *_defconfig in the project root and in configs/. Several matches are an error unless you name one:

KCONFIG_DEFCONFIG=qemu_defconfig cargo build
KCONFIG_DEFCONFIG=configs/prod_defconfig cargo build

Keep illegal assignment files out of that search (for example configs/cases/unmet_defconfig) so a cargo build cannot pick them up.

§2. Depend on the macros crate

No build.rs. The proc-macro runs on the host while your crate compiles, including no_std targets:

[dependencies]
cargo-kcfg-macros = "0.0.1"

§3. Include the generated constants

ⓘ
pub mod config {
    cargo_kcfg_macros::include_config!();
}

use config::*;

pub fn init() {
    if CONFIG_FOO {
        let _buf = [0u8; CONFIG_BUFFER_SIZE as usize];
        let _ = CONFIG_BOARD_NAME;
    }
}

include_config! finds Kconfig next to this package, or walks up to a parent directory that has both Cargo.toml and Kconfig. It then evaluates the unique defconfig (or KCONFIG_DEFCONFIG) and expands CONFIG_* items into that module.

Use the constants, not rustc cfg:

ⓘ
if CONFIG_FOO { /* ... */ }
if !CONFIG_FOO { /* ... */ }

// #[cfg(CONFIG_FOO)]  // not set — a proc-macro cannot emit cargo:rustc-cfg

§4. Workspace (several packages)

Cargo never runs a build.rs at a virtual workspace root. Member crates do not need one either.

my-product/
  Cargo.toml                 # [workspace] members = ["lib", "app"]
  Kconfig
  configs/qemu_defconfig
  lib/
    Cargo.toml               # cargo-kcfg-macros = "0.0.1"
    src/lib.rs               # pub mod config { include_config!(); }
  app/
    Cargo.toml               # depends on lib
    src/main.rs              # use my_lib::config::*;

lib owns the include. Other members depend on lib and write use my_lib::config::*;.

cargo test -p my-lib
cargo run -p my-app

§5. Check a tree from the CLI

cargo kcfg check
cargo kcfg build          # writes .config and config.rs next to the crate

--root / --kconfig / --defconfig override discovery. check does not write files. An unmet depends on, bad select, choice conflict, or out-of-range value prints a red error and exits 1.

§6. Unit tests with other (including illegal) defconfigs

The compile-time include still uses the product defconfig. Tests that need a different file, or a known-bad one, evaluate at runtime with ConfigTest:

[dependencies]
cargo-kcfg-macros = "0.0.1"

[dev-dependencies]
cargo-kcfg = "0.0.2"
use cargo_kcfg::domain::{IssueKind, Value};
use cargo_kcfg::{ConfigTest, Error};

fn uart_paths() -> Result<(), Error> {
    let kconfig = ConfigTest::discover()?;

    let ok = kconfig.evaluate("configs/qemu_defconfig")?;
    if ok.get("UART") == Some(&Value::Bool(true)) {
        assert_eq!(ok.get("BUS"), Some(&Value::Bool(true)));
    }

    match kconfig.evaluate("configs/cases/unmet_defconfig") {
        Err(Error::Validation(report)) if report.has_kind(IssueKind::UnmetDependency) => {}
        other => panic!("expected unmet-dependency, got {other:?}"),
    }

    match kconfig.evaluate_text("CONFIG_UART=y\n") {
        Err(Error::Validation(_)) => {}
        other => panic!("expected validation error, got {other:?}"),
    }
    Ok(())
}

§Optional: #[cfg(CONFIG_*)]

If this crate must use #[cfg(CONFIG_FOO)] / cfg!(CONFIG_FOO), add cargo-kcfg as a build-dependency. That cfg is visible only inside that crate.

[build-dependencies]
cargo-kcfg = "0.0.2"
if cargo_kcfg::run_build_script().is_err() {
    std::process::exit(1);
}

Prefer if CONFIG_FOO and sharing the_lib::config unless you truly need cfg.

§Crate map

SurfaceResponsibility
cargo-kcfg-macros::include_config!Compile-time include of CONFIG_* constants. No build.rs. Host-only proc-macro.
ConfigTestRuntime evaluate of a chosen (including illegal) defconfig from unit tests.
Pipeline / ProjectLocatorLoad Kconfig + defconfig, evaluate, generate .config / config.rs.
BuildScript / run_build_scriptOptional build.rs helper: write OUT_DIR artefacts and emit cargo:rustc-cfg.
cli::Clicargo kcfg check|build|test.
TelemetryProcess-wide tracing on stderr; new(prefix) prefixes every log line.
domainPure evaluation: symbols, expressions, select/imply/choice. No filesystem.
infraFiles, parser adapter, codegen, discovery. Depends on domain, never the reverse.
ErrorAll library and CLI failures. Domain evaluation failures are ValidationReport.

The binary (src/main.rs) only installs Telemetry and calls cli::Cli::run. It panics solely if telemetry cannot be installed.

§Errors

Public functions return Result with Error (or TelemetryError / ValidationReport where noted). Nothing in the library panics on user input.

VariantWhen
Error::IoA Kconfig, defconfig, or output path could not be read or written.
Error::Parsenom-kconfig rejected the file, or trailing text was left unparsed.
Error::ValidationThe configuration is incoherent (unmet depends on, bad select, choice conflict, unknown symbol, type mismatch, out of range, cycle).
Error::DomainResource limits or symbol-table rules (Limits) were exceeded.
Error::UsageMissing files, ambiguous defconfigs, missing CARGO_MANIFEST_DIR/OUT_DIR, or rustc failed during cargo kcfg test.
TelemetryError::InitFailedTelemetry::new called more than once in the process.

Match on Error::Validation and ValidationReport::has_kind in tests to branch on a known-bad defconfig. The Display text always includes what is wrong and what to change.

§Commands

cargo kcfg check
cargo kcfg build
cargo kcfg test

check validates only. build writes .config and config.rs. test additionally type-checks the generated constants with rustc.

--root <DIR>           Project root used to resolve `source` paths
--kconfig <FILE>       Root Kconfig (default: <root>/Kconfig)
--defconfig <FILE>     Assignment file (`*_defconfig` or `.config`)
--out-dir <DIR>        Where to write generated files
--emit-rustc-cfg       Print cargo rustc-cfg lines (for an optional build.rs)

§Examples in this repository

ExampleWhat it shows
examples/minimalBool / int / string constants, source, and if CONFIG_*
examples/dependsdepends on, && / `
examples/firmwareMenus, default ... if, range, tristate, hex, def_bool, select HAS_NET, and a sourced file gated by if NETWORK
examples/selectselect auto-enables helpers; enabling a target whose depends on is unmet is an error. imply is a weak default. Switch with KCONFIG_DEFCONFIG=dma_defconfig or imply_defconfig
examples/choiceBool choice exclusivity. Switch with KCONFIG_DEFCONFIG=rtt_defconfig
examples/errorsEach keyword that must fail: depends on, select, imply (user y), if, choice, range. Valid defaults: ok_defconfig and imply_respected_defconfig
examples/workspaceVirtual workspace: root Kconfig + configs/qemu_defconfig, member lib with include_config! (no build.rs), member app that uses lib::config. Unit tests feed a bad defconfig through ConfigTest
KCONFIG_DEFCONFIG=bus_defconfig cargo run --manifest-path examples/depends/Cargo.toml
KCONFIG_DEFCONFIG=no_bus_defconfig cargo run --manifest-path examples/depends/Cargo.toml

KCONFIG_DEFCONFIG=debug_defconfig cargo run --manifest-path examples/firmware/Cargo.toml
KCONFIG_DEFCONFIG=prod_defconfig cargo run --manifest-path examples/firmware/Cargo.toml

KCONFIG_DEFCONFIG=uart_defconfig cargo run --manifest-path examples/select/Cargo.toml
KCONFIG_DEFCONFIG=dma_defconfig cargo run --manifest-path examples/select/Cargo.toml
KCONFIG_DEFCONFIG=imply_defconfig cargo run --manifest-path examples/select/Cargo.toml

KCONFIG_DEFCONFIG=uart_defconfig cargo run --manifest-path examples/choice/Cargo.toml
KCONFIG_DEFCONFIG=rtt_defconfig cargo run --manifest-path examples/choice/Cargo.toml

KCONFIG_DEFCONFIG=ok_defconfig cargo run --manifest-path examples/errors/Cargo.toml
KCONFIG_DEFCONFIG=imply_respected_defconfig cargo run --manifest-path examples/errors/Cargo.toml

cargo test --manifest-path examples/workspace/lib/Cargo.toml
cargo run --manifest-path examples/workspace/app/Cargo.toml

Invalid defconfigs error out instead of generating constants. Check them with the CLI:

cargo kcfg check --root examples/errors --defconfig depends_unmet_defconfig
cargo kcfg check --root examples/errors --defconfig select_unmet_defconfig
cargo kcfg check --root examples/errors --defconfig imply_unmet_defconfig
cargo kcfg check --root examples/errors --defconfig if_unmet_defconfig
cargo kcfg check --root examples/errors --defconfig choice_conflict_defconfig
cargo kcfg check --root examples/errors --defconfig range_bad_defconfig

select is a reverse dependency: enabling UART_FOO turns HAS_UART on even if the user never assigned it. If the target’s own depends on is still unmet after that, evaluation fails and tells you to enable the missing dependencies or remove the select. imply is the weaker form — the user can keep the target at n, and unmet target dependencies are respected (the imply does not fire).

§Design

The crate follows a strict domain / infrastructure split:

  • domain — Symbol, SymbolTable, Expression, Tristate, Value, AssignmentSet, ChoiceGroup, DependencyGraph, evaluation, and ValidationReport. No filesystem or Cargo types.
  • infrastructure — Kconfig loading (following source directives, never crawling the tree), defconfig parsing, code generation, CLI.

Inputs are size-limited. Unexpected types, out-of-range integers, unknown symbols, select/imply of a non-bool target, unmet user assignments, and select of a target whose depends on is unmet are reported as errors rather than ignored.

§License

MIT

Re-exports§

pub use domain::Assignment;
pub use domain::AssignmentSet;
pub use domain::ChoiceGroup;
pub use domain::DependencyGraph;
pub use domain::EvaluatedConfig;
pub use domain::Evaluator;
pub use domain::Expression;
pub use domain::Limits;
pub use domain::Symbol;
pub use domain::SymbolTable;
pub use domain::SymbolType;
pub use domain::Tristate;
pub use domain::ValidationReport;
pub use domain::Value;
pub use domain::evaluate;
pub use error::Error;
pub use infra::build_script::BuildScript;
pub use infra::build_script::run_build_script;
pub use infra::codegen::CodeGenerator;
pub use infra::codegen::Generated;
pub use infra::config_test::ConfigTest;
pub use infra::locator::ProjectLocator;
pub use infra::locator::find_unique_defconfig;
pub use infra::locator::resolve_defconfig;
pub use infra::locator::resolve_kconfig;
pub use infra::pipeline::ArtifactWriter;
pub use infra::pipeline::GenerateRequest;
pub use infra::pipeline::GenerateResult;
pub use infra::pipeline::Pipeline;
pub use infra::pipeline::run;
pub use infra::pipeline::write_outputs;
pub use telemetry::telemetry::Telemetry;
pub use telemetry::telemetry::TelemetryError;

Modules§

cli
CLI entry — start here after main.
domain
Core Kconfig domain: symbols, expressions, evaluation, and validation.
error
Top-level error type for the library, CLI, and optional build.rs helper.
infra
Infrastructure: file loading, parser adaptation, and code generation.
telemetry
Process-wide telemetry and structured logging macros.

Macros§

telemetry_error
Log an ERROR event, prefixed with the string passed to Telemetry::new.
telemetry_info
Log an INFO event, prefixed with the string passed to Telemetry::new.