A cargo subcommand that extends cargo's capabilities when it comes to code generation.

Luca Palmieri

Last update: May 7, 2023

Related tags

Utilities cargo-px

Overview

cargo-px

Cargo Power eXtensions

Check out the announcement post to learn more about cargo-px and the problems it solves with respect to code generation in Rust projects.

How to install
How to use
Verify that the generated code is up-to-date
License

How To Install

You can install cargo-px from crates.io with

cargo install cargo-px --locked

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.

cargo px leverages the metadata section.
In the crate that you want to see generated, you fill in the [package.metadata.px.generate] section as follows:

[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.toml file of the crate that needs to be generated;
CARGO_PX_WORKSPACE_ROOT_DIR, the path to the Cargo.toml file that defines the current workspace (i.e. the one that contains the [workspace] section).

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)

License

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.

Comments

chore: release
🤖 New release

cargo-px: 0.1.2 -> 0.1.3 (✓ API compatible changes)

cargo_px_env: 0.1.0

Changelog

cargo-px

0.1.3 - 2023-05-05

Other

Add cargo_px_env (#6)

Add CI configuration (#1)

cargo_px_env

0.1.0 - 2023-05-05

Other

Add cargo_px_env (#6)

This PR was generated with release-plz.
opened by github-actions[bot] 0
chore: release v0.1.3
🤖 New release

cargo-px: 0.1.2 -> 0.1.3 (✓ API compatible changes)

Changelog

0.1.3 - 2023-05-03

Other

Add CI configuration (#1)

This PR was generated with release-plz.
opened by github-actions[bot] 0
chore: Add CI configuration

Issue #, if available:

Description of changes:

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

opened by LukeMathWalker 0
Pathological case: the code generator is a target in the generated package

We should detect this edge case and report an informative error to the user. The code generator must always be defined in a separate package from the generated crate.
bug enhancement

opened by LukeMathWalker 0
Re-compute codegen plan after the execution of each code-generation step

There are pathological cases (see here) that might require us to re-compute the codegen plan after the execution of each code generation unit.

We could start off with a pretty naive implementation (i.e. cargo generate-lockfile + re-compute the codegen plan - the units we already generated) and then make it more sophisticated over time (e.g. detect if the newly generated manifest has added any new dependency edges and skip re-generation if that's not the case).
bug enhancement

opened by LukeMathWalker 1
Console output: match `cargo`'s style and behaviour

As a rule of thumb, cargo-px doesn't want to "hide" the output coming from cargo commands—it should make it easier for users to understand what is being done (and it makes the tool feel more responsive if you can see what it is busy doing).

At the moment though, the visual style of cargo's output is quite different from the visual style of cargo-px's output (based on tracing-subscriber::fmt). I'd like to fix that: cargo-px's output should "blend in" with cargo's output in terms of colors and style.

We should detect when --verbose and --quiet flags are passed to commands proxied by cargo-px itself and behave accordingly (i.e. no intermediate output when --quiet is specified, just like in cargo).
enhancement help wanted good first issue

opened by LukeMathWalker 0

Releases(cargo_px_env-v0.1.0)

cargo_px_env-v0.1.0(May 5, 2023)
Other

Add cargo_px_env (#6)

Source code(tar.gz)
Source code(zip)
cargo-px-v0.1.3(May 5, 2023)
Other

Add cargo_px_env (#6)

Add CI configuration (#1)

Source code(tar.gz)
Source code(zip)