cargo-cgp
cargo-cgp helps you understand compile errors and macro expansions in
Context-Generic Programming (CGP) code. CGP extends Rust with pluggable trait
implementations through macros that generate ordinary Rust traits, so a compiler error may name
that generated machinery while leaving the failed requirement unclear. Running cargo cgp check
brings the root cause forward for failures the tool recognizes.
You can keep using ordinary cargo commands alongside it. CGP is a library on stable Rust, so
cargo check, cargo build, and cargo test work without the tool. Reach for cargo-cgp when
you need help understanding an error or a macro expansion.
The problem it solves
A wiring entry can select a provider even when its context lacks a dependency. The
delegate_components! table records the choice,
and Rust checks whether it works when the trait is required later. At that later call site, the
compiler can report unsatisfied bounds without exposing the dependency that failed.
For example, this table selects RectangleArea for Rectangle. The provider obtains width
and height through #[implicit] arguments, but the
context supplies only width:
use cgp::prelude::*;
#[cgp_component(AreaCalculator)]
pub trait CanCalculateArea {
fn area(&self) -> f64;
}
#[cgp_impl(new RectangleArea)]
impl AreaCalculator {
fn area(&self, #[implicit] width: f64, #[implicit] height: f64) -> f64 {
width * height
}
}
#[derive(HasField)]
pub struct Rectangle {
pub width: f64,
// missing `height` field
}
delegate_components! {
Rectangle {
AreaCalculatorComponent: RectangleArea,
}
}
pub fn print_area(rectangle: &Rectangle) {
println!("{}", rectangle.area());
}
Plain cargo check on stable Rust reports the call to area:
error[E0599]: the method `area` exists for reference `&Rectangle`, but its trait bounds were not satisfied
--> src/lib.rs:28:30
|
16 | pub struct Rectangle {
| -------------------- doesn't satisfy `Rectangle: AreaCalculator<Rectangle>` or `Rectangle: CanCalculateArea`
...
28 | println!("{}", rectangle.area());
| ^^^^ this is an associated function, not a method
|
= note: found the following associated functions; to be used as methods, functions must have a `self` parameter
note: the candidate is defined in the trait `AreaCalculator`
--> src/lib.rs:5:5
|
5 | fn area(&self) -> f64;
| ^^^^^^^^^^^^^^^^^^^^^^
note: the following trait bounds were not satisfied:
`&Rectangle: AreaCalculator<&Rectangle>`
`Rectangle: AreaCalculator<Rectangle>`
--> src/lib.rs:3:1
|
3 | #[cgp_component(AreaCalculator)]
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4 | pub trait CanCalculateArea {
| ^^^^^^^^^^^^^^^^
note: the trait `AreaCalculator` must be implemented
--> src/lib.rs:4:1
|
4 | / pub trait CanCalculateArea {
5 | | fn area(&self) -> f64;
6 | | }
| |_^
= help: items from traits can only be used if the trait is implemented and in scope
note: `CanCalculateArea` defines an item `area`, perhaps you need to implement it
--> src/lib.rs:4:1
|
4 | pub trait CanCalculateArea {
| ^^^^^^^^^^^^^^^^^^^^^^^^^^
= note: this error originates in the attribute macro `cgp_component` (in Nightly builds, run with -Z macro-backtrace for more info)
help: use associated function syntax instead
|
28 - println!("{}", rectangle.area());
28 + println!("{}", Rectangle::area());
|
For more information about this error, try `rustc --explain E0599`.
Nothing in this message names height. Instead, it reports the generated trait bounds and
suggests calling Rectangle::area(), which would address a different problem. The missing field
never reached the diagnostic because the compiler set the candidate implementation aside before
working out why it did not apply.
cargo cgp check reports the same mistake like this:
error[E0599]: [CGP-E001] missing field `height` on `Rectangle`
--> src/lib.rs:28:30
|
28 | println!("{}", rectangle.area());
| ^^^^
|
= note: root cause: [CGP-E110] missing field `height` on `Rectangle`
this is required through the dependency chain:
[CGP-E101] consumer trait impl `CanCalculateArea` for context `Rectangle`
└─ [CGP-E102] provider trait impl `AreaCalculator` with context `Rectangle` for provider `RectangleArea`
└─ [CGP-E110] missing field `height` on `Rectangle`
= help: add the field `height: f64` to `Rectangle`
For more information about this error, try `rustc --explain E0599`.
The rewritten headline identifies height immediately. Below it, the tree connects the call
to the provider and its field requirement, followed by a suggested fix. The compiler's code and
source position stay in place, as Reading the output explains in more detail.
How it works
To produce this message, the tool first checks the program with Rust's next-generation trait
solver. Where the default solver stops at unsatisfied method bounds, this solver follows the
requirement down to the missing HasField bound. That gives the tool a cause it can report.
The tool then rewrites the failures it recognizes, naming the cause, drawing the dependency chain,
and adding a [CGP-Exxx] code for the class of mistake. It retains the compiler's code so
rustc --explain still applies. Errors it does not recognize pass through as the compiler wrote them.
The two commands
For a wiring error, cargo cgp check is usually the command to reach for.
It accepts the arguments you would pass to cargo check, so you can keep the same package,
workspace, and feature selections.
If you need to inspect the generated implementation, use cargo cgp expand.
It prints the macro expansion with CGP's type-level constructs in their familiar forms.
For example, a field tag appears as Symbol!("height"), making the name readable without
following a list of character types.
What it costs
To make those diagnostics available, setup downloads one exact nightly and builds the driver against its compiler libraries. The toolchain occupies more than a gigabyte, so installation has a cost in both time and disk space. That nightly belongs to the tool's diagnostic pass; your project keeps its own toolchain.
Checking under that nightly also needs a separate build. The tool puts its artifacts in
target/cgp, so the first run compiles every dependency again and uses additional disk space.
Later checks reuse those artifacts alongside your normal build output.
CGP's agent skill can help a coding assistant run the check and interpret its output. You still need to review the diagnosis and proposed change yourself.
What it does not do
For building, running, and testing, keep using ordinary cargo. The tool provides no
cargo cgp build, run, or test commands, and CGP itself compiles on stable Rust 1.89 or newer.
Because this diagnostic pass uses its own compiler and trait solver, its result can differ from
your project's check. Treat it as you would a Clippy run under separate settings, and keep your
own toolchain's cargo check as the authority on whether the code builds.
Its diagnostic coverage has limits too. cargo cgp check leads with the root cause for the classes it
recognizes, and the tool does not yet reshape every class.
Reading the output identifies common
cases that pass through and points to their explanations. Rewriting also applies only to crates
inside your workspace.
Finally, the tool is tested on Linux. macOS and Windows have not been tested yet.
Where to go next
Start with installation, then go to the page for what you want to do:
- Installation: installing with cargo or Nix, checking the install, updating, and uninstalling.
- Check: running a check, and trying it on a deliberate mistake.
- Reading the output: the shapes of error the tool produces, part by part.
- Expand: reading what your CGP macros generated.
- Editor integration: rewritten errors in VS Code, every time you save.
- Troubleshooting: when the tool itself will not run.
- Error codes and Command reference: to look something up.
For a guided walk through one mistake, from the raw error to the fix, the area-calculation tutorial's checking part uses the tool on a program it builds up step by step.
An AI agent wrote this page using the CGP knowledge base, and its outputs were produced by running the commands. See How AI is used in this project.