Skip to content

Latest commit

 

History

History
138 lines (96 loc) · 9.6 KB

features-examples.zh.md

File metadata and controls

138 lines (96 loc) · 9.6 KB

Features Examples

下面展示了一些实际的功能示例。

Minimizing build times and file sizes

让构建时间的软件大小最小化

有些软件包使用功能,因此如果未启用这些功能,它会减小箱子的大小,并缩短编译时间。例如:

  • syn是一种用于解析 Rust 代码的流行箱子。由于它非常流行,因此有助于减少编译时间,因为它会影响很多项目。它有一个清晰的功能列表文档,可用于最小化其包含的代码量的功能。
  • regex有一个几项功能,那是很好的功能文档。删除 Unicode 支持可以减少生成的文件大小,因为它可以删除一些大型表格。
  • winapi一长串的功能,用来限制那些 Windows API 绑定。
  • web-sys是另一个例子,与winapi类似,它提供了一个超大的范围,控制功能 API 绑定。

Extending behavior

行为是可扩展得

serde_json包上有一个preserve_order 功能,它会更改JSON maps 行为,以保留 keys 插入的顺序。注意到的是,它启用了可选的依赖项indexmap,来实现这个新的行为。

当改变这样的行为时,要小心确保这些改变是正确的,SemVer 兼容的。也就是说,启用该功能不应破坏通常在关闭该功能的情况下,生成的代码。

no_std support

有些软件包希望同时支持no_stdstd环境。这对于支持嵌入式和资源受限的平台很有用,但仍要允许,它可以扩展为支持完整标准库的平台的功能。

这个wasm-bindgen包是会定义std 作为功能,其是默认启用的。在 library 的顶层必然启用 no_std 属性。之后,要确保std还有[std prelude][std 预载]不自动在(构建)范围内。然后,在代码的各个地方(比如:example1, example2),它使用#[cfg(feature = "std")]属性,有条件地启用需要的额外功能std

Re-exporting dependency features

重导出依赖项功能

有种方便的做法,就是将一个依赖项的功能,重新导出。用户控制这些功能,就无需直接指定这些依赖项。例如,regexregex_syntax包进行重导出,而用户不需要知道regex_syntax包,但他们仍然可以访问它包含的功能。

Vendoring of C libraries

C 库的供给

有些软件包提供了,对通用 C 库的绑定(有时,称为"sys" crates)。有时,这些软件包让您可以选择,使用系统上安装的 C 库,或者从源代码构建它。例如,openssl包上有一个vendored 功能,启用openssl-sys相应的vendored功能,而openssl-sys构建脚本有一些条件性逻辑,导致它从 OpenSSL 源代码的本地副本构建,而不是使用系统中的版本。

这个curl-sys包是另一个示例,static-curl 功能,让这个包,从源代码构建 libcurl。注意,它还有一个force-system-lib-on-osx迫使它使用系统的 libcurl,覆盖 static-curl 设置。

Feature precedence

功能的优先级

有些软件包可能具有相互排斥的功能。处理这一问题的一个选择是:优先选择一个功能。这个log包就是一个例子。它有几项功能用于在编译时,选择最大日志记录级别,文档在here。它使用cfg-if,用来选择一个优先级。如果启用了多个功能,则与较低级别相比,更高的“最大”级别将应用。

Proc-macro companion package

(Proc-macro)宏指令伴侣

有些软件包有一个与之密切相关的 proc 宏。但是,并非所有用户都需要使用 proc 宏。通过将 proc 宏设置为可选依赖项,可以方便地选择是否包含它。这很有帮助,因为有时 proc 宏版本,必须与父包保持同步,并且您不希望强制用户必须指定这两个依赖项,并保持它们同步。

例如serde它有一个derive使serde_derive过程宏。这个serde_derive箱子被紧紧地绑在一起serde,所以它使用equals version requirement以确保它们保持同步。

Nightly-only features

一些软件包想要尝试 API 或语言的实验性功能,这些功能只在 Rust nightly channel上可用,但是,他们可能不想要求用户也使用 nightly channel。例如wasm-bindgen有一个nightly feature,使得extended API能够使用 nightly channel 上的Unsize marker trait。

请注意,在箱子的根目录上,它使用cfg_attr 启用 nightly 功能。记住[feature 属性]与 Cargo 功能无关,用于实验性语言功能——(可选择性)。

rand的这个simd_support feature是另一个例子,它依赖于只在 nightly channel 上构建的依赖项。

Experimental features

有些软件包有新的功能,他们可能想试用,却不保证这些 API 的稳定性。这些功能通常被记录为实验性的,因为将来可能会改变或中断(即使是在一个小版本中)。例如async-std包,它有一个unstable feature,会有个gates new APIs能选择使用,但可能还没有完全准备好被依赖。