From 51c8c1270842c03bbac7604974dac4c340e9cc13 Mon Sep 17 00:00:00 2001 From: Jane Losare-Lusby Date: Mon, 13 Oct 2025 13:57:28 -0700 Subject: [PATCH 01/12] Add section on expansion-time (early) name resolution Co-authored-by: Vadim Petrochenkov Co-authored-by: Eric Huss Co-authored-by: Tshepang Mbambo Co-authored-by: Travis Cross --- src/glossary.md | 1 + src/items/use-declarations.md | 67 +----- src/macros-by-example.md | 82 ++++++- src/macros.md | 14 +- src/names/name-resolution.md | 418 +++++++++++++++++++++++++++++++++- src/names/namespaces.md | 64 +++--- src/procedural-macros.md | 19 ++ 7 files changed, 575 insertions(+), 90 deletions(-) diff --git a/src/glossary.md b/src/glossary.md index fd865dcc4d..c6c1656b88 100644 --- a/src/glossary.md +++ b/src/glossary.md @@ -1,5 +1,6 @@ # Glossary +r[glossary.ast] ### Abstract syntax tree An ‘abstract syntax tree’, or ‘AST’, is an intermediate representation of diff --git a/src/items/use-declarations.md b/src/items/use-declarations.md index 94638b6a12..71661d6cc0 100644 --- a/src/items/use-declarations.md +++ b/src/items/use-declarations.md @@ -116,6 +116,7 @@ They may create bindings for: * [Built-in types] * [Attributes] * [Derive macros] +* [`macro_rules`] r[items.use.path.disallowed] They cannot import [associated items], [generic parameters], [local variables], paths with [`Self`], or [tool attributes]. More restrictions are described below. @@ -302,6 +303,10 @@ mod clashing { } ``` +> [!NOTE] +> +> For areas where shadowing is not allowed, see [name resolution ambiguities]. + r[items.use.glob.last-segment-only] `*` cannot be used as the first or intermediate segments. @@ -389,71 +394,19 @@ r[items.use.restrictions.variant] use TypeAlias::MyVariant; //~ ERROR ``` -r[items.use.ambiguities] -## Ambiguities - -> [!NOTE] -> This section is incomplete. - -r[items.use.ambiguities.intro] -Some situations are an error when there is an ambiguity as to which name a `use` declaration refers. This happens when there are two name candidates that do not resolve to the same entity. - -r[items.use.ambiguities.glob] -Glob imports are allowed to import conflicting names in the same namespace as long as the name is not used. -For example: - -```rust -mod foo { - pub struct Qux; -} - -mod bar { - pub struct Qux; -} - -use foo::*; -use bar::*; //~ OK, no name conflict. - -fn main() { - // This would be an error, due to the ambiguity. - //let x = Qux; -} -``` - -Multiple glob imports are allowed to import the same name, and that name is allowed to be used, if the imports are of the same item (following re-exports). The visibility of the name is the maximum visibility of the imports. For example: - -```rust -mod foo { - pub struct Qux; -} - -mod bar { - pub use super::foo::Qux; -} - -// These both import the same `Qux`. The visibility of `Qux` -// is `pub` because that is the maximum visibility between -// these two `use` declarations. -pub use bar::*; -use foo::*; - -fn main() { - let _: Qux = Qux; -} -``` - -[`extern crate`]: extern-crates.md -[`macro_rules`]: ../macros-by-example.md -[`self`]: ../paths.md#self -[associated items]: associated-items.md [Attributes]: ../attributes.md [Built-in types]: ../types.md [Derive macros]: macro.proc.derive [Enum variants]: enumerations.md +[`extern crate`]: extern-crates.md +[`macro_rules`]: ../macros-by-example.md +[`self`]: ../paths.md#self +[associated items]: associated-items.md [extern prelude]: ../names/preludes.md#extern-prelude [generic parameters]: generics.md [items]: ../items.md [local variables]: ../variables.md +[name resolution ambiguities]: names.resolution.expansion.imports.ambiguity [namespace]: ../names/namespaces.md [namespaces]: ../names/namespaces.md [paths]: ../paths.md diff --git a/src/macros-by-example.md b/src/macros-by-example.md index 2fa104ed4d..64a89286b7 100644 --- a/src/macros-by-example.md +++ b/src/macros-by-example.md @@ -326,6 +326,77 @@ fn foo() { // m!(); // Error: m is not in scope. ``` +r[macro.decl.scope.textual.shadow.path-based] +Textual scope name bindings for macros shadow path-based scope bindings to macros. + +```rust +#[macro_export] +macro_rules! m2 { + () => { + println!("m2"); + }; +} + +m!(); // prints "m2\n" + +macro_rules! m { + () => { + println!("m"); + }; +} + +use crate::m2 as m; + +m!(); // prints "m\n" +``` + +> [!NOTE] +> +> For areas where shadowing is not allowed, see [name resolution ambiguities]. + +r[macro.decl.scope.path-based] +### Path-based scope + +r[macro.decl.scope.path-based.intro] +By default, a macro has no path-based scope. Macros can gain path-based scope in two ways: + +* [Use declaration re-export] +* [`macro_export`] + +r[macro.decl.scope.path.reexport] +Macros can be re-exported to give them path-based scope from a module other than the crate root. + +```rust +mac::m!(); // OK: Path-based lookup finds m in the mac module. + +mod mac { + macro_rules! m { + () => {}; + } + pub(crate) use m; +} +``` + +r[macro.decl.scope.path-based.visibility] +Macros have an implicit visibility of `pub(crate)`. `#[macro_export]` changes the implicit visibility to `pub`. + +```rust,compile_fail,E0364 +macro_rules! private_m { + () => {}; +} + +#[macro_export] +macro_rules! pub_m { + () => {}; +} + +pub(crate) use private_m as private_macro; // OK +pub use pub_m as pub_macro; // OK + +pub use private_m; // ERROR: `private_m` is only public within + // the crate and cannot be re-exported outside +``` + r[macro.decl.scope.macro_use] ### The `macro_use` attribute @@ -713,14 +784,17 @@ expansions, taking separators into account. This means: For more detail, see the [formal specification]. +[Hygiene]: #hygiene +[Metavariables]: #metavariables +[Repetitions]: #repetitions +[Use declaration re-export]: items/use-declarations.md#use-visibility +[`macro_export`]: #the-macro_export-attribute +[`$crate`]: macro.decl.hygiene.crate [`extern crate self`]: items.extern-crate.self [`macro_use` prelude]: names/preludes.md#macro_use-prelude [block labels]: expr.loop.block-labels [delimiters]: tokens.md#delimiters [formal specification]: macro-ambiguity.md -[Hygiene]: #hygiene [loop labels]: expressions/loop-expr.md#loop-labels -[Metavariables]: #metavariables -[Repetitions]: #repetitions +[name resolution ambiguities]: names/name-resolution.md#r-names.resolution.expansion.imports.ambiguity [token]: tokens.md -[`$crate`]: macro.decl.hygiene.crate diff --git a/src/macros.md b/src/macros.md index 36287e0d4a..1cd902034a 100644 --- a/src/macros.md +++ b/src/macros.md @@ -106,15 +106,25 @@ macro_rules! example { example!(); ``` +r[macro.invocation.name-resolution] + +Macros invocations can be resolved via two kinds of scopes: + +* Textual Scope + * [Textual scope `macro_rules`](macros-by-example.md#r-macro.decl.scope.textual) +* Path-based scope + * [Path-based scope `macro_rules`](macros-by-example.md#r-macro.decl.scope.path-based) + * [Procedural macros] + +[External blocks]: items/external-blocks.md [Macros by Example]: macros-by-example.md [Procedural Macros]: procedural-macros.md +[`macro_rules`]: macros-by-example.md [associated items]: items/associated-items.md [delimiters]: tokens.md#delimiters [expressions]: expressions.md [items]: items.md -[`macro_rules`]: macros-by-example.md [patterns]: patterns.md [statements]: statements.md [types]: types.md [visibility qualifiers]: visibility-and-privacy.md -[External blocks]: items/external-blocks.md diff --git a/src/names/name-resolution.md b/src/names/name-resolution.md index da60d7eb32..4c46151742 100644 --- a/src/names/name-resolution.md +++ b/src/names/name-resolution.md @@ -1,4 +1,420 @@ +r[names.resolution] # Name resolution +r[names.resolution.intro] +_Name resolution_ is the process of tying paths and other identifiers to the declarations of those entities. Names are segregated into different [namespaces], allowing entities in different namespaces to share the same name without conflict. Each name is valid within a [scope], or a region of source text where that name may be referenced. Access to a name may be restricted based on its [visibility]. + +Name resolution is split into three stages throughout the compilation process. The first stage, *expansion-time resolution*, resolves all [`use` declarations] and [macro invocations]. The second stage, *primary resolution*, resolves all names that have not yet been resolved and that do not depend on type information to resolve. The last stage, *type-relative resolution*, resolves the remaining names once type information is available. + +> [!NOTE] +> Expansion-time resolution is also known as *early resolution*. Primary resolution is also known as *late resolution*. + +r[names.resolution.general] +## General + +r[names.resolution.general.intro] +The rules within this section apply to all stages of name resolution. + +r[names.resolution.general.scopes] +### Scopes + +r[names.resolution.general.scopes.intro] > [!NOTE] -> This is a placeholder for future expansion. +> This is a placeholder for future expansion about resolution of names within various scopes. + +r[names.resolution.expansion] +## Expansion-time name resolution + +r[names.resolution.expansion.intro] +Expansion-time name resolution is the stage of name resolution necessary to complete macro expansion and fully generate a crate's [AST]. This stage requires the resolution of macro invocations and `use` declarations. Resolving `use` declarations is required for macro invocations that resolve via [path-based scope]. Resolving macro invocations is required in order to expand them. + +r[names.resolution.expansion.unresolved-invocations] +After expansion-time name resolution, the AST must not contain any unexpanded macro invocations. Every macro invocation resolves to a valid definition that exists in the final AST or in an external crate. + +```rust,compile_fail +m!(); // ERROR: Cannot find macro `m` in this scope. +``` + +r[names.resolution.expansion.expansion-order-stability] +The resolution of names must be stable. After expansion, names in the fully expanded AST must resolve to the same definition regardless of the order in which macros are expanded and imports are resolved. + +r[names.resolution.expansion.speculation] +All name resolution candidates selected during macro expansion are considered speculative. Once the crate has been fully expanded, all speculative import resolutions are validated to ensure that macro expansion did not introduce any new ambiguities. + +> [!NOTE] +> Due to the iterative nature of macro expansion, this causes so-called time traveling ambiguities, such as when a macro or glob import introduces an item that is ambiguous with its own base path. +> +> ```rust,compile_fail,E0659 +> # fn main() {} +> macro_rules! f { +> () => { +> mod m { +> pub(crate) use f; +> } +> } +> } +> f!(); +> +> const _: () = { +> // Initially, we speculatively resolve `m` to the module in +> // the crate root. +> // +> // Expansion of `f` introduces a second `m` module inside this +> // body. +> // +> // Expansion-time resolution finalizes resolutions by re- +> // resolving all imports and macro invocations, sees the +> // introduced ambiguity and reports it as an error. +> m::f!(); // ERROR: `m` is ambiguous. +> }; +> ``` + +r[names.resolution.expansion.imports] +### Imports +r[names.resolution.expansion.imports.intro] +All `use` declarations are fully resolved during this stage of resolution. [Type-relative paths] cannot be resolved at this stage and will produce an error. + +```rust +mod m { + pub const C: () = (); + pub enum E { V } + pub type A = E; + impl E { + pub const C: () = (); + } +} + +// Valid imports resolved at expansion-time: +use m::C; // OK. +use m::E; // OK. +use m::A; // OK. +use m::E::V; // OK. + +// Valid expressions resolved during type-relative resolution: +let _ = m::A::V; // OK. +let _ = m::E::C; // OK. +``` + +```rust,compile_fail,E0432 +# mod m { +# pub const C: () = (); +# pub enum E { V } +# pub type A = E; +# impl E { +# pub const C: () = (); +# } +# } +// Invalid type-relative imports that can't resolve at expansion-time: +use m::E::C; // ERROR: Unresolved import `m::E::C`. +use m::A::V; // ERROR: Unresolved import `m::A::V`. +``` + +r[names.resolution.expansion.imports.shadowing] +Names introduced via `use` declarations in an [outer scope] are shadowed by +candidates in the same namespace with the same name from an inner scope except +where otherwise restricted by [name resolution ambiguities]. + +```rust +pub mod foo { + pub mod baz { + pub struct Name; + } +} + +pub mod bar { + pub mod baz { + pub struct Name(pub ()); + } +} + +use foo::baz; +fn f() { + use bar::baz; + use baz::Name; + Name(()); +} +``` + +r[names.resolution.expansion.imports.shadowing.shared-scope] +Shadowing of names introduced via `use` declarations within a single scope is permitted in the following situations: + +- [`use` glob shadowing] +- [Macro textual scope shadowing] + +r[names.resolution.expansion.imports.ambiguity] +#### Ambiguities + +r[names.resolution.expansion.imports.ambiguity.intro] +Some situations are an error when there is an ambiguity as to which macro definition, `use` declaration, or module an import or macro invocation's name refers to. This happens when there are two name candidates that do not resolve to the same entity where neither candidate is [permitted] to shadow the other. + +r[names.resolution.expansion.imports.ambiguity.glob-vs-glob] +Names may not be resolved through ambiguous glob imports. Glob imports are allowed to import conflicting names in the same namespace as long as the name is not used. Names with conflicting candidates from ambiguous glob imports may still be shadowed by non glob imports and used without producing an error. The errors occur at time of use, not time of import. + +For example: + +```rust +mod foo { + pub struct Qux; +} + +mod bar { + pub struct Qux; +} + +use foo::*; +use bar::*; // OK, no name conflict. + +fn ambiguous_use() { + // This would be an error, due to the ambiguity. + //let x = Qux; +} + +fn ambiguous_shadow() { + // This is permitted, since resolution is not through the ambiguous globs. + struct Qux; + let x = Qux; +} +``` + +Multiple glob imports are allowed to import the same name, and that name is allowed to be used if the imports are of the same item (following re-exports). The visibility of the name is the maximum visibility of the imports. For example: + +```rust +mod foo { + pub struct Qux; +} + +mod bar { + pub use super::foo::Qux; +} + +// These both import the same `Qux`. The visibility of `Qux` +// is `pub` because that is the maximum visibility between +// these two `use` declarations. +pub use bar::*; +use foo::*; + +fn main() { + let _: Qux = Qux; +} +``` + +r[names.resolution.expansion.imports.ambiguity.glob-vs-outer] +Names may not be resolved through glob imports when there is another candidate available in an [outer scope]. + +```rust,compile_fail,E0659 +mod bar { + pub mod foo { +// ^-- glob `foo` candidate + pub struct Name; + } +} + +pub mod foo { +// ^-- outer `foo` candidate + pub struct Name; +} + +pub fn qux() { + use bar::*; + use foo::Name; // ERROR: `foo` is ambiguous +} +``` + +```rust,compile_fail,E0659 +pub mod bar { + #[macro_export] + macro_rules! m { + () => {}; + } + + macro_rules! m2 { + () => {}; + } + pub(crate) use m2 as m; +} + +pub fn qux() { + use bar::*; + m!(); // ERROR: `m` is ambiguous +} +``` + +> [!NOTE] +> These ambiguity errors are specific to imports, even though they are only observed when those imports are used. Having multiple candidates available for a given name during later stages of resolution is not considered an error. So long as none of the imports themselves are ambiguous, there will always be a single unambiguous closest resolution. +> +> ```rust +> mod bar { +> pub const NAME: bool = true; +> } +> +> mod baz { +> pub const NAME: bool = false; +> } +> +> use baz::NAME; +> +> pub fn foo() { +> use bar::*; +> assert!(NAME); +> // ^--- This `NAME` is resolved during primary resolution. +> } +> ``` + +r[names.resolution.expansion.imports.ambiguity.path-vs-textual-macro] +Path-based scope bindings for macros may not shadow textual scope bindings to macros. + +```rust,compile_fail,E0659 +macro_rules! m2 { + () => {} +} +macro_rules! m { + () => {} +} +pub fn foo() { + m!(); // ERROR: `m` is ambiguous + use m2 as m; // In scope for entire function body. +} +``` + +r[names.resolution.expansion.macros] +### Macros + +r[names.resolution.expansion.macros.intro] +Macros are resolved by iterating through the available scopes to find the available candidates. Macros are split into two sub-namespaces, one for bang macros, and the other for attributes and derives. Resolution candidates from the incorrect sub-namespace are ignored. + +r[names.resolution.expansion.macros.visitation-order] +The available scope kinds are visited in the following order. Each of these scope kinds represent one or more scopes. + +* [Derive helpers] +* [Textual scope macros] +* [Path-based scope macros] +* [`macro_use` prelude] +* [Standard library prelude] +* [Builtin attributes] + +> [!NOTE] +> +> The compiler will attempt to resolve derive helpers that are used before their associated macro introduces them into scope. This scope is visited after the scope for resolving derive helper candidates that are correctly in scope. This behavior is slated for removal. +> +> For more info see [derive helper scope]. + +> [!EDITION-2018] +> +> Starting in edition 2018 the `#[macro_use]` prelude is not visited when `#[no_implicit_prelude]` is present. + +r[names.resolution.expansion.macros.derivehelpers] +Derive helper scopes are not visited when resolving derive macros in the parent scope (starting scope). + +r[names.resolution.expansion.macros.reserved-names] +The names `cfg` and `cfg_attr` are reserved in the macro attribute [sub-namespace]. + +r[names.resolution.expansion.macros.ambiguity] +#### Ambiguities + +r[names.resolution.expansion.macros.ambiguity.more-expanded-vs-outer] +Name bindings from macro expansions may not shadow name bindings from outside of those expansions. + +```rust,compile_fail,E0659 +macro_rules! name { + () => {} +} + +macro_rules! define_name { + () => { + macro_rules! name { + () => {} + } + } +} + +fn foo() { + define_name!(); + name!(); // ERROR: `name` is ambiguous +} +``` + +r[names.resolution.expansion.macros.ambiguity.builtin-attr] +User defined attributes or derive macros may not shadow builtin non-macro attributes (e.g. inline). + + +```rust,ignore +// with-helper/src/lib.rs +# use proc_macro::TokenStream; +# +#[proc_macro_derive(WithHelperAttr, attributes(non_exhaustive))] +// ^------------- user attr candidate +... +# pub fn derive_with_helper_attr(_item: TokenStream) -> TokenStream { +# TokenStream::new() +# } +``` + + +```rust,ignore +// src/lib.rs +#[derive(with_helper::WithHelperAttr)] +#[non_exhaustive] // ERROR: `non_exhaustive` is ambiguous +struct S; +``` + +> [!NOTE] +> This applies regardless of the name the builtin attribute is a candidate for: +> +> +> ```rust,ignore +> // with-helper/src/lib.rs +> # use proc_macro::TokenStream; +> # +> #[proc_macro_derive(WithHelperAttr, attributes(helper))] +> // ^----- user attr candidate +> ... +> # pub fn derive_with_helper_attr(_item: TokenStream) -> TokenStream { +> # TokenStream::new() +> # } +> ``` +> +> +> ```rust,ignore +> // src/lib.rs +> use inline as helper; +> // ^----- builtin attr candidate via re-export +> +> #[derive(with_helper::WithHelperAttr)] +> #[helper] // ERROR: `helper` is ambiguous +> struct S; +> ``` + +r[names.resolution.primary] +## Primary name resolution +> [!NOTE] +> This is a placeholder for future expansion about primary name resolution. + +r[names.resolution.type-relative] +# Type-relative resolution +> [!NOTE] +> This is a placeholder for future expansion about type-dependent resolution. + +[AST]: glossary.ast +[Builtin attributes]: ./preludes.md#r-names.preludes.lang +[Derive helpers]: ../procedural-macros.md#r-macro.proc.derive.attributes +[Macros]: ../macros.md +[Path-based scope macros]: ../macros.md#r-macro.invocation.name-resolution +[Standard library prelude]: ./preludes.md#r-names.preludes.std +[Textual scope macros]: ../macros-by-example.md#r-macro.decl.scope.textual +[`let` bindings]: ../statements.md#let-statements +[`macro_use` prelude]: ./preludes.md#r-names.preludes.macro_use +[`use` declarations]: ../items/use-declarations.md +[`use` glob shadowing]: ../items/use-declarations.md#r-items.use.glob.shadowing +[derive helper scope]: ../procedural-macros.md#r-macro.proc.derive.attributes.scope +[item definitions]: ../items.md +[macro invocations]: ../macros.md#macro-invocation +[macro textual scope shadowing]: ../macros-by-example.md#r-macro.decl.scope.textual.shadow +[name resolution ambiguities]: #r-names.resolution.expansion.imports.ambiguity +[namespaces]: ../names/namespaces.md +[outer scope]: #r-names.resolution.general.scopes +[path-based scope]: ../macros.md#r-macro.invocation.name-resolution +[permitted]: name-resolution.md#r-names.resolution.expansion.imports.shadowing +[scope]: ../names/scopes.md +[sub-namespace]: ../names/namespaces.md#r-names.namespaces.sub-namespaces +[type-relative paths]: names.resolution.type-relative +[visibility]: ../visibility-and-privacy.md diff --git a/src/names/namespaces.md b/src/names/namespaces.md index b3560d2c19..c0156fc40d 100644 --- a/src/names/namespaces.md +++ b/src/names/namespaces.md @@ -117,58 +117,70 @@ This prevents one style from shadowing another. For example, the [`cfg` attribute] and the [`cfg` macro] are two different entities with the same name in the macro namespace, but they can still be used in their respective context. -r[names.namespaces.sub-namespaces.use-shadow] -It is still an error for a [`use` import] to shadow another macro, regardless of their sub-namespaces. + +> [!NOTE] +> `use` imports still cannot create duplicate bindings of the same name in a module or block, regardless of sub-namespace. +> +> ```rust,ignore +> #[macro_export] +> macro_rules! mymac { +> () => {}; +> } +> +> use myattr::mymac; // error[E0252]: the name `mymac` is defined multiple times +> ``` -[`cfg` attribute]: ../conditional-compilation.md#the-cfg-attribute -[`cfg` macro]: ../conditional-compilation.md#the-cfg-macro -[`for`]: ../expressions/loop-expr.md#iterator-loops -[`if let`]: ../expressions/if-expr.md#if-let-patterns -[`let`]: ../statements.md#let-statements -[`macro_rules` declarations]: ../macros-by-example.md -[`match`]: ../expressions/match-expr.md -[`Self` constructors]: ../paths.md#self-1 -[`Self` type]: ../paths.md#self-1 -[`use` import]: ../items/use-declarations.md -[`while let`]: ../expressions/loop-expr.md#while-let-patterns [Associated const declarations]: ../items/associated-items.md#associated-constants [Associated function declarations]: ../items/associated-items.md#associated-functions-and-methods [Associated type declarations]: ../items/associated-items.md#associated-types [Attribute macros]: ../procedural-macros.md#the-proc_macro_attribute-attribute -[attributes]: ../attributes.md -[bang-style macros]: ../macros.md [Block labels]: expr.loop.block-labels -[boolean]: ../types/boolean.md [Built-in attributes]: ../attributes.md#built-in-attributes-index -[closure parameters]: ../expressions/closure-expr.md -[closure]: ../expressions/closure-expr.md [Constant item declarations]: ../items/constant-items.md [Derive macro helpers]: ../procedural-macros.md#derive-macro-helper-attributes [Derive macros]: macro.proc.derive -[entity]: ../glossary.md#entity [Enum variant constructors]: ../items/enumerations.md -[enum]: ../items/enumerations.md [External crate declarations]: ../items/extern-crates.md [External crate prelude]: preludes.md#extern-prelude -[field expression]: ../expressions/field-expr.md [Function declarations]: ../items/functions.md -[function parameters]: ../items/functions.md#function-parameters [Function-like procedural macros]: ../procedural-macros.md#the-proc_macro-attribute [Generic const parameters]: ../items/generics.md#const-generics [Generic lifetime parameters]: ../items/generics.md [Generic type parameters]: ../items/generics.md [Loop labels]: ../expressions/loop-expr.md#loop-labels [Module declarations]: ../items/modules.md -[name resolution]: name-resolution.md -[names]: ../names.md -[numeric]: ../types/numeric.md [Static item declarations]: ../items/static-items.md [Struct constructors]: ../items/structs.md [Struct]: ../items/structs.md -[textual]: ../types/textual.md [Tool attribute modules]: ../attributes.md#tool-attributes [Tool attributes]: ../attributes.md#tool-attributes [Trait item declarations]: ../items/traits.md [Type aliases]: ../items/type-aliases.md +[`Self` constructors]: ../paths.md#self-1 +[`Self` type]: ../paths.md#self-1 +[`cfg` attribute]: ../conditional-compilation.md#the-cfg-attribute +[`cfg` macro]: ../conditional-compilation.md#the-cfg-macro +[`for`]: ../expressions/loop-expr.md#iterator-loops +[`if let`]: ../expressions/if-expr.md#if-let-patterns +[`let`]: ../statements.md#let-statements +[`macro_rules` declarations]: ../macros-by-example.md +[`match`]: ../expressions/match-expr.md +[`use` import]: ../items/use-declarations.md +[`while let`]: ../expressions/loop-expr.md#while-let-patterns +[attributes]: ../attributes.md +[bang-style macros]: ../macros.md +[boolean]: ../types/boolean.md +[closure parameters]: ../expressions/closure-expr.md +[closure]: ../expressions/closure-expr.md +[entity]: ../glossary.md#entity +[enum]: ../items/enumerations.md +[field expression]: ../expressions/field-expr.md +[function parameters]: ../items/functions.md#function-parameters +[name resolution ambiguity errors]: name-resolution.md#r-names.resolution.expansion.imports.ambiguity.pathvstextualmacro +[name resolution]: name-resolution.md +[names]: ../names.md +[numeric]: ../types/numeric.md +[textual]: ../types/textual.md [union]: ../items/unions.md [use declaration]: ../items/use-declarations.md + diff --git a/src/procedural-macros.md b/src/procedural-macros.md index 4395e3db95..721991f1eb 100644 --- a/src/procedural-macros.md +++ b/src/procedural-macros.md @@ -240,6 +240,24 @@ A helper attribute for a derive macro is declared by adding its identifier to th > } > ``` +r[macro.proc.derive.attributes.scope] +When a derive macro invocation is applied to an item, the helper attributes introduced by that derive macro become in scope 1) for attributes that are applied to that item and are applied lexically after the derive macro invocation and 2) for attributes that are applied to fields and variants inside of the item. + +> [!NOTE] +> rustc currently allows derive helpers to be used before the macro that introduces them. Such derive helpers used out of order may not shadow other attribute macros. This behavior is deprecated and slated for removal. +> +> +> ```rust,ignore +> #[helper] // Deprecated, hard error in the future. +> #[derive(WithHelperAttr)] +> struct Struct { +> field: (), +> } +> ``` +> +> For more details, see [Rust issue #79202](https://github.com/rust-lang/rust/issues/79202). + + r[macro.proc.attribute] ## The `proc_macro_attribute` attribute @@ -432,6 +450,7 @@ their equivalent `#[doc = r"str"]` attributes when passed to macros. [items]: items.md [macro namespace]: names/namespaces.md [module]: items/modules.md +[name resolution ambiguities]: names/name-resolution.md#r-names.resolution.expansion.imports.ambiguity.derivehelper [patterns]: patterns.md [public]: visibility-and-privacy.md [statements]: statements.md From b3fc5d5298fa08aba94554e2407c6cd0ea9434e4 Mon Sep 17 00:00:00 2001 From: Jane Losare-Lusby Date: Tue, 9 Dec 2025 15:09:47 -0800 Subject: [PATCH 02/12] split test into failing and passing components --- src/names/name-resolution.md | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/src/names/name-resolution.md b/src/names/name-resolution.md index 4c46151742..b73ee0992a 100644 --- a/src/names/name-resolution.md +++ b/src/names/name-resolution.md @@ -152,7 +152,7 @@ Names may not be resolved through ambiguous glob imports. Glob imports are allow For example: -```rust +```rust,compile_fail,E0659 mod foo { pub struct Qux; } @@ -165,10 +165,21 @@ use foo::*; use bar::*; // OK, no name conflict. fn ambiguous_use() { - // This would be an error, due to the ambiguity. - //let x = Qux; + let x = Qux; // ERROR: `Qux` is ambiguous } +``` +```rust +# mod foo { +# pub struct Qux; +# } +# +# mod bar { +# pub struct Qux; +# } +# +# use foo::*; +# use bar::*; // OK, no name conflict. fn ambiguous_shadow() { // This is permitted, since resolution is not through the ambiguous globs. struct Qux; From 3739f339804d8fd414220430df11a47f06437110 Mon Sep 17 00:00:00 2001 From: Jane Losare-Lusby Date: Tue, 9 Dec 2025 15:26:46 -0800 Subject: [PATCH 03/12] Update src/names/name-resolution.md Co-authored-by: Eric Huss --- src/names/name-resolution.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/names/name-resolution.md b/src/names/name-resolution.md index b73ee0992a..e6892ddef2 100644 --- a/src/names/name-resolution.md +++ b/src/names/name-resolution.md @@ -401,7 +401,7 @@ r[names.resolution.primary] > This is a placeholder for future expansion about primary name resolution. r[names.resolution.type-relative] -# Type-relative resolution +## Type-relative resolution > [!NOTE] > This is a placeholder for future expansion about type-dependent resolution. From db220a92b05a0b212dd080e2dce25f84cc5707ad Mon Sep 17 00:00:00 2001 From: Travis Cross Date: Tue, 9 Dec 2025 23:24:09 +0000 Subject: [PATCH 04/12] Revise editorially --- src/names/name-resolution.md | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/src/names/name-resolution.md b/src/names/name-resolution.md index e6892ddef2..7f9ddfd843 100644 --- a/src/names/name-resolution.md +++ b/src/names/name-resolution.md @@ -110,28 +110,29 @@ use m::A::V; // ERROR: Unresolved import `m::A::V`. ``` r[names.resolution.expansion.imports.shadowing] -Names introduced via `use` declarations in an [outer scope] are shadowed by -candidates in the same namespace with the same name from an inner scope except -where otherwise restricted by [name resolution ambiguities]. +Names introduced via `use` declarations in an [outer scope] are shadowed by candidates in the same namespace with the same name from an inner scope except where otherwise restricted by [name resolution ambiguities]. -```rust -pub mod foo { - pub mod baz { - pub struct Name; +```rust,no_run +pub mod m1 { + pub mod ambig { + pub const C: u8 = 1; } } -pub mod bar { - pub mod baz { - pub struct Name(pub ()); +pub mod m2 { + pub mod ambig { + pub const C: u8 = 2; } } -use foo::baz; +// This introduces the name `ambig` in the outer scope. +use m1::ambig; fn f() { - use bar::baz; - use baz::Name; - Name(()); + // This shadows `ambig` in the inner scope. + use m2::ambig; + // The `use` from the inner scope is used here. + use ambig::C; + const { assert!(C == 2) }; } ``` From 9a213f71ea13328d50957d7b3102d2f04152d66e Mon Sep 17 00:00:00 2001 From: Jane Losare-Lusby Date: Tue, 9 Dec 2025 15:50:27 -0800 Subject: [PATCH 05/12] change idents for globvsglob example --- src/names/name-resolution.md | 57 +++++++++++++++++++----------------- 1 file changed, 30 insertions(+), 27 deletions(-) diff --git a/src/names/name-resolution.md b/src/names/name-resolution.md index 7f9ddfd843..cdca743292 100644 --- a/src/names/name-resolution.md +++ b/src/names/name-resolution.md @@ -130,7 +130,8 @@ use m1::ambig; fn f() { // This shadows `ambig` in the inner scope. use m2::ambig; - // The `use` from the inner scope is used here. + // The inner candidate is selected here + // as the resolution of `ambig`. use ambig::C; const { assert!(C == 2) }; } @@ -148,65 +149,67 @@ r[names.resolution.expansion.imports.ambiguity] r[names.resolution.expansion.imports.ambiguity.intro] Some situations are an error when there is an ambiguity as to which macro definition, `use` declaration, or module an import or macro invocation's name refers to. This happens when there are two name candidates that do not resolve to the same entity where neither candidate is [permitted] to shadow the other. +TODO rewrite + r[names.resolution.expansion.imports.ambiguity.glob-vs-glob] Names may not be resolved through ambiguous glob imports. Glob imports are allowed to import conflicting names in the same namespace as long as the name is not used. Names with conflicting candidates from ambiguous glob imports may still be shadowed by non glob imports and used without producing an error. The errors occur at time of use, not time of import. For example: ```rust,compile_fail,E0659 -mod foo { - pub struct Qux; +mod m1 { + pub struct Ambig; } -mod bar { - pub struct Qux; +mod m2 { + pub struct Ambig; } -use foo::*; -use bar::*; // OK, no name conflict. +use m1::*; +use m2::*; // OK, no name conflict. fn ambiguous_use() { - let x = Qux; // ERROR: `Qux` is ambiguous + let x = Ambig; // ERROR: `Ambig` is ambiguous } ``` ```rust -# mod foo { -# pub struct Qux; +# mod m1 { +# pub struct Ambig; # } # -# mod bar { -# pub struct Qux; +# mod m2 { +# pub struct Ambig; # } # -# use foo::*; -# use bar::*; // OK, no name conflict. +# use m1::*; +# use m2::*; // OK, no name conflict. fn ambiguous_shadow() { // This is permitted, since resolution is not through the ambiguous globs. - struct Qux; - let x = Qux; + struct Ambig; + let x = Ambig; } ``` -Multiple glob imports are allowed to import the same name, and that name is allowed to be used if the imports are of the same item (following re-exports). The visibility of the name is the maximum visibility of the imports. For example: +Multiple glob imports are allowed to import the same name, and that name is allowed to be used if the imports are of the same item (following re-exports). The visibility of the name is the maximum visibility of the imports. ```rust -mod foo { - pub struct Qux; +mod m1 { + pub struct Ambig; } -mod bar { - pub use super::foo::Qux; +mod m2 { + pub use super::m1::Ambig; } -// These both import the same `Qux`. The visibility of `Qux` -// is `pub` because that is the maximum visibility between -// these two `use` declarations. -pub use bar::*; -use foo::*; +// These both import the same `Ambig`. The visibility of `Ambig` is +// `pub` because that is the maximum visibility between these two `use` +// declarations. +pub use m2::*; +use m1::*; fn main() { - let _: Qux = Qux; + let _: Ambig = Ambig; } ``` From 00588c7476f97727c0a6fdc7d0ad336c4b203431 Mon Sep 17 00:00:00 2001 From: Jane Losare-Lusby Date: Tue, 9 Dec 2025 15:59:02 -0800 Subject: [PATCH 06/12] update examples for globvsouter --- src/names/name-resolution.md | 56 +++++++++++++++++++----------------- 1 file changed, 30 insertions(+), 26 deletions(-) diff --git a/src/names/name-resolution.md b/src/names/name-resolution.md index cdca743292..5bc08d634a 100644 --- a/src/names/name-resolution.md +++ b/src/names/name-resolution.md @@ -152,7 +152,7 @@ Some situations are an error when there is an ambiguity as to which macro defini TODO rewrite r[names.resolution.expansion.imports.ambiguity.glob-vs-glob] -Names may not be resolved through ambiguous glob imports. Glob imports are allowed to import conflicting names in the same namespace as long as the name is not used. Names with conflicting candidates from ambiguous glob imports may still be shadowed by non glob imports and used without producing an error. The errors occur at time of use, not time of import. +Names may not be resolved through ambiguous glob imports. Glob imports are allowed to import conflicting names in the same namespace as long as the name is not used. Names with conflicting candidates from ambiguous glob imports may still be shadowed by non-glob imports and used without producing an error. The errors occur at time of use, not time of import. For example: @@ -191,7 +191,9 @@ fn ambiguous_shadow() { } ``` -Multiple glob imports are allowed to import the same name, and that name is allowed to be used if the imports are of the same item (following re-exports). The visibility of the name is the maximum visibility of the imports. +Multiple glob imports are allowed to import the same name, and that name is +allowed to be used if the imports are of the same item (following re-exports). +The visibility of the name is the maximum visibility of the imports. ```rust mod m1 { @@ -212,66 +214,68 @@ fn main() { let _: Ambig = Ambig; } ``` +// TODO update example to rely upon visibilty for compilation success r[names.resolution.expansion.imports.ambiguity.glob-vs-outer] Names may not be resolved through glob imports when there is another candidate available in an [outer scope]. ```rust,compile_fail,E0659 -mod bar { - pub mod foo { -// ^-- glob `foo` candidate +mod glob { + pub mod ambig { +// ^-- glob `ambig` candidate pub struct Name; } } -pub mod foo { -// ^-- outer `foo` candidate +pub mod ambig { +// ^-- outer `ambig` candidate pub struct Name; } -pub fn qux() { - use bar::*; - use foo::Name; // ERROR: `foo` is ambiguous -} +const _: () = { + use glob::*; + use ambig::Name; // ERROR: `ambig` is ambiguous +}; ``` ```rust,compile_fail,E0659 -pub mod bar { - #[macro_export] +use glob::m2 as ambig; +pub mod glob { macro_rules! m { () => {}; } + pub(crate) use m as ambig; macro_rules! m2 { () => {}; } - pub(crate) use m2 as m; + pub(crate) use m2; } -pub fn qux() { - use bar::*; - m!(); // ERROR: `m` is ambiguous -} +const _: () = { + use glob::*; + ambig!(); // ERROR: `ambig` is ambiguous +}; ``` > [!NOTE] > These ambiguity errors are specific to imports, even though they are only observed when those imports are used. Having multiple candidates available for a given name during later stages of resolution is not considered an error. So long as none of the imports themselves are ambiguous, there will always be a single unambiguous closest resolution. > > ```rust -> mod bar { -> pub const NAME: bool = true; +> mod glob { +> pub const AMBIG: bool = true; > } > -> mod baz { -> pub const NAME: bool = false; +> mod outer { +> pub const AMBIG: bool = false; > } > -> use baz::NAME; +> use outer::AMBIG; > > pub fn foo() { -> use bar::*; -> assert!(NAME); -> // ^--- This `NAME` is resolved during primary resolution. +> use glob::*; +> assert!(AMBIG); +> // ^--- This `AMBIG` is resolved during primary resolution. > } > ``` From 50b110b22efbae5faef5d37d039db12a8f932a08 Mon Sep 17 00:00:00 2001 From: Jane Losare-Lusby Date: Tue, 9 Dec 2025 16:04:13 -0800 Subject: [PATCH 07/12] update example for path vs textual macro ambiguity --- src/names/name-resolution.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/src/names/name-resolution.md b/src/names/name-resolution.md index 5bc08d634a..869b4c25a7 100644 --- a/src/names/name-resolution.md +++ b/src/names/name-resolution.md @@ -283,15 +283,19 @@ r[names.resolution.expansion.imports.ambiguity.path-vs-textual-macro] Path-based scope bindings for macros may not shadow textual scope bindings to macros. ```rust,compile_fail,E0659 -macro_rules! m2 { +macro_rules! ambig { +// ^---- textual macro candidate () => {} } -macro_rules! m { + +macro_rules! path_based { +// ^--- path-based macro candidate () => {} } + pub fn foo() { - m!(); // ERROR: `m` is ambiguous - use m2 as m; // In scope for entire function body. + ambig!(); // ERROR: `ambig` is ambiguous + use path_based as ambig; // In scope for entire function body. } ``` From 4f7ec527fe9278211c5f606d5161fd3c6a88b5a7 Mon Sep 17 00:00:00 2001 From: Travis Cross Date: Wed, 10 Dec 2025 00:07:00 +0000 Subject: [PATCH 08/12] Revise --- src/names/name-resolution.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/names/name-resolution.md b/src/names/name-resolution.md index 869b4c25a7..8e1521879c 100644 --- a/src/names/name-resolution.md +++ b/src/names/name-resolution.md @@ -272,7 +272,7 @@ const _: () = { > > use outer::AMBIG; > -> pub fn foo() { +> pub fn f() { > use glob::*; > assert!(AMBIG); > // ^--- This `AMBIG` is resolved during primary resolution. @@ -293,7 +293,7 @@ macro_rules! path_based { () => {} } -pub fn foo() { +pub fn f() { ambig!(); // ERROR: `ambig` is ambiguous use path_based as ambig; // In scope for entire function body. } @@ -350,7 +350,7 @@ macro_rules! define_name { } } -fn foo() { +fn f() { define_name!(); name!(); // ERROR: `name` is ambiguous } From 1cd52e64af8f32007b976500a79e5c28ed6f8600 Mon Sep 17 00:00:00 2001 From: Travis Cross Date: Wed, 10 Dec 2025 00:09:10 +0000 Subject: [PATCH 09/12] Revise example --- src/names/name-resolution.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/src/names/name-resolution.md b/src/names/name-resolution.md index 8e1521879c..5c7c756e71 100644 --- a/src/names/name-resolution.md +++ b/src/names/name-resolution.md @@ -239,17 +239,18 @@ const _: () = { ``` ```rust,compile_fail,E0659 -use glob::m2 as ambig; -pub mod glob { - macro_rules! m { +use m::f as ambig; +pub mod m { + macro_rules! f { () => {}; } - pub(crate) use m as ambig; - - macro_rules! m2 { + pub(crate) use f; +} +pub mod glob { + macro_rules! f { () => {}; } - pub(crate) use m2; + pub(crate) use f as ambig; } const _: () = { From d8113d23a8d4ce31ed587240cc87be931439f8b1 Mon Sep 17 00:00:00 2001 From: Travis Cross Date: Wed, 10 Dec 2025 00:10:57 +0000 Subject: [PATCH 10/12] Revise examples --- src/names/name-resolution.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/names/name-resolution.md b/src/names/name-resolution.md index 5c7c756e71..019b7d20e1 100644 --- a/src/names/name-resolution.md +++ b/src/names/name-resolution.md @@ -166,7 +166,7 @@ mod m2 { } use m1::*; -use m2::*; // OK, no name conflict. +use m2::*; // OK: No name conflict. fn ambiguous_use() { let x = Ambig; // ERROR: `Ambig` is ambiguous @@ -183,7 +183,7 @@ fn ambiguous_use() { # } # # use m1::*; -# use m2::*; // OK, no name conflict. +# use m2::*; // OK: No name conflict. fn ambiguous_shadow() { // This is permitted, since resolution is not through the ambiguous globs. struct Ambig; @@ -234,7 +234,7 @@ pub mod ambig { const _: () = { use glob::*; - use ambig::Name; // ERROR: `ambig` is ambiguous + use ambig::Name; // ERROR: `ambig` is ambiguous. }; ``` @@ -255,7 +255,7 @@ pub mod glob { const _: () = { use glob::*; - ambig!(); // ERROR: `ambig` is ambiguous + ambig!(); // ERROR: `ambig` is ambiguous. }; ``` @@ -295,7 +295,7 @@ macro_rules! path_based { } pub fn f() { - ambig!(); // ERROR: `ambig` is ambiguous + ambig!(); // ERROR: `ambig` is ambiguous. use path_based as ambig; // In scope for entire function body. } ``` @@ -353,7 +353,7 @@ macro_rules! define_name { fn f() { define_name!(); - name!(); // ERROR: `name` is ambiguous + name!(); // ERROR: `name` is ambiguous. } ``` @@ -377,7 +377,7 @@ User defined attributes or derive macros may not shadow builtin non-macro attrib ```rust,ignore // src/lib.rs #[derive(with_helper::WithHelperAttr)] -#[non_exhaustive] // ERROR: `non_exhaustive` is ambiguous +#[non_exhaustive] // ERROR: `non_exhaustive` is ambiguous. struct S; ``` @@ -404,7 +404,7 @@ struct S; > // ^----- builtin attr candidate via re-export > > #[derive(with_helper::WithHelperAttr)] -> #[helper] // ERROR: `helper` is ambiguous +> #[helper] // ERROR: `helper` is ambiguous. > struct S; > ``` From d479387db382f0a044283491b31a0e4e9ca5d039 Mon Sep 17 00:00:00 2001 From: Travis Cross Date: Wed, 10 Dec 2025 00:29:38 +0000 Subject: [PATCH 11/12] Revise --- src/names/name-resolution.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/names/name-resolution.md b/src/names/name-resolution.md index 019b7d20e1..e741068a69 100644 --- a/src/names/name-resolution.md +++ b/src/names/name-resolution.md @@ -304,7 +304,7 @@ r[names.resolution.expansion.macros] ### Macros r[names.resolution.expansion.macros.intro] -Macros are resolved by iterating through the available scopes to find the available candidates. Macros are split into two sub-namespaces, one for bang macros, and the other for attributes and derives. Resolution candidates from the incorrect sub-namespace are ignored. +Macros are resolved by iterating through the available scopes to find the available candidates. Macros are split into two sub-namespaces, one for function-like macros, and the other for attributes and derives. Resolution candidates from the incorrect sub-namespace are ignored. r[names.resolution.expansion.macros.visitation-order] The available scope kinds are visited in the following order. Each of these scope kinds represent one or more scopes. From 291d048a1dec590e0ba8e3c8948f17a4b2d05d18 Mon Sep 17 00:00:00 2001 From: Jane Losare-Lusby Date: Tue, 9 Dec 2025 16:34:29 -0800 Subject: [PATCH 12/12] update path-vs-textual ambiguity text --- src/names/name-resolution.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/src/names/name-resolution.md b/src/names/name-resolution.md index e741068a69..ab80f52556 100644 --- a/src/names/name-resolution.md +++ b/src/names/name-resolution.md @@ -191,9 +191,7 @@ fn ambiguous_shadow() { } ``` -Multiple glob imports are allowed to import the same name, and that name is -allowed to be used if the imports are of the same item (following re-exports). -The visibility of the name is the maximum visibility of the imports. +Multiple glob imports are allowed to import the same name, and that name is allowed to be used if the imports are of the same item (following re-exports). The visibility of the name is the maximum visibility of the imports. ```rust mod m1 { @@ -281,7 +279,7 @@ const _: () = { > ``` r[names.resolution.expansion.imports.ambiguity.path-vs-textual-macro] -Path-based scope bindings for macros may not shadow textual scope bindings to macros. +Names may not be resolved through ambiguous macro re-exports. Macro re-exports are ambiguous when they would shadow a textual macro candidate for the same name in an [outer scope]. ```rust,compile_fail,E0659 macro_rules! ambig { @@ -300,6 +298,11 @@ pub fn f() { } ``` +// [!NOTE] +// This restriction is needed due to implementation details in the compiler, +// specifically the current scope visitation logic and the complexity of supporting +// this behavior. This ambiguity error may be removed in the future. + r[names.resolution.expansion.macros] ### Macros @@ -322,6 +325,12 @@ The available scope kinds are visited in the following order. Each of these scop > > For more info see [derive helper scope]. +> [!NOTE] +> +> This visitation order may change in the future, such as interleaving the +> visitation of textual and path-based scope candidates based on their lexical +> scopes. + > [!EDITION-2018] > > Starting in edition 2018 the `#[macro_use]` prelude is not visited when `#[no_implicit_prelude]` is present.