git2version

git2version 包提供了一种从git获取包版本并将其作为常量集成到程序中的方法。

设置

要使用此功能，您需要在工作区中设置一个代理包。

1. 将以下内容添加到您的Cargo.toml文件中

[workspace]

[dependencies]
version_proxy = {path = "./version_proxy"}

2. 将以下文件添加到代理包中

version_proxy/Cargo.toml

[package]
name = "version_proxy"
# The version field here is ignored, no need to change it
version = "0.0.0"

[dependencies]
git2version = "*"

[build-dependencies]
git2version = "*"

您还可以将git2version的版本锁定到特定版本，而不是使用 *。

version_proxy/build.rs

fn main() {
    git2version::init_proxy_build!();
}

version_proxy/src/lib.rs

git2version::init_proxy_lib!();

用法

您的代理包中的 init_proxy_lib! 宏将生成类似以下内容

pub const GITINFO: Option<GitInfo> =
    Some(GitInfo {
      tag_info: Some(TagInfo {
        tag:"v1.2.3-alpha",
        commits_since_tag: 5,
      }),
      commit_id: "a9ebd080a7",
      modified: false,
    });

如果包不在git仓库中或从git查找版本信息时出现错误，则此对象可以是 None。

您可以使用此常量从主包中使用，例如

fn main() {
    println!("Version from git: {:?}", version_proxy::GITINFO);
}

替代方案

git-version 包提供类似的功能。

git-version 相比于 git2version 的主要优势是它更容易使用。它使用基于 proc-macro 的方法，不需要您设置代理包。

git2version 相比于 git-version 的优势如下

• git2version 使用 git2 包来读取git信息。这意味着它不需要在您的路径中有一个 git 可执行文件即可工作。
• git2version 会输出有关 git 版本的 structured information，而 git-version 仅输出一个字符串，这个字符串由 git describe 生成。在 git-version 中，您需要自己解析这个字符串，并且它可能不总是包含所有信息（例如，当您检出标签时，git describe --tags 不会输出提交 id）。git2version 总是会给出提交 id。

另一个值得注意的点是，这两个 crates 使用不同的机制来检测增量构建中的更改。

• git2version 使用 cargo:rerun-if-changed 机制，在 build.rs 中重新生成版本号，每当 git 仓库发生变化时（例如添加新标签，调用 git fetch ...）以及每当工作副本中的文件发生变化时。后者很重要，因为它可能会改变报告中版本信息的 -modified 标志。
• git-version 使用 include_bytes! 机制将来自您的 git 仓库数据的字节数据包含到生成的源代码中，这将导致 cargo 将其检测为依赖项，并在 git 仓库数据更改时重新运行 proc 宏。这听起来很复杂，但可能有效。我还没有测试这种方法有多可靠或可扩展。cargo:rerun-if-changed 是官方支持进行此类更改检测的方式，因此我预计它应该更可靠，但它只适用于 build.rs 脚本，不适用于 proc 宏。

为什么需要代理 crate？

该 crate 需要知道您的 git 仓库目录以读取版本信息。然而，git2version crate 是独立编译的，无法访问您的 git 仓库。这就是为什么我们需要一个位于您 git 仓库内的代理 crate，该 crate 知道其位置并且可以评估版本信息。

您可能会问，为什么我们不直接在主 crate 中评估版本信息，毕竟主 crate 也位于您的仓库中。原因是用于评估版本信息的 build.rs 代码需要在每个单个文件修改后运行，因为这可能会影响 git 版本信息的 modified 标签。如果我们将其放入主 crate 中，那么增量编译基本上就变得毫无意义，因为它需要为每个更改重新编译一切。通过将其放入代理 crate，我们只需要重新编译代理 crate 中的代码，并将您的主 crate 链接到它。

许可：MIT 或 Apache-2.0