Skip to main content

cgp v0.8.0

Version 0.8.0 of cgp, the library for Context-Generic Programming (CGP) that enables pluggable trait implementations in Rust, lets a context select whole groups of implementations through namespaces. This page lists every change a user can see and the steps that take a project there from v0.7.0.

Released on 2026-11-18.

Summary​

Namespaces and component paths name groups of wiring that a context joins, in place of the removed presets. The open statement chooses a provider per type in a context's own table, and the Struct! and Enum! macros write a data shape as a declaration. The prelude now exports only the names CGP code writes, and with its default features the library builds without std or an allocator.

Compatibility​

  • Minimum Rust version: 1.89, unchanged from v0.7.0.
  • Released together: the workspace's 29 published crates, all at 0.8.0, and cargo-cgp v0.1.0, CGP's error toolchain, which is released beside this version.
  • New crates: cgp-base-types, cgp-base, and cgp-base-extra, the base layer below cgp-core; cgp-macro-core and cgp-macro-extra-core, the shared cores of the macros; and cgp-macro-test-util with cgp-macro-test-util-lib, the snapshot-testing macros the library's own tests use.
  • Renamed crates: cgp-extra-macro is now cgp-macro-extra, and cgp-extra-macro-lib is now cgp-macro-extra-lib; see the rename.
  • Features: the default features of cgp, cgp-extra, and cgp-error-extra are empty, and cgp gains an alloc feature; see the default features.
  • Dependencies: the macro crates require at least syn 2.0.119, quote 1.0.47, and proc-macro2 1.0.107, up from 2.0.95, 1.0.38, and 1.0.92 (#303). The error backends require at least anyhow 1.0.104 and eyre 0.6.14; see the error backends.

Upgrading​

A project moving from v0.7.0 takes these steps, in this order:

  1. Change the version to cgp = "0.8.0", adding features = ["alloc"] if the wiring uses DebugError or DisplayError, per the default features.
  2. Rename a direct dependency on cgp-extra-macro or cgp-extra-macro-lib, per the rename.
  3. Replace each preset with a configuration namespace or an aggregate provider, per the preset removal.
  4. Rewrite the attribute forms that changed: #[use_type]'s separator and derive_delegate.
  5. Import each name the prelude dropped from its module, writing the English name of each type-level type, per the prelude and the Greek-letter names.
  6. Build the crate, removing the imports the compiler reports as unused and qualifying an ambiguous Struct! or Enum!, per the handler macros and the shape macros.
  7. Update tests that compare output, such as a UI test's expected compiler messages or an assertion on an error backend's report, per the error messages and the error backends.

Breaking changes​

The preset system is removed​

cgp_preset!, #[cgp_inherit], #[wrap_provider], #[cgp::re_export_imports], IsPreset, and the replace_with! macro the presets expanded through are removed (#242). A context could inherit only one preset, while namespaces group wiring through the trait system and nest.

The prelude exports only the names users write​

use cgp::prelude::* brings in the macros and derives, PhantomData, HasErrorType, CanRaiseError, CanWrapError, UseType, UseDelegate, and DefaultNamespace (#294). The code the macros generate goes through cgp::macro_prelude, a module of its own rather than an alias of the prelude, so the prelude no longer carries the generated code's names.

  • Old: the glob also brought in the wiring traits, the field traits, the type-level types, HasType, and the handler family.
  • New: each dropped name is imported from its module: the wiring traits such as DelegateComponent and IsProviderFor from cgp::core::component; the field-access, builder, extractor, and shape traits from cgp::core::field::traits; UseField and the field-state markers from cgp::core::field::impls; Cons, Nil, Either, Void, Field, Index, Life, Chars, and Symbol from cgp::core::field::types; HasType and TypeProvider from cgp::core::types; the handler traits, keys, and promotion bundles from cgp::extra::handler; and the value matchers from cgp::extra::dispatch.
  • What to do: add the import the compiler asks for. A derive still needs no import, so #[derive(HasField)] works through the prelude while a HasField bound or a .get_field() call imports HasField. A #[cgp_impl] provider for a handler trait such as Computer imports ComputerComponent beside the trait.

Raw compiler output names a dropped type through cgp::macro_prelude, such as cgp::macro_prelude::Chars where v0.7.0 printed cgp::prelude::Chars.

#[use_type] separates the trait from its type with a dot​

#[use_type] writes the associated type after a . (#248), and an import from another context names that context after in (#255).

  • Old: #[use_type(HasScalarType::Scalar)], #[use_type(HasErrorType::{Error = AppError})], and #[use_type(@Types::HasScalarType::Scalar)].
  • New: #[use_type(HasScalarType.Scalar)], #[use_type(HasErrorType.{Error = AppError})], and #[use_type(HasScalarType.Scalar in Types)].
  • What to do: rewrite each attribute; the macro rejects the old separator.

derive_delegate is an attribute of its own​

A component that generates a UseDelegate provider writes #[derive_delegate(...)] beneath #[cgp_component], one attribute per dispatch specification (#241).

  • Old: #[cgp_component { provider: AreaCalculator, derive_delegate: UseDelegate<Shape> }].
  • New: #[cgp_component(AreaCalculator)] followed by #[derive_delegate(UseDelegate<Shape>)].
  • What to do: move the key into the attribute. A new component dispatches per type with the open statement instead.

The default features include no allocator​

The default features of cgp, cgp-extra, and cgp-error-extra are empty, and cgp gains an alloc feature that turns on the providers needing an allocator, DebugError and DisplayError (#287).

  • Old: cgp-extra's default full feature turned on cgp-error-extra's alloc, so both providers were always present.
  • New: a crate that wires DebugError or DisplayError writes cgp = { version = "0.8.0", features = ["alloc"] }.

The Greek-letter type names are removed​

The type-level types have only their English names (#243).

  • Old: v0.7.0 declared them under Greek letters with the English names as aliases, and the prelude exported both: Ο€ for Cons, Ξ΅ for Nil, Οƒ for Either, ΞΈ for Void, ΞΆ for Chars, ψ for Symbol, Ξ΄ for Index, and Ο‰ for Field.
  • New: only Cons, Nil, Either, Void, Chars, Symbol, Index, and Field exist, and raw compiler output prints them by these names.
  • What to do: replace a Greek name with its English name, imported from cgp::core::field::types.

The extra-feature macro crates are renamed​

cgp-extra-macro and cgp-extra-macro-lib, which carry #[cgp_computer], #[cgp_producer], and #[cgp_auto_dispatch], are renamed cgp-macro-extra and cgp-macro-extra-lib, beside a new cgp-macro-extra-core (#274). Code that reaches the macros through cgp::prelude is unaffected; a crate that depends on the old crates directly changes its manifest and its cgp_extra_macro:: paths.

The handler macros generate self-contained code​

#[cgp_computer], #[cgp_producer], and #[cgp_auto_dispatch] emit their final code with every name qualified, instead of nested #[cgp_new_provider], delegate_components!, and #[cgp_computer] invocations that resolved through the caller's imports (#274).

  • Unused imports: an import that existed only for the old expansion trips the unused_imports lint; remove it.
  • Computer signatures: the per-variant computers #[cgp_auto_dispatch] generates give each elided argument lifetime its own name, so their impls are more general.
  • Rejected input: #[cgp_auto_dispatch] rejects a typed receiver such as self: Box<Self>, which miscompiled, and an attribute argument, which it ignored.
  • Helper names: its private per-method helper is named __compute_{method}__ (#273), so code that called the undocumented helper by the method's name stops compiling.

Struct! and Enum! join the prelude​

The prelude exports the Struct! and Enum! macros (#276). A module that glob-imports the prelude beside another crate exporting a macro of either name gets an ambiguity error where it uses the name; qualify the call.

The core traits drop their custom error messages​

DelegateComponent, IsProviderFor, HasField, and HasFieldMut no longer carry #[diagnostic::on_unimplemented] messages (#257). Plain cargo check reports an unmet bound on them in rustc's own wording, and cargo cgp check rewrites them. cargo cgp check leads with the root cause for the classes it recognizes, and the tool does not yet reshape every class. A test that compares compiler output updates the messages it expects.

The error backends change their output​

The standalone error backends change behavior (#269, #270).

  • cgp-error-eyre: builds eyre with auto-install, so a report no longer panics when the application has installed no hook with eyre::set_hook, and with track-caller, so a report's location is the line that called raise_error or wrap_error.
  • cgp-error-std: WrapError prints only its detail with {}, and the whole chain with {:#} and {:?}, where v0.7.0 also printed the source inside Display and so repeated it when a reporter walked source(). RaiseBoxedStdError gains an ErrorWrapper impl.
  • Dependencies: the minimum versions rise to anyhow 1.0.104 and eyre 0.6.14.
  • What to do: update assertions on a report's text or location.

New features​

Namespaces and component paths​

A namespace names a group of component wirings that a context joins as a whole (#219, #223, #224, #228). The namespaces concept explains the model.

  • cgp_namespace! defines a namespace, optionally inheriting a parent's entries; a namespace with no entries of its own may omit the braces, as new AppNamespace: DefaultNamespace (#265). See cgp_namespace!.
  • #[prefix(@path in Namespace)] registers a component under a hierarchical path in a namespace. See #[prefix].
  • The namespace statement inside delegate_components! joins a namespace, and an @-path key such as @app.core: CoreComponents delegates every component under the path to one provider. See the namespace statements.
  • The => operator redirects a key's lookup along a path, and the for statement, for <T, Provider> in Table { … }, emits one mapping per entry of another lookup table, which is how a context adopts a namespace's per-type defaults (#228). See the operators.
  • #[default_impl(T in DefaultImpls1<Component>)] registers a #[cgp_impl] provider as a namespace's default for one type (#231). See #[default_impl] and DefaultImpls1.
  • Path! writes a type-level path, and a path groups alternatives with braces or brackets, as @app.[FooComponent, BarComponent] (#241). See Path!.
  • Generic path keys: a path key and a check entry may carry the impl's generic parameters (#226).
  • RedirectLookup is the provider that re-routes a lookup along a path, and DefaultNamespace is the built-in namespace, in the prelude (#219). See RedirectLookup.
  • CGP's own components register in DefaultNamespace: the error components under @cgp.core.error and the handler components under @cgp.extra.handler.

The open statement​

open AreaCalculatorComponent; inside delegate_components! dispatches a generic component per type with @AreaCalculatorComponent.Rectangle: RectangleArea entries, without a namespace or a nested UseDelegate table (#222, #248). A key has one segment per type parameter of the component, so open dispatches on a later parameter too. See the open statement.

Functions and providers​

  • #[impl_generics(Param: Bound)] adds a bounded generic parameter to a #[cgp_fn]'s impl alone, so a body can borrow a generic value without a trait parameter (#221). See #[impl_generics].
  • #[uses] takes any trait bound, such as core::fmt::Debug or a higher-ranked bound, where v0.7.0 took only a trait name with optional generic arguments (#252). See #[uses].
  • A provider header names its key by path: a #[cgp_impl], #[cgp_provider], or #[cgp_new_provider] header that names its trait by path, as impl crate::components::Greeter, derives its component key from the same path, so the module needs no import of the key (#296). See importing the component key.
  • A &str implicit argument borrows any string field: an #[implicit] name: &str argument reads any field whose type implements AsRef<str>, such as String, Box<str>, or Cow<'static, str>, and an Option<&str> argument reads any Option<U> whose U implements AsRef<str>, through the new OptionAsRef trait; neither needs an allocator (#288). See #[implicit].

Data shapes and variants​

  • Struct! and Enum! write a record or variant shape as the body of a struct or enum declaration, and each is the same type #[derive(HasFields)] gives that body (#276, #277). cargo-cgp prints shapes in this form, so a shape read in a diagnostic can be copied into code. See Struct! and Enum!.
  • Fieldless variants: #[derive(CgpVariant)], CgpData, ExtractField, and FromVariant accept a variant written Closed, Closed(), or Closed {}, with the payload Nil, where v0.7.0 rejected such a variant and the workaround was a () payload (#278). The mutable extractor builds its &mut Nil with Box::leak, so a no_std crate deriving it has Box in scope.

Building without std​

With its default features, cgp needs neither std nor alloc, and builds for a target such as x86_64-unknown-none (#287). The alloc feature turns on DebugError and DisplayError. The error backends keep their requirements: cgp-error-anyhow and cgp-error-std need alloc, and cgp-error-eyre needs std.

Improvements​

Documentation​

  • Generated items carry documentation: every macro that declares a public item gives it a doc line when the user wrote none, so a crate can enable #![warn(missing_docs)] (#286). A user's own doc is kept, and a #[cgp_fn] function's doc lands on the generated trait's method.
  • A provider trait names its key: each provider trait's doc ends by naming its component key, so an editor's hover on the trait shows the key a provider imports beside it (#296).
  • Every crate is documented: each published crate's docs.rs page says what the crate provides and links the website's page for each construct, and every public item has a doc comment. docs.rs builds each crate with every feature, and most crates' READMEs, which double as their crate documentation, show a short program using the crate's main construct (#284, #285, #289, #302).
  • Crate metadata: each crate names its description, the project's homepage, five keywords, and the rust-patterns and no-std categories on crates.io (#259, #267).

Diagnostics​

  • Errors point at the code the user wrote: an error about a data derive's generated impl, such as a coherence conflict between two #[derive(HasField)] fields, points at the field or variant (#260); a -> entry's missing-key error points at the entry rather than the whole delegate_components! block (#281); and a provider header's missing key is reported on the trait's name (#296).
  • Malformed input gets the macro's own message, spanned on the input, where it used to fail inside generated code or with an internal parse error (#273, #274, #281):
    • a #[cgp_component] name: parameter the trait does not declare, and a const generic in a component's name;
    • #[uses] on a component trait, with the #[extend(...)] form to write;
    • a component method parameter written as _ or a destructuring pattern;
    • a #[cgp_computer] type or const parameter that only the return type uses;
    • impl Trait in a #[cgp_computer] or #[cgp_producer] signature, and a one-argument Result<T> alias, with the Result<T, E> form they require;
    • an Option<&[T]> or Option<&dyn Trait> getter or implicit argument, with the sized field type to read instead.
  • #[use_type] grounds every alias: an imported alias resolves inside an equality pin's right-hand side, in an expression path such as Transaction::begin_from(pool), and in the imported trait's own generic arguments; a pin on a generic trait builds a valid bound; and two imports whose contexts resolve through each other are rejected, naming the cycle (#264).
  • Fully qualified expansions: every conversion and field read the macros emit is a fully qualified trait call, so a local trait named like AsRef or HasField cannot capture it (#288).

Errors​

  • #[track_caller] on raising and wrapping: CanRaiseError::raise_error and CanWrapError::wrap_error are #[track_caller], and #[cgp_component] copies the attribute onto the provider trait, so an error library that records Location::caller() sees the line that called raise_error (#270). See CanRaiseError.

Fixes​

Providers and components​

  • Self::CONST in a provider: inside a #[cgp_impl] block, Self::LIMIT names a const the block declares, and in a component's default body it names the trait's own const, where v0.7.0 failed with E0599 (#281).
  • mut parameters: a component method may take a mut parameter or a mut self receiver, which made v0.7.0's macro panic, and the forwarding impls drop the mut so the build raises no unused_mut warning (#281).
  • #[async_trait] default bodies: an async fn with a default body compiles, because the macro wraps the body in async move, where v0.7.0 failed with E0277: `{integer}` is not a future (#281). See #[async_trait].
  • Self in a provider header: a #[cgp_impl] header such as impl Comparer<Self> reads Self in the trait's arguments as the context, where v0.7.0 failed with E0053 (#225).
  • Unsized parameters: a component used at an unsized parameter, such as HasReference<'a, str>, resolves through delegate_components!, where a call through the context failed with E0599 (#273).

Wiring and checking​

  • #[check_providers] on a generic table: a check_components! table such as <T> Wrapper<T> with #[check_providers(...)] compiles, where it failed with E0425 and E0207 (#273). See check_components!.
  • const table parameters: a table struct that delegate_components! declares, as a new target or a nested table, keeps its const parameters (#273).

Data derives​

  • Reserved variant names: an enum may name a variant Value, Remainder, Extractor, ExtractorRef, ExtractorMut, Fields, or FieldsRef and still derive the variant traits, where v0.7.0 failed with an ambiguous associated item (#281).

  • Helper attributes: a type that combines the data derives with another derive's helper attribute, such as #[default] or #[serde(...)], builds, because the builder and extractor companions keep only each field's and variant's documentation (#281).

  • Empty enums: #[derive(CgpData)] on an enum with no variants compiles, where v0.7.0 failed with E0392 on an unused lifetime (#250).

Handler macros​

  • Without the prelude: #[cgp_computer], #[cgp_producer], and #[cgp_auto_dispatch] work when invoked by path in a module that imports nothing from cgp, and beside a local item named like a CGP trait (#274).
  • #[cgp_auto_dispatch] lifetimes: a named receiver lifetime, a trait lifetime parameter, a reference nested in another type, and an argument outlived by the returned borrow compile, because the macro names a method's elided lifetimes by the compiler's elision rules (#274).
  • #[cgp_auto_dispatch] supertraits: a dispatch trait with a supertrait compiles, and the enum is required to implement the supertrait (#274).
  • #[cgp_auto_dispatch] names: its generated function no longer collides with a module item of the same name, and a method named with a raw identifier such as r#type no longer panics the macro (#273).
  • #[cgp_auto_dispatch] beside CanCompute: the generated method names the matcher's provider trait, so a module that imports CanCompute no longer fails with E0034 (#268).
  • Raw function names: #[cgp_computer] and #[cgp_producer] accept a function named with a raw identifier, which made them panic (#274).

An AI agent wrote this page from the release's source changes and the CGP knowledge base. Its content was verified against the library's source at the release's tag. See How AI is used in this project.