{"id":16865989,"url":"https://github.com/lukemathwalker/cargo-px","last_synced_at":"2025-04-05T07:06:55.393Z","repository":{"id":160566042,"uuid":"635390581","full_name":"LukeMathWalker/cargo-px","owner":"LukeMathWalker","description":"A cargo subcommand that extends cargo's capabilities when it comes to code generation.","archived":false,"fork":false,"pushed_at":"2024-11-11T08:48:01.000Z","size":87,"stargazers_count":54,"open_issues_count":5,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-29T06:08:45.091Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://lukemathwalker.github.io/cargo-px/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LukeMathWalker.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-05-02T15:37:13.000Z","updated_at":"2025-01-22T10:06:04.000Z","dependencies_parsed_at":"2024-02-23T19:28:15.856Z","dependency_job_id":"57982557-6413-43c0-b113-569b2fafcb69","html_url":"https://github.com/LukeMathWalker/cargo-px","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LukeMathWalker%2Fcargo-px","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LukeMathWalker%2Fcargo-px/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LukeMathWalker%2Fcargo-px/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LukeMathWalker%2Fcargo-px/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LukeMathWalker","download_url":"https://codeload.github.com/LukeMathWalker/cargo-px/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247299832,"owners_count":20916190,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-13T14:49:05.982Z","updated_at":"2025-04-05T07:06:55.368Z","avatar_url":"https://github.com/LukeMathWalker.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv class=\"oranda-hide\"\u003e\n\u003ch1 align=\"center\"\u003ecargo-px\u003c/h1\u003e\n\u003cdiv align=\"center\"\u003e\n \u003cstrong\u003e\n   Cargo Power eXtensions\n \u003c/strong\u003e\n\u003c/div\u003e\n\n\u003cbr /\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003c!-- Crates version --\u003e\n  \u003ca href=\"https://crates.io/crates/cargo-px\"\u003e\n    \u003cimg src=\"https://img.shields.io/crates/v/cargo-px.svg?style=flat-square\"\n    alt=\"Crates.io version\" /\u003e\n  \u003c/a\u003e\n  \u003c!-- Downloads --\u003e\n  \u003ca href=\"https://crates.io/crates/cargo-px\"\u003e\n    \u003cimg src=\"https://img.shields.io/crates/d/cargo-px.svg?style=flat-square\"\n      alt=\"Download\" /\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\u003cbr/\u003e\n\u003c/div\u003e\n\nCheck out the [announcement post](https://lpalmieri.com/posts/cargo-px) to learn more about `cargo-px` and the problems it solves with respect to code generation in Rust projects.\n\n\n\u003cdiv class=\"oranda-hide\"\u003e\n\n# Table of Contents\n0. [How to install](#how-to-install)\n1. [How to use](#how-to-use)\n2. [Verify that the generated code is up-to-date](#verify-that-the-generated-code-is-up-to-date)\n3. [License](#license)\n4. [Known issues](#known-issues)\n\n## How To Install \n\nCheck out the instructions in the [release page](https://lukemathwalker.github.io/cargo-px/)\n\n\u003c/div\u003e\n\n## How to use\n\nIt is designed as a **`cargo` proxy**: instead of invoking `cargo \u003cCMD\u003e \u003cARGS\u003e`, you go for `cargo px \u003cCMD\u003e \u003cARGS\u003e`. For example, you go for `cargo px build --all-features` instead of `cargo build --all-features`.\n\n`cargo px` examines your workspace every time you invoke it.  \nIf any of your crates needs to be generated, it will invoke the respective code generators before forwarding the command and its arguments to cargo.\n\n`cargo px` leverages the [`metadata` section](https://doc.rust-lang.org/cargo/reference/manifest.html#the-metadata-table).  \nIn the crate that you want to see generated, you fill in the [`package.metadata.px.generate`] section as follows: \n\n```toml\n[package]\nname = \"...\"\nversion = \"...\"\n# [...]\n\n[package.metadata.px.generate]\n# The generator is a binary in the current workspace. \n# It's the only generator type we support at the moment.\ngenerator_type = \"cargo_workspace_binary\"\n# The name of the binary.\ngenerator_name = \"bp\"\n# The arguments to be passed to the binary. \n# It can be omitted if there are no arguments.\ngenerator_args = [\"--quiet\", \"--profile\", \"optimised\"]\n```\n\n`cargo-px` will detect the configuration and invoke `cargo run --bin bp -- --quiet --profile=\"optimised\"` for you.  \nIf 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).\n\n`cargo-px` will also set two environment variables for the code generator:\n\n- `CARGO_PX_GENERATED_PKG_MANIFEST_PATH`, the path to the `Cargo.toml` file of the crate that needs to be generated;\n- `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).\n\nYou can use the [`cargo_px_env`](https://crates.io/crates/cargo_px_env) crate to retrieve and work with these environment variables.\n\n## Verify that the generated code is up-to-date\n\nIf you are committing the generated code, it might be desirable to verify in CI that it's up-to-date.  \nYou can do so by invoking `cargo px verify-freshness`.  \nIt will only work if you define a verifier for every code-generated project in your workspace:\n\n```toml\n[package]\nname = \"...\"\nversion = \"...\"\n# [...]\n\n[package.metadata.px.verify]\n# The verifier is a binary in the current workspace. \n# It's the only verifier type we support at the moment.\nverifier_type = \"cargo_workspace_binary\"\n# The name of the binary.\nverifier_name = \"bp\"\n# The arguments to be passed to the binary. \n# It can be omitted if there are no arguments.\nverifier_args = [\"--verify\"]\n```\n\n`cargo-px` will detect the configuration and invoke `cargo run --bin bp -- --verify\"` for you.  \nThe generated package is considered up-to-date if the verifier invocation returns a `0` status code.\n\nIf there are multiple crates that need to be verified, `cargo-px` will invoke the respective verifier \nin an order that takes into account the dependency graph (i.e. dependencies are always code-generated before their dependents).\n\n`cargo-px` will also set two environment variables for the verifier:\n\n- `CARGO_PX_GENERATED_PKG_MANIFEST_PATH`, the path to the `Cargo.toml` file of the generated crate;\n- `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).\n\nYou can use the [`cargo_px_env`](https://crates.io/crates/cargo_px_env) crate to retrieve and work with these environment variables.\n\n## Known issues\n\n### MacOS\n\nIf you're using a macOS machine, you probably want to [disable gatekeeper notarisation for your terminal](https://apple.stackexchange.com/questions/403184/disable-gatekeeper-notarisation-check-without-disabling-sip/403185#403185).\nQuick guide:\n\n- Run\n  ```bash\n  spctl developer-mode enable-terminal\n  ```\n  from your terminal\n- Then enable it in \"Settings\" -\u003e \"Security \u0026 Privacy\" -\u003e \"Developer Tools\"\n\nEvery time you execute a binary for the first time, Apple [executes a request over the network to their servers](https://sigpipe.macromates.com/2020/macos-catalina-slow-by-design/). 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.  \nThe 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.  \nFun aside: if you're working without an Internet connection, Apple skips the check entirely and lets you execute unverified binaries without complaint.\n\n\n## License\n\nLicensed under either of Apache License, Version 2.0 or MIT license at your option.\nUnless 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukemathwalker%2Fcargo-px","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flukemathwalker%2Fcargo-px","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukemathwalker%2Fcargo-px/lists"}