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

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.

Table of Contents

  1. How to install
  2. How to use
  3. Verify that the generated code is up-to-date
  4. 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

    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

    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

    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

    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

    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

    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)
Owner
Luca Palmieri
Playing around with Rust, at $dayjob and for fun.
Luca Palmieri
cargo-lambda is a Cargo subcommand to help you work with AWS Lambda.

cargo-lambda cargo-lambda is a Cargo subcommand to help you work with AWS Lambda. The new subcommand creates a basic Rust package from a well defined

null 184 Jan 5, 2023
A cargo subcommand that displays the assembly generated for Rust source code

cargo-show-asm A cargo subcommand that displays the assembly generated for Rust source code.

null 193 Dec 29, 2022
Cargo subcommand for optimizing binaries with PGO and BOLT.

cargo-pgo Cargo subcommand that makes it easier to use PGO and BOLT to optimize Rust binaries. Installation $ cargo install cargo-pgo You will also ne

Jakub Beránek 229 Dec 28, 2022
Cargo subcommand to easily bootstrap nocode applications. Write nothing; deploy nowhere.

cargo-nocode No code is the best way to write secure and reliable applications. Write nothing; deploy nowhere. cargo-nocode aims to bring the nocode a

Orhun Parmaksız 29 Jul 1, 2023
Simplified glue code generation for Deno FFI libraries written in Rust.

deno_bindgen This tool aims to simplify glue code generation for Deno FFI libraries written in Rust. Quickstart # install CLI deno install -Afq -n den

Divy Srivastava 173 Dec 17, 2022
Easy to use Rust i18n library based on code generation

rosetta-i18n rosetta-i18n is an easy-to-use and opinionated Rust internationalization (i18n) library powered by code generation. rosetta_i18n::include

null 38 Dec 18, 2022
Fegeya Gretea (aka green tea), new generation programming language.

Fegeya Gretea Gretea (aka green tea), new generation programming language. A taste of Gretea's syntax: import tea.green.fmt module hello { fn hel

Ferhat Geçdoğan 13 Sep 28, 2022
Arkworks bindings to Circom's R1CS, for Groth16 Proof and Witness generation in Rust.

ark-circom Arkworks bindings to Circom's R1CS, for Groth16 Proof and Witness generation in Rust.

Georgios Konstantopoulos 138 Dec 25, 2022
A Rust library for random number generation.

A Rust library for random number generation.

null 1.3k Jan 6, 2023
cargo, make me a project

cargo-generate cargo, make me a project cargo-generate is a developer tool to help you get up and running quickly with a new Rust project by leveragin

null 1.2k Jan 3, 2023
Render cargo dependency tree in online

Cargo Tree Online Check out rendered page Render cargo dependency tree in online. Usage trunk serve Copy and paste the content of Cargo.lock file to

Kangwook Lee (이강욱) 2 Sep 23, 2021
Generate a THIRDPARTY file with all licenses in a cargo project.

cargo-bundle-licenses Bundle all third-party licenses into a single file. NOTE This tools is not a lawyer and no guarantee of correctness can be made

Seth 58 Jan 7, 2023
Rust+Cargo lightweight hello world with the most minimum binary size possible.

Lightweight Cargo Hello World Rust+Cargo lightweight hello world with the most minimum binary size possible. requirements 1: Rustup (Rustc, Cargo) Ins

Raymond 1 Dec 13, 2021
Plugin to request a relaunch when uploading a Skyline plugin through cargo skyline

restart-plugin A skyline plugin for allowing cargo-skyline (or other tools) to restart your game without you having to touch your controller. Install

null 1 Nov 21, 2021
Convenience wrapper for cargo buildscript input/output

A convenience wrapper for cargo buildscript input/output. Why? The cargo buildscript API is (necessarily) stringly-typed.

Christopher Durham 6 Sep 25, 2022
Mommy's here to support you when running cargo~

cargo-mommy Mommy's here to support you when running cargo~ ❤️ Installation Install cargo-mommy like you would any other cargo extension~ > cargo inst

Aria Beingessner 198 Jan 5, 2023
Load and resolve Cargo configuration.

cargo-config2 Load and resolve Cargo configuration. This library is intended to accurately emulate the actual behavior of Cargo configuration, for exa

Taiki Endo 6 Jan 10, 2023
Cargo-BOJ: test and submit solutions to BOJ problems

Cargo-BOJ Test and submit solutions to BOJ (Baekjoon Online Judge) problems. Defaults are geared towards Rust solutions, but non-Rust usage is support

null 5 Apr 3, 2023
Cargo wrapper for working with Webassembly wasi(x).

cargo-wasix A cargo subcommand that wraps regular cargo commands for compiling Rust code to wasix, a superset of Websassembly wasi with additional fun

WASIX 19 Jun 12, 2023