Crate toml_cfg

toml-cfg

Summary

• Crates can declare variables that can be overridden
  • Anything const, e.g. usize, strings, etc.
• (Only) The “root crate” can override these variables by including a cfg.toml file

Config file

This is defined ONLY in the final application or “root crate”

# a toml-cfg file

[lib-one]
buffer_size = 4096

[lib-two]
greeting = "Guten tag!"

In the library

// lib-one
#[toml_cfg::toml_config]
pub struct Config {
    #[default(32)]
    buffer_size: usize,
}

 // lib-two
 #[toml_cfg::toml_config]
 pub struct Config {
     #[default("hello")]
     greeting: &'static str,
 }

Configuration

With the TOML_CFG environment variable is set with a value containing “require_cfg_present”, the toml-cfg proc macro will panic if no valid config file is found. This is indicative of either no cfg.toml file existing in the “root project” path, or a failure to find the correct “root project” path.

This failure could occur when NOT building with a typical cargo build environment, including with rust-analyzer. This is mostly okay, as it doesn’t seem that Rust Analyzer presents this in some misleading way.

If you do find a case where this occurs, please open an issue!

Look at what we get!

# Print the "buffer_size" value from the `lib-one` crate.
# Since it has no cfg.toml, we just get the default value.
$ cd pkg-example/lib-one
$ cargo run
    Finished dev [unoptimized + debuginfo] target(s) in 0.01s
     Running `target/debug/lib-one`
32

# Print the "greeting" value from the `lib-two` crate.
# Since it has no cfg.toml, we just get the default value.
$ cd ../lib-two
$ cargo run
   Compiling lib-two v0.1.0 (/home/james/personal/toml-cfg/pkg-example/lib-two)
    Finished dev [unoptimized + debuginfo] target(s) in 0.32s
     Running `target/debug/lib-two`
hello

# Print the "buffer_size" value from `lib-one`, and "greeting"
# from `lib-two`. Since we HAVE defined a `cfg.toml` file, the
# values defined there are used instead.
$ cd ../application
$ cargo run
   Compiling lib-two v0.1.0 (/home/james/personal/toml-cfg/pkg-example/lib-two)
   Compiling application v0.1.0 (/home/james/personal/toml-cfg/pkg-example/application)
    Finished dev [unoptimized + debuginfo] target(s) in 0.30s
     Running `target/debug/application`
4096
Guten tag!

Attribute Macros

toml_config