Skip to content
State: Draft

ADR#2228057065

rustcargonamingmacrospackages

Rust package and companion crate naming ​

Context ​

A Cargo package name, a Rust library name, a companion suffix and a feature flag identify different things. Confusing them makes derive, macros and import paths look interchangeable and turns an implementation split into an application-facing naming decision.

Established projects use descriptive companions such as serde_derive, tokio-macros and prost-build. Their spellings demonstrate conventions, not a compiler-enforced suffix. We need a consistent choice for our packages while preserving the names and compatibility contracts consumers already use.

Resolution ​

Package, library and feature identities ​

Canonical spelling and exact directory lookup follow ADR#3522444690. The companion names below use that package, directory and library identity.

Our owned Cargo packages MUST use product-first lower_snake_case, with no hyphens. Keep the product word parts from ADR#3545947886, using this Rust-specific representation where that proposal uses kebab-case. Cargo permits both hyphens and underscores; this stricter spelling is our policy, not a Rust restriction.

A hyphenated package can have an exactly matching hyphenated directory, but its default Rust library name replaces those hyphens with underscores. Using one literal spelling for package, directory and library avoids that normalization when a tool or reader moves between them.

IdentityExampleMeaning
Cargo packageacme_identity[package].name and dependency package identity
Rust libraryacme_identityDefault library target and import path
Workspace directorycrates/acme_identity/Package directory within its workspace
Optional macro featuremacrosCapability selected by the consumer

Workspace placement follows the proposal in ADR#5842232571; a workspace package directory MUST match its Cargo package name exactly. This does not require a crates/ directory in a repository that contains only one package.

Rust permits an explicit [lib].name, but an owned package with a library target MUST keep that name equal to its package name. A dependency alias can still change the consumer's import path without renaming the package or directory. Documentation and generated paths MUST respect that consumer alias.

Choose companions by their purpose ​

The normal library or facade SHOULD keep the base product package name. Create a companion only when there is an actual compilation, dependency or reusability boundary. New companions SHOULD use these purpose-specific names:

PurposePackage exampleRust library name
Derive-only procedural macrosacme_identity_deriveacme_identity_derive
Attribute, function-like or mixed procedural macrosacme_identity_macrosacme_identity_macros
Library supporting generation or setup from build.rsacme_identity_buildacme_identity_build
Raw bindings to a native libraryacme_identity_sysacme_identity_sys

serde_derive provides derive macros; tokio-macros provides attribute and function-like procedural macros. These support the role distinction while showing why our spelling policy is a team choice. prost-build illustrates the build-support role; our suffix is _build. Cargo documents the ecosystem -sys convention for native-library linking and low-level bindings; our suffix is _sys. It MUST NOT label an arbitrary low-level Rust library or a remote-service client.

Names such as _macro_derive SHOULD NOT combine redundant role words. Do not introduce empty companions to complete this table or split every library into _core, _impl, _lib or _runtime by default. Other meaningful parts follow the product naming proposal, such as acme_identity_storage. An exception to a companion suffix SHOULD explain its concrete purpose.

Procedural macros and the public facade ​

Custom derives and other procedural macros are implemented in a proc-macro library and consumed from another crate. For a runtime facade with public types, that requires a separate procedural-macro crate. Rust enforces the crate type and consumption boundary, not the _derive or _macros spelling. Ordinary macro_rules! macros and handwritten trait implementations may remain in the normal library.

The optional public feature MUST be macros for either companion suffix, following ADR#7592933658. A derive-only implementation does not require a public feature named derive or macro_derive. The feature MUST gate the helper dependency and public macro re-exports, while core types and runtime validation remain available without it. A package whose core API is procedural macros does not need a redundant macros feature.

Illustrative facade Cargo.toml:

toml
[package]
name = "acme_identity"
version = "0.1.0"

[features]
default = []
macros = ["dep:acme_identity_derive"]

[dependencies]
acme_identity_derive = { version = "0.1", path = "../acme_identity_derive", optional = true }

Its library re-exports the derive macro:

rust
#[cfg(feature = "macros")]
pub use acme_identity_derive::Identity;

Consumers normally depend on the facade:

toml
[dependencies]
acme_identity = { version = "0.1", default-features = false, features = ["macros"] }

They import through acme_identity. If the consumer names its dependency identity and sets package = "acme_identity", its import path becomes identity. Macro expansion paths MUST support dependency renaming; the package suffix does not determine the consumer's chosen path. Keep the Rust #[derive(...)] syntax unchanged when selecting a Cargo feature name.

The companion runs during compilation; generated implementations can still perform runtime work. A name or re-export alone establishes no allocation or performance guarantee.

Compatibility ​

Owned packages that do not meet this spelling rule require an explicit migration plan; they are not permanently exempt. This documentation MUST NOT trigger unplanned package or source renames. Third-party package names remain unchanged. Adding attribute or function-like macros to an established _derive package does not by itself require renaming that package. Package names, library names, dependency aliases and feature names have distinct compatibility effects. Changes MUST include a consumer and release migration appropriate to their SemVer and registry contracts. Feature compatibility aliases may be retained as described in ADR#7592933658.

The related product, workspace and feature records are separate proposals; this ADR does not change their states or authorize repository-wide renaming.

Except as otherwise noted, the content of this repository is licensed under the Creative Commons Attribution 4.0 License and code samples are licensed under the MIT