Cargo Feature 是非常强大的机制,可以为大家提供条件编译和可选依赖的高级特性,可以为你省下不少的代码量来判断操作系统和条件编译等功能。rust官方条件编译文档:Conditional compilation - The Rust Reference
features特性
Featuure
可以通过 Cargo.toml
中的 [features]
部分来定义:其中每个 feature
通过列表的方式指定了它所能启用的其他 feature
或可选依赖。
假设我们有一个 2D 图像处理库,然后该库所支持的图片格式可以通过以下方式启用:
[features]
# 定义一个feature并启动: webp, 但它并没有启用其它 feature
webp = []
当定义了 webp
后,我们就可以在代码中通过 cfg 表达式来进行条件编译(cfg表达式讲解说明:
https://xiaoshen.blog.csdn.net/article/details/137040041?spm=1001.2014.3001.5502)。例如项目中的 lib.rs 可以使用以下代码对 webp 模块进行条件引入:
#[cfg(feature = "webp")]
pub mod webp;
#[cfg(feature = "webp")]
的含义是:只有在 webp
feature 被定义后,以下的 webp
模块才能被引入进来。由于我们之前在 [features]
里定义了 webp
,因此以上代码的 webp
模块会被成功引入。
在 Cargo.toml
中定义的 feature
会被 Cargo
通过命令行参数 --cfg
传给 rustc
,最终由后者完成编译:rustc --cfg ...
。若项目中的代码想要测试 feature
是否存在,可以使用 cfg属性 或 cfg 宏。
之前我们提到了一个 feature
还可以开启其他 feature
,举个例子,例如 ICO
图片格式包含 BMP
和 PNG
,因此当 ICO
图片格式被启用后,它还得确保启用 BMP
和 PNG
格式:
[features]
bmp = []
png = []
ico = ["bmp", "png"]
webp = []
对此,我们可以理解为: bmp 和 png 是开启 ico 的先决条件。
Feature 名称可以包含来自 Unicode XID standard 定义的字母,允许使用 _ 或 0-9 的数字作为起始字符,在起始字符后,还可以使用 -、+ 或 . 。
但是我们还是推荐按照 http://crates.io 的方式来设置 Feature 名称 : crate.io 要求名称只能由 ASCII 字母数字、_、- 或 + 组成。
default feature
默认情况下,所有的 feature
都会被自动禁用,可以通过 default
来启用它们:
[features]
default = ["ico", "webp"]
bmp = []
png = []
ico = ["bmp", "png"]
webp = []
使用如上配置的项目被构建时,default
feature 首先会被启用,然后它接着启用了 ico
和 webp
feature,当然我们还可以关闭 default
:
--no-default-features
命令行参数可以禁用default
feature</