vergen - 一套从 Cargo 构建脚本生成 cargo 指令的库

vergen、vergen-git2、vergen-gitcl、vergen-gix、vergen-pretty

当与 cargo 构建脚本 结合使用时，可以生成以下 输出

• 将为每个启用的功能生成 cargo:rustc-env=VAR=VALUE。您可以使用代码中的 env! 或 option_env! 宏来引用这些指令。
• 如果使用具有 git 功能的库之一，将生成 cargo:rerun-if-changed=.git/HEAD。这是为了确保在提交时重新生成任何 git 指令。
• 如果使用具有 git 功能的库之一，将发出 cargo:rerun-if-changed=.git/<path_to_ref>。这样做是为了确保在提交时重新生成任何 git 指令。
• 如果未启用 fail_on_error 功能，并且请求的变量因错误而默认或通过 idempotent 标志默认，则可以发出 cargo:warning 输出。
• 如果 build.rs 文件已更改，将发出 cargo:rerun-if-changed=.git/<path_to_ref> 以重新运行指令发出。
• 如果 VERGEN_IDEMPOTENT 环境变量已更改，将发出 cargo:rerun-if-env-changed=VERGEN_IDEMPOTENT 以重新运行指令发出。
• 如果 SOURCE_DATE_EPOCH 环境变量已更改，将发出 cargo:rerun-if-env-changed=SOURCE_DATE_EPOCH 以重新运行指令发出。

vergen-pretty 是一个基于 vergen 的 cargo 指令输出宏和美化打印器。

当前版本

vergen

vergen-git2

vergen-gitcl

vergen-gix

vergen-pretty

MSRV

当前最低支持的 Rust 版本为 1.73.0

⚠️ 关于版本 9 的注意事项 ⚠️

• 版本 9 引入了 3 个新的库，分别是 vergen-git2、vergen-gitcl 和 vergen-gix，这些库将与 vergen 独立版本化。
• 这三个新的库旨在在您需要生成基于 git 的 cargo 构建脚本指令时作为 vergen 的替代品。
• 基于 git 的功能已从基本 vergen 库中移除。
• vergen 现在包含 build、cargo、rustc 和 sysinfo 功能实现。这些功能通过新库重新导出，允许您配置输出，就像您以前做的那样。
• 版本 9 引入了 AddCustomEntries 特性。实现此特性允许您包括自己的自定义 Cargo 指令，使用 vergen 作为生成它们的引擎。有关更多信息，请参阅 AddCustomEntries 文档。
• 版本 8 分支 将在一段时间内得到维护。

为什么？

这是为了解决与Cargo功能统一和互斥功能相关的问题。之前版本的vergen有3个互斥功能（git2、gitcl和gix）。如果您包含了一个也使用了vergen但配置了不同git功能的依赖项，功能统一可能会导致编译问题。将git后端分割成单独的库有助于缓解这个问题。

从版本8迁移

请参阅MIGRATING_v8_to_v9.md文档

文档

• vergen
• vergen-git2
• vergen-gitcl
• vergen-gix
• vergen-pretty

贡献

请参阅CONTRIBUTING.md文档

许可

许可方式为以下之一

• Apache License，版本2.0（LICENSE-APACHE或https://apache.ac.cn/licenses/LICENSE-2.0）
• MIT许可（LICENSE-MIT或https://open-source.org.cn/licenses/MIT）由您选择。

贡献

除非您明确声明，否则根据Apache-2.0许可证定义的任何有意提交以包含在作品中的贡献，均将双重许可如上所述，不附加任何额外的条款或条件。