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.
- Release post: CGP v0.8.0 - cargo-cgp, new documentation, and namespaces
- Crate:
cgp0.8.0 on crates.io - Changes: v0.7.0...v0.8.0
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-cgpv0.1.0, CGP's error toolchain, which is released beside this version. - New crates:
cgp-base-types,cgp-base, andcgp-base-extra, the base layer belowcgp-core;cgp-macro-coreandcgp-macro-extra-core, the shared cores of the macros; andcgp-macro-test-utilwithcgp-macro-test-util-lib, the snapshot-testing macros the library's own tests use. - Renamed crates:
cgp-extra-macrois nowcgp-macro-extra, andcgp-extra-macro-libis nowcgp-macro-extra-lib; see the rename. - Features: the default features of
cgp,cgp-extra, andcgp-error-extraare empty, andcgpgains anallocfeature; see the default features. - Dependencies: the macro crates require at least
syn2.0.119,quote1.0.47, andproc-macro21.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:
- Change the version to
cgp = "0.8.0", addingfeatures = ["alloc"]if the wiring usesDebugErrororDisplayError, per the default features. - Rename a direct dependency on
cgp-extra-macroorcgp-extra-macro-lib, per the rename. - Replace each preset with a configuration namespace or an aggregate provider, per the preset removal.
- Rewrite the attribute forms that changed:
#[use_type]'s separator andderive_delegate. - 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.
- Build the crate, removing the imports the compiler reports as unused and qualifying an
ambiguous
Struct!orEnum!, per the handler macros and the shape macros. - 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.
- Shared fixed choices: a preset's provider choices become a configuration namespace, defined
with
cgp_namespace!and joined with anamespacestatement in the context'sdelegate_components!. - A selectable group: a group that configurations swap becomes an
aggregate provider, selected through an
@-path key. - Migration: the release post works one preset through to a namespace, with its component checks, in Replace presets with namespace configuration.
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
DelegateComponentandIsProviderForfromcgp::core::component; the field-access, builder, extractor, and shape traits fromcgp::core::field::traits;UseFieldand the field-state markers fromcgp::core::field::impls;Cons,Nil,Either,Void,Field,Index,Life,Chars, andSymbolfromcgp::core::field::types;HasTypeandTypeProviderfromcgp::core::types; the handler traits, keys, and promotion bundles fromcgp::extra::handler; and the value matchers fromcgp::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 aHasFieldbound or a.get_field()call importsHasField. A#[cgp_impl]provider for a handler trait such asComputerimportsComputerComponentbeside 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
openstatement 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 defaultfullfeature turned oncgp-error-extra'salloc, so both providers were always present. - New: a crate that wires
DebugErrororDisplayErrorwritescgp = { 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:
ΟforCons,Ξ΅forNil,ΟforEither,ΞΈforVoid,ΞΆforChars,ΟforSymbol,Ξ΄forIndex, andΟforField. - New: only
Cons,Nil,Either,Void,Chars,Symbol,Index, andFieldexist, 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_importslint; 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 asself: 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 withauto-install, so a report no longer panics when the application has installed no hook witheyre::set_hook, and withtrack-caller, so a report's location is the line that calledraise_errororwrap_error.cgp-error-std:WrapErrorprints only its detail with{}, and the whole chain with{:#}and{:?}, where v0.7.0 also printed the source insideDisplayand so repeated it when a reporter walkedsource().RaiseBoxedStdErrorgains anErrorWrapperimpl.- 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, asnew AppNamespace: DefaultNamespace(#265). Seecgp_namespace!.#[prefix(@path in Namespace)]registers a component under a hierarchical path in a namespace. See#[prefix].- The
namespacestatement insidedelegate_components!joins a namespace, and an@-path key such as@app.core: CoreComponentsdelegates every component under the path to one provider. See the namespace statements. - The
=>operator redirects a key's lookup along a path, and theforstatement,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]andDefaultImpls1.Path!writes a type-level path, and a path groups alternatives with braces or brackets, as@app.[FooComponent, BarComponent](#241). SeePath!.- Generic path keys: a path key and a check entry may carry the impl's generic parameters (#226).
RedirectLookupis the provider that re-routes a lookup along a path, andDefaultNamespaceis the built-in namespace, in the prelude (#219). SeeRedirectLookup.- CGP's own components register in
DefaultNamespace: the error components under@cgp.core.errorand 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 ascore::fmt::Debugor 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, asimpl 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
&strimplicit argument borrows any string field: an#[implicit] name: &strargument reads any field whose type implementsAsRef<str>, such asString,Box<str>, orCow<'static, str>, and anOption<&str>argument reads anyOption<U>whoseUimplementsAsRef<str>, through the newOptionAsReftrait; neither needs an allocator (#288). See#[implicit].
Data shapes and variantsβ
Struct!andEnum!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-cgpprints shapes in this form, so a shape read in a diagnostic can be copied into code. SeeStruct!andEnum!.- Fieldless variants:
#[derive(CgpVariant)],CgpData,ExtractField, andFromVariantaccept a variant writtenClosed,Closed(), orClosed {}, with the payloadNil, where v0.7.0 rejected such a variant and the workaround was a()payload (#278). The mutable extractor builds its&mut NilwithBox::leak, so ano_stdcrate deriving it hasBoxin 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
#. 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-patternsandno-stdcategories 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 wholedelegate_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 aconstgeneric 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 Traitin a#[cgp_computer]or#[cgp_producer]signature, and a one-argumentResult<T>alias, with theResult<T, E>form they require;- an
Option<&[T]>orOption<&dyn Trait>getter or implicit argument, with the sized field type to read instead.
- a
#[use_type]grounds every alias: an imported alias resolves inside an equality pin's right-hand side, in an expression path such asTransaction::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
AsReforHasFieldcannot capture it (#288).
Errorsβ
#[track_caller]on raising and wrapping:CanRaiseError::raise_errorandCanWrapError::wrap_errorare#[track_caller], and#[cgp_component]copies the attribute onto the provider trait, so an error library that recordsLocation::caller()sees the line that calledraise_error(#270). SeeCanRaiseError.
Fixesβ
Providers and componentsβ
Self::CONSTin a provider: inside a#[cgp_impl]block,Self::LIMITnames a const the block declares, and in a component's default body it names the trait's own const, where v0.7.0 failed withE0599(#281).mutparameters: a component method may take amutparameter or amut selfreceiver, which made v0.7.0's macro panic, and the forwarding impls drop themutso the build raises nounused_mutwarning (#281).#[async_trait]default bodies: anasync fnwith a default body compiles, because the macro wraps the body inasync move, where v0.7.0 failed withE0277: `{integer}` is not a future(#281). See#[async_trait].Selfin a provider header: a#[cgp_impl]header such asimpl Comparer<Self>readsSelfin the trait's arguments as the context, where v0.7.0 failed withE0053(#225).- Unsized parameters: a component used at an unsized parameter, such as
HasReference<'a, str>, resolves throughdelegate_components!, where a call through the context failed withE0599(#273).
Wiring and checkingβ
#[check_providers]on a generic table: acheck_components!table such as<T> Wrapper<T>with#[check_providers(...)]compiles, where it failed withE0425andE0207(#273). Seecheck_components!.consttable parameters: a table struct thatdelegate_components!declares, as anewtarget or a nested table, keeps itsconstparameters (#273).
Data derivesβ
-
Reserved variant names: an enum may name a variant
Value,Remainder,Extractor,ExtractorRef,ExtractorMut,Fields, orFieldsRefand 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 withE0392on 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 fromcgp, 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 asr#typeno longer panics the macro (#273).#[cgp_auto_dispatch]besideCanCompute: the generated method names the matcher's provider trait, so a module that importsCanComputeno longer fails withE0034(#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.