Crate cargo_rustc_cfg

The goal of this library, a.k.a. crate, is to provide access to the compiler configuration at Cargo build time of a project for use with third-party Cargo custom subcommands by running the cargo rustc -- --print cfg command and parsing its output. This library is not recommended for build scripts as the compiler configuration information is available via Cargo environment variables that are passed to build scripts at run time.

If the Rust compiler (rustc) target is x86_64-pc-windows-msvc, then the output from the cargo rustc -- --print cfg command will look similar to this:

PS C:\Path\to\Rust\Project> cargo rustc -- --print cfg
  Compiling <PACKAGE> vX.X.X (<PACKAGE_PATH>)
debug_assertions
target_arch="x86_64"
target_endian="little"
target_env="msvc"
target_family="windows"
target_feature="fxsr"
target_feature="sse"
target_feature="sse2"
target_os="windows"
target_pointer_width="64"
target_vendor="pc"
windows
  Finished dev [unoptimized + debuginfo] target(s) in 0.10s

where <PACKAGE> is replaced with the name of the Rust package, the vX.X.X is replaced with the Semantic Version number defined in the package's manifest (Cargo.toml), and the <PACKAGE_PATH> is replaced with the absolute path to the package's root directory. The output may vary depending on the rustc target and development environment.

This crate parses the above output and provides the Cfg and Target types for accessing the various values from the output. The values for any lines containing a key-value pair and prepended by the target_ string are available in the Target type with the double quotes, ", removed. Any lines that are not recognized and/or not a target key-value pair are stored (unaltered) and can be obtained with the Cfg::extras method.

Examples

Get the configuration for the default rustc target as configured by Cargo if the rustc target is x86_64-pc-windows-msvc:

let cfg = Cfg::new()?;
assert_eq!(cfg.target().arch(), "x86_64");
assert_eq!(cfg.target().endian(), "little");
assert_eq!(cfg.target().env(), Some("msvc"));
assert_eq!(cfg.target().family(), Some("windows"));
assert_eq!(cfg.target().os(), "windows");
assert_eq!(cfg.target().pointer_width(), "64");
assert_eq!(cfg.target().vendor(), Some("pc"));

If the default rustc target is x86_64-pc-windows-gnu, then:

let cfg = Cfg::new()?;
assert_eq!(cfg.target().arch(), "x86_64");
assert_eq!(cfg.target().endian(), "little");
assert_eq!(cfg.target().env(), Some("gnu"));
assert_eq!(cfg.target().family(), Some("windows"));
assert_eq!(cfg.target().os(), "windows");
assert_eq!(cfg.target().pointer_width(), "64");
assert_eq!(cfg.target().vendor(), Some("pc"));

If the default rustc target is x86_64-unknown-linux-gnu, then:

let cfg = Cfg::new()?;
assert_eq!(cfg.target().arch(), "x86_64");
assert_eq!(cfg.target().endian(), "little");
assert_eq!(cfg.target().env(), None);
assert_eq!(cfg.target().family(), Some("unix"));
assert_eq!(cfg.target().os(), "os");
assert_eq!(cfg.target().pointer_width(), "64");
assert_eq!(cfg.target().vendor(), Some("unknown"));

If the default rustc target is x86_64-apple-darwin, then:

let cfg = Cfg::new()?;
assert_eq!(cfg.target().arch(), "x86_64");
assert_eq!(cfg.target().endian(), "little");
assert_eq!(cfg.target().env(), None);
assert_eq!(cfg.target().family(), Some("unix"));
assert_eq!(cfg.target().os(), "os");
assert_eq!(cfg.target().pointer_width(), "64");
assert_eq!(cfg.target().vendor(), Some("apple"));

If the default rustc target is i686-pc-windows-msvc, then:

let cfg = Cfg::new()?;
assert_eq!(cfg.target().arch(), "x86");
assert_eq!(cfg.target().endian(), "little");
assert_eq!(cfg.target().env(), Some("msvc"));
assert_eq!(cfg.target().family(), Some("windows"));
assert_eq!(cfg.target().os(), "windows");
assert_eq!(cfg.target().pointer_width(), "32");
assert_eq!(cfg.target().vendor(), Some("pc"));

If the default rustc target is i686-pc-windows-gnu, then:

let cfg = Cfg::new()?;
assert_eq!(cfg.target().arch(), "x86_64");
assert_eq!(cfg.target().endian(), "little");
assert_eq!(cfg.target().env(), Some("gnu"));
assert_eq!(cfg.target().family(), Some("windows"));
assert_eq!(cfg.target().os(), "windows");
assert_eq!(cfg.target().pointer_width(), "32");
assert_eq!(cfg.target().vendor(), Some("pc"));

If the rustc target is i686-unknown-linux-gnu, then:

let cfg = Cfg::new()?;
assert_eq!(cfg.target().arch(), "x86");
assert_eq!(cfg.target().endian(), "little");
assert_eq!(cfg.target().env(), None);
assert_eq!(cfg.target().family(), Some("unix"));
assert_eq!(cfg.target().os(), "os");
assert_eq!(cfg.target().pointer_width(), "32");
assert_eq!(cfg.target().vendor(), Some("unknown"));

If the rustc target is i686-apple-darwin, then:

let cfg = Cfg::new()?;
assert_eq!(cfg.target().arch(), "x86");
assert_eq!(cfg.target().endian(), "little");
assert_eq!(cfg.target().env(), None);
assert_eq!(cfg.target().family(), Some("unix"));
assert_eq!(cfg.target().os(), "os");
assert_eq!(cfg.target().pointer_width(), "32");
assert_eq!(cfg.target().vendor(), Some("apple"));

Get the configuration for a specific rustc target triple using the Cfg::with_args with the --target <TRIPLE> option for the cargo rustc subcommand:

let cfg = Cfg::with_args(
    &["--target", "i686-pc-windows-msvc"],
    std::iter::empty::<&str>()
)?;
assert_eq!(cfg.target().arch(), "x86");
assert_eq!(cfg.target().endian(), "little");
assert_eq!(cfg.target().env(), Some("msvc"));
assert_eq!(cfg.target().family(), Some("windows"));
assert_eq!(cfg.target().os(), "windows");
assert_eq!(cfg.target().pointer_width(), "32");
assert_eq!(cfg.target().vendor(), Some("pc"));

The above use-case is relatively common, but it is tedious to routinely use the Cfg::with_args method. The Cfg::with_triple method is available as a shorthand for the previous example:

let cfg = Cfg::with_triple("i686-pc-windows-msvc")?;
assert_eq!(cfg.target().arch(), "x86");
assert_eq!(cfg.target().endian(), "little");
assert_eq!(cfg.target().env(), Some("msvc"));
assert_eq!(cfg.target().family(), Some("windows"));
assert_eq!(cfg.target().os(), "windows");
assert_eq!(cfg.target().pointer_width(), "32");
assert_eq!(cfg.target().vendor(), Some("pc"));

Structs

Cfg	A container for the parsed output from the cargo rustc -- --print cfg command.
Target	A container for all lines from the output that are prefixed with the target_ string.

Enums

Error

The error type for cargo-rustc-cfg operations and associated traits.

Constants

CARGO	The command line name of the Cargo application.
CARGO_VARIABLE	The environment variable name for the Cargo appplication.
RUSTC	The command line name of the Rust compiler subcommand for Cargo.