Cargo和编译器团队很高兴地宣布,从Rust1.80(或nightly-2024-05-05)开始,会自动检查每个可访问的#[cfg],看看是否与期望的配置名和值匹配.
这帮助验证crate,是否正确处理不同目标平台或函数的条件编译.它确保在期望和使用设置的配置间保持一致,帮助在开发过程的早期抓住潜在的错误.
特征一览
每次声明Cargo特征时,都会按传递给rustc(Rust编译器)的配置转换,这样可与周知的配置一起验证#[cfg],#![cfg_attr]和cfg!的配置是否有意外,并使用unexpected_cfgs检查来报告警告.
Cargo.toml中:
[package]
name = "foo"
[features]
lasers = []
zapping = []
src/lib.rs:
#[cfg(feature = "lasers")] //此条件是期望的,因为`"lasers"`是`'feature'`cfg`的期望值
fn shoot_lasers() {}
#[cfg(feature = "monkeys")] //它是意外的,因为`"monkeys"`不是`'feature'cfg`的期望值
fn write_shakespeare() {}
#[cfg(windosw)] //它是意外的,它应该是`"窗口"`
fn win() {}
需要自定义配置
更新:此节是在nightly-2024-05-19的发布中添加的.
从Cargo来看:自定义配置既不是由rustc定义的,也不是由Cargo函数定义的.想想tokio_unstable,has_foo.......但不是feature="lasers",unix或debug_assertions.
一些crate可用自定义配置,如loom,fuzzing或期望从环境中取得(RUSTFLAGS或其他方式)且在编译时总是是静态已知的tokio_unstable.
对这些,Cargo通过[lints]表来如期静态声明这些配置.
通过在[lints.rust.unexpected_cfgs]下的特殊check-cfg配置,如期定义这些自定义配置:
Cargo.toml文件
[lints.rust]
unexpected_cfgs = { level = "warn", checkcfg = ['cfg(loom)', 'cfg(fuzzing)'] }
构建脚本中的自定义配置
另一方面,一些crate使用由build.rs中的某些逻辑启用的自定义配置.对这些crate,Cargo提供了一个新指令:cargo::rustc-check-cfg(或较旧的Cargo版本的cargo:rustc-check-cfg).
在rustcbook检查配置节描述了使用的语法,总之,--check-cfg的基本语法是:
cfg(name, values("value1", "value2", ..., "valueN"))
注意,无论配置是否活动,每个自定义配置都必须总是是期望的!
build.rs示例
build.rs:
fn main() {
println!("cargo::rustccheckcfg=cfg(has_foo)");
//^^^^^^^^^^^^^^^^^^^^^^`Cargo1.80`的新功能
if has_foo() {
println!("cargo::rustccfg=has_foo");
}
}
每个cargo::rustccfg都应该有一个附带的无条件cargo::rustc-check-cfg指令,以避免此警告:未期望的条件名:has_foo.
等价表
| 第一列 | 第二列 |
|---|---|
货物::rustc-cfg | 货物::rustc-check-cfg |
foo | cfg(foo)或cfg(foo,values(none())) |
foo="" | cfg(foo,values("")) |
foo="bar" | cfg(foo,values("bar")) |
foo="1"和foo="2" | cfg(foo,values("1","2")) |
foo="1"和bar="2" | cfg(foo,values("1"))和cfg(bar,values("2")) |
foo和foo="bar" | cfg(foo,values(none(),"bar")) |
常见问题解答
可禁止吗
对Cargo用户,该功能总是打开且无法禁止,但与其他检查一样,可控制它:#![warn(unexpected_cfgs)].
检查是否会影响依赖
不会,和大多数检查一样,因为cap-lints,unexpected_cfgs只会报告本地包.
它如何与RUSTFLAGS环境交互
应该可如前使用RUSTFLAGS环境变量.当前不检查--配置参数,只检查代码中的用法.
即RUSTFLAGS="--cfg tokio_unstable" cargo check不会报告警告,除非在本地crate中使用tokio_unstable,此时,crate作者需要确保该crate的`build.
rs中带cargo::rustccheckcfg的自定义配置`.
如何在没有build.rs时期待自定义配置
更新:nightly-2024-05-19的Cargo现在提供[lints.rust.unexpected_cfgs.checkcfg]配置来定位静态已知的自定义配置.
如果Crate作者不想使用build.rs且不能[lints.rust.unexpected_cfgs.checkcfg],鼓励他们改用Cargo特征.
它如何与其他构建系统交互
默认,不基于Cargo的构建系统不受检查的影响.想拥有相同特征的构建系统作者应该查看rustc文档中的--checkcfg标志,以取如何实现相同功能的详细说明.
稳定实现和RFC3013有很大的不同,特别是--check-cfg只有一个形式:cfg()而不是values()和names()不完整且彼此不兼容.
cargo::rustccheckcfg将在Rust1.80(或nightly-2024-05-05)中开始工作.从Rust1.77到Rust1.79(含)会静默忽略它.在Rust1.76及更低版本中,在没有不稳定的Cargo标志-Zcheck-cfg时使用时会发出警告.