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 --helpThe binary is named cargo-kcfg, so Cargo exposes it as a subcommand:
cargo kcfg check
cargo kcfg build
cargo kcfg testConstants 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.rsconfig 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 buildKeep 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
| Surface | Responsibility |
|---|---|
cargo-kcfg-macros::include_config! | Compile-time include of CONFIG_* constants. No build.rs. Host-only proc-macro. |
ConfigTest | Runtime evaluate of a chosen (including illegal) defconfig from unit tests. |
Pipeline / ProjectLocator | Load Kconfig + defconfig, evaluate, generate .config / config.rs. |
BuildScript / run_build_script | Optional build.rs helper: write OUT_DIR artefacts and emit cargo:rustc-cfg. |
cli::Cli | cargo kcfg check|build|test. |
Telemetry | Process-wide tracing on stderr; new(prefix) prefixes every log line. |
domain | Pure evaluation: symbols, expressions, select/imply/choice. No filesystem. |
infra | Files, parser adapter, codegen, discovery. Depends on domain, never the reverse. |
Error | All 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.
| Variant | When |
|---|---|
Error::Io | A Kconfig, defconfig, or output path could not be read or written. |
Error::Parse | nom-kconfig rejected the file, or trailing text was left unparsed. |
Error::Validation | The configuration is incoherent (unmet depends on, bad select, choice conflict, unknown symbol, type mismatch, out of range, cycle). |
Error::Domain | Resource limits or symbol-table rules (Limits) were exceeded. |
Error::Usage | Missing files, ambiguous defconfigs, missing CARGO_MANIFEST_DIR/OUT_DIR, or rustc failed during cargo kcfg test. |
TelemetryError::InitFailed | Telemetry::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 testcheck 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
| Example | What it shows |
|---|---|
examples/minimal | Bool / int / string constants, source, and if CONFIG_* |
examples/depends | depends on, && / ` |
examples/firmware | Menus, default ... if, range, tristate, hex, def_bool, select HAS_NET, and a sourced file gated by if NETWORK |
examples/select | select 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/choice | Bool choice exclusivity. Switch with KCONFIG_DEFCONFIG=rtt_defconfig |
examples/errors | Each keyword that must fail: depends on, select, imply (user y), if, choice, range. Valid defaults: ok_defconfig and imply_respected_defconfig |
examples/workspace | Virtual 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.tomlInvalid 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_defconfigselect 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, andValidationReport. No filesystem or Cargo types. - infrastructure — Kconfig loading (following
sourcedirectives, 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.rshelper. - 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.