|new 0.1.7||Nov 18, 2023|
|0.1.6||Nov 18, 2023|
|0.1.5||Jun 20, 2023|
|0.1.4||May 18, 2023|
|0.1.0||Apr 27, 2023|
#222 in Cargo plugins
Check out the announcement post to learn more about
cargo-px and the problems it solves with respect to code generation in Rust projects.
Table of Contents
How To Install
You can install
cargo-px from crates.io with
cargo install cargo-px --locked
If you're using a macOS machine, you probably want to disable gatekeeper notarisation for your terminal.
Every time you execute a binary for the first time, Apple executes a request over the network to their servers. This becomes an issue for
cargo-px, since it must compile your generator and then execute it: the generator binary is "new", therefore it incurs the penalty of this notarisation check.
The magnitude of the delay depends on the quality of your connection as well as on Apple's servers performance. On a good Internet connection, I consistenly observed 100/150ms delays, but delays in the order of seconds have been reported as well.
Fun aside: if you're working without an Internet connection, Apple skips the check entirely and lets you execute unverified binaries without any complaint.
How to use
It is designed as a
cargo proxy: instead of invoking
cargo <CMD> <ARGS>, you go for
cargo px <CMD> <ARGS>. For example, you go for
cargo px build --all-features instead of
cargo build --all-features.
cargo px examines your workspace every time you invoke it.
If any of your crates needs to be generated, it will invoke the respective code generators before forwarding the command and its arguments to cargo.
[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 will detect the configuration and invoke
cargo run --bin bp -- --quiet --profile="optimised" for you.
If there are multiple crates that need to be code-generated,
cargo-px will invoke the respective code-generators in an order that takes into account the dependency graph (i.e. dependencies are always code-generated before their dependents).
cargo-px will also set two environment variables for the code generator:
CARGO_PX_GENERATED_PKG_MANIFEST_PATH, the path to the
Cargo.tomlfile of the crate that needs to be generated;
CARGO_PX_WORKSPACE_ROOT_DIR, the path to the
Cargo.tomlfile that defines the current workspace (i.e. the one that contains the
You can use the
cargo_px_env crate to retrieve and work with these environment variables.
Verify that the generated code is up-to-date
If you are committing the generated code, it might be desirable to verify in CI that it's up-to-date.
You can do so by running:
# Triggers code-generation and verifies that the code compiles cargo px check # Returns an error if the code generation step created new files or # modified any of the files tracked by `git` in version control git diff --quiet HEAD || (echo "The code-generated crates are stale. Re-run 'cargo px check locally and commit the results" && exit 1)
Licensed under either of Apache License, Version 2.0 or MIT license at your option. Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.