cargo-px

Cargo Power eXtensions

查看 公告帖子 了解更多关于 cargo-px 以及它解决 Rust 项目的代码生成问题的信息。

如何使用

它设计为一个 cargo 代理：您不需要调用 cargo <CMD> <ARGS>，而是使用 cargo px <CMD> <ARGS>。例如，您可以使用 cargo px build --all-features 而不是 cargo build --all-features。

cargo px 每次您调用它时都会检查您的 workspace。
如果您的任何 crate 需要生成，它将在将命令及其参数转发到 cargo 之前调用相应的代码生成器。

cargo px 利用 metadata 部分。
在您想查看生成的crate中，您需要填写如下 package.metadata.px.generate 部分：

[package]
name = "..."
version = "..."
# [...]

[package.metadata.px.generate]
# The generator is a binary in the current workspace. 
# It's the only generator type we support at the moment.
generator_type = "cargo_workspace_binary"
# The name of the binary.
generator_name = "bp"
# The arguments to be passed to the binary. 
# It can be omitted if there are no arguments.
generator_args = ["--quiet", "--profile", "optimised"]

cargo-px 将检测配置并为您调用 cargo run --bin bp -- --quiet --profile="optimised"。
如果有多个需要代码生成的crate，cargo-px 将按考虑依赖图（即依赖项总是在其依赖项之前进行代码生成）的顺序调用相应的代码生成器。

cargo-px 还将为代码生成器设置两个环境变量：

• CARGO_PX_GENERATED_PKG_MANIFEST_PATH，需要生成crate的Cargo.toml文件的路径；
• CARGO_PX_WORKSPACE_ROOT_DIR，定义当前工作区的Cargo.toml文件的路径（即包含 [workspace] 部分的那个）。

您可以使用 cargo_px_env crate 来检索和使用这些环境变量。

验证生成的代码是否是最新的

如果您正在提交生成的代码，您可能希望在CI中验证它是否是最新的。
您可以通过调用 cargo px verify-freshness 来执行此操作。
这仅在您为工作区中的每个代码生成的项目定义验证器的情况下才有效

[package]
name = "..."
version = "..."
# [...]

[package.metadata.px.verify]
# The verifier is a binary in the current workspace. 
# It's the only verifier type we support at the moment.
verifier_type = "cargo_workspace_binary"
# The name of the binary.
verifier_name = "bp"
# The arguments to be passed to the binary. 
# It can be omitted if there are no arguments.
verifier_args = ["--verify"]

cargo-px 将检测配置并为您调用 cargo run --bin bp -- --verify"。
如果验证器调用返回状态码 0，则认为生成的包是最新的。

如果有多个需要验证的crate，cargo-px 将按考虑依赖图（即依赖项总是在其依赖项之前进行代码生成）的顺序调用相应的验证器。

cargo-px 还将为验证器设置两个环境变量：

• CARGO_PX_GENERATED_PKG_MANIFEST_PATH，生成crate的Cargo.toml文件的路径；
• CARGO_PX_WORKSPACE_ROOT_DIR，定义当前工作区的Cargo.toml文件的路径（即包含 [workspace] 部分的那个）。

您可以使用 cargo_px_env crate 来检索和使用这些环境变量。

已知问题

MacOS

如果您使用的是macOS机器，您可能想要 禁用终端的gatekeeper notarisation。

每次您第一次执行一个二进制文件时，Apple 都会通过网络向他们的服务器发送一个请求。这对 cargo-px 是一个问题，因为它必须编译您的生成器然后执行它：生成器二进制文件是“新的”，因此它遭受了notarisation检查的惩罚。
延迟的大小取决于您的连接质量以及苹果服务器的性能。在良好的互联网连接下，我始终观察到100/150毫秒的延迟，但也有报道称延迟达到几秒钟。
闲话少说：如果您在没有互联网连接的情况下工作，苹果将完全跳过检查，并允许您无任何抱怨地执行未经验证的二进制文件。

许可证

根据您的选择，受Apache License，Version 2.0或MIT许可证的许可。除非您明确说明，否则您有意提交给本仓库的任何贡献，如Apache-2.0许可证所定义，应按上述方式双许可，不附加任何额外条款或条件。