Explicitly export core and std macros

[Voultapher]

Currently all core and std macros are automatically added to the prelude via #[macro_use]. However a situation arose where we want to add a new macro assert_matches but don't want to pull it into the standard prelude for compatibility reasons. By explicitly exporting the macros found in the core and std crates we get to decide on a per macro basis and can later add them via the rust_20xx preludes.

Closes #53977
Unlocks #137487

Reference PR:

• Reflect explicit macro import in reference reference#2077

Stabilization report lib

Everything N/A or already covered by lang report except, breaking changes: The unstable and never intended for public use format_args_nl macro is no longer publicly accessible as requested by @petrochenkov. Affects <10 crates including dependencies.

Stabilization report lang

Summary

Explicitly export core and std macros.

This change if merged would change the code injected into user crates to no longer include #[macro_use] on extern crate core and extern crate std. This change is motivated by a near term goal and a longer term goal. The near term goal is to allow a macro to be defined at the std or core crate root but not have it be part of the implicit prelude. Such macros can then be separately promoted to the prelude in a new edition. Specifically this is blocking the stabilization of assert_matches #137487. The longer term goal is to gradually deprecate #[macro_use]. By no longer requiring it for standard library usage, this serves as a step towards that goal. For more information see #53977.

PR link: #139493

Tracking:

• Tracking Issue for future-incompatibility lint ambiguous_panic_imports #147319

Reference PRs:

• Explicitly export core and std macros #139493

cc @rust-lang/lang @rust-lang/lang-advisors

What is stabilized

Stabilization:

• #[macro_use] is no longer automatically included in the crate root module. This allows the explicit import of macros in the core and std prelude e.g. pub use crate::dbg;.

• ambiguous_panic_imports lint. Code that previously passed without warnings, but included the following or equivalent - only pertaining to core vs std panic - will now receive a warning:

  #![no_std]
  extern crate std;
  use std::prelude::v1::*;
  fn xx() {
      panic!(); // resolves to core::panic
      //~^ WARNING `panic` is ambiguous
      //~| WARNING this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!
  }

  This lint is tied to a new exception to the name resolution logic in compiler/rustc_resolve/src/ident.rs similar to an exception added for Glob import causes ambiguity on nightly #145575. Specifically this only happens if the import of two builtin macros is ambiguous and they are named sym::panic. I.e. this can only happen for core::panic and std::panic. While there are some tiny differences in what syntax is allowed in std::panic vs core::panic in editions 2015 and 2018, see. The behavior at runtime will always be the same if it compiles, implying minimal risk in what specific macro is resolved. At worst some closed source project not captured by crater will stop compiling because a different panic is resolved than previously and they were using obscure syntax like panic!(&String::new()).

Design

N/A

Reference

What updates are needed to the Reference? Link to each PR. If the Reference is missing content needed for describing this feature, discuss that.

• Reflect explicit macro import in reference reference#2077

RFC history

What RFCs have been accepted for this feature?

N/A

Answers to unresolved questions

N/A

Post-RFC changes

What other user-visible changes have occurred since the RFC was accepted? Describe both changes that the lang team accepted (and link to those decisions) as well as changes that are being presented to the team for the first time in this stabilization report.

N/A

Key points

What decisions have been most difficult and what behaviors to be stabilized have proved most contentious? Summarize the major arguments on all sides and link to earlier documents and discussions.

• Nothing was really contentious.

Nightly extensions

Are there extensions to this feature that remain unstable? How do we know that we are not accidentally committing to those?

N/A

Doors closed

What doors does this stabilization close for later changes to the language? E.g., does this stabilization make any other RFCs, lang experiments, or known in-flight proposals more difficult or impossible to do later?

No known doors are closed.

Feedback

Call for testing

Has a "call for testing" been done? If so, what feedback was received?

No.

Nightly use

Do any known nightly users use this feature? Counting instances of #![feature(FEATURE_NAME)] on GitHub with grep might be informative.

N/A

Implementation

Major parts

Summarize the major parts of the implementation and provide links into the code and to relevant PRs.

See, e.g., this breakdown of the major parts of async closures:

• https://rustc-dev-guide.rust-lang.org/coroutine-closures.html

The key change is compiler/rustc_builtin_macros/src/standard_library_imports.rs removing the macro_use inject and the v1.rs preludes now explicitly pub useing the macros https://github.com/rust-lang/rust/pull/139493/files#diff-a6f9f476d41575b19b399c6d236197355556958218fd035549db6d584dbdea1d + https://github.com/rust-lang/rust/pull/139493/files#diff-49849ff961ebc978f98448c8990cf7aae8e94cb03db44f016011aa8400170587.

Coverage

Summarize the test coverage of this feature.

Consider what the "edges" of this feature are. We're particularly interested in seeing tests that assure us about exactly what nearby things we're not stabilizing. Tests should of course comprehensively demonstrate that the feature works. Think too about demonstrating the diagnostics seen when common mistakes are made and the feature is used incorrectly.

Within each test, include a comment at the top describing the purpose of the test and what set of invariants it intends to demonstrate. This is a great help to our review.

Describe any known or intentional gaps in test coverage.

Contextualize and link to test folders and individual tests.

A variety of UI tests including edge cases have been added.

Outstanding bugs

What outstanding bugs involve this feature? List them. Should any block the stabilization? Discuss why or why not.

An old bug is made more noticeable by this change #145577 but it was recommended to not block on it #139493 (comment).

Outstanding FIXMEs

What FIXMEs are still in the code for that feature and why is it OK to leave them there?

// Turn ambiguity errors for core vs std panic into warnings.
// FIXME: Remove with lang team approval.

https://github.com/rust-lang/rust/pull/139493/files#diff-c046507afdba3b0705638f53fffa156cbad72ed17aa01d96d7bd1cc10b8d9bce

Tool changes

What changes must be made to our other tools to support this feature. Has this work been done? Link to any relevant PRs and issues.

• rustfmt
• rust-analyzer
• rustdoc (both JSON and HTML)
• cargo
• clippy
• rustup
• docs.rs

No known changes needed or expected.

Breaking changes

If this stabilization represents a known breaking change, link to the crater report, the analysis of the crater report, and to all PRs we've made to ecosystem projects affected by this breakage. Discuss any limitations of what we're able to know about or to fix.

Breaking changes:

• It's possible for user code to invoke an ambiguity by defining their own macros with standard library names and glob importing them, e.g. use nom::* importing nom::dbg. In practice this happens rarely based on crater data. The 3 public crates where this was an issue, have been fixed. The ambiguous panic import is more common and affects a non-trivial amount of the public - and likely private - crate ecosystem. To avoid a breaking change, a new future incompatible lint was added ambiguous_panic_imports see Tracking Issue for future-incompatibility lint ambiguous_panic_imports #147319. This allows current code to continue compiling, albeit with a new warning. Future editions of Rust make this an error and future versions of Rust can choose to make this error. Technically this is a breaking change, but crater gives us the confidence that the impact will be at worst a new warning for 99+% of public and private crates.

  #![no_std]
  extern crate std;
  use std::prelude::v1::*;
  fn xx() {
      panic!(); // resolves to core::panic
      //~^ WARNING `panic` is ambiguous
      //~| WARNING this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!
  }

• Code using #![no_implicit_prelude] and Rust edition 2015 will no longer automatically have access to the prelude macros. The following works on nightly but would stop working with this change:

  #![no_implicit_prelude]
  // Uncomment to fix error.
  // use std::vec;
  fn main() {
      let _ = vec![3, 6];
  }

  Inversely with this change the panic and unreachable macro will always be in the prelude even if #![no_implicit_prelude] is specified.

  Error matrix when using #![no_implicit_prelude], ✅ means compiler passes 🚫 means compiler error:

  Configuration	Rust 2015	Rust 2018+
  Nightly (panic|unreachable) macro	✅	🚫
  PR (panic|unreachable) macro	✅	✅
  Nightly (column|concat|file|line|module_path|stringify) macro	✅	✅
  PR (column|concat|file|line|module_path|stringify) macro	✅	✅
  Nightly remaining macros	✅	🚫
  PR remaining macros	🚫	🚫

  Addressing this issue is deemed expensive.

Crater found no instance of this pattern in use. Affected code can fix the issue by directly importing the macros. The new behavior matches the behavior of #![no_implicit_prelude] in Rust editions 2018 and beyond and it's intuitive meaning.

Crater report:

• https://crater-reports.s3.amazonaws.com/pr-139493-2/index.html (latest run, but partial run)
• https://crater-reports.s3.amazonaws.com/pr-139493-1/index.html (previous full run, one fix missing)

Crater analysis:

• Discussed in breaking changes.

PRs to affected crates:

• Fix ambiguous assert_eq uses Michael-F-Bryan/gcode-rs#57
• Fix uses of assert_eq stbuehler/rust-ipcrypt#1
• Fix ambiguous assert_eq imports jcreekmore/dmidecode#55

Type system, opsem

Compile-time checks

What compilation-time checks are done that are needed to prevent undefined behavior?

Link to tests demonstrating that these checks are being done.

N/A

Type system rules

What type system rules are enforced for this feature and what is the purpose of each?

N/A

Sound by default?

Does the feature's implementation need specific checks to prevent UB, or is it sound by default and need specific opt-in to perform the dangerous/unsafe operations? If it is not sound by default, what is the rationale?

N/A

Breaks the AM?

Can users use this feature to introduce undefined behavior, or use this feature to break the abstraction of Rust and expose the underlying assembly-level implementation? Describe this if so.

N/A

Common interactions

Temporaries

Does this feature introduce new expressions that can produce temporaries? What are the scopes of those temporaries?

N/A

Drop order

Does this feature raise questions about the order in which we should drop values? Talk about the decisions made here and how they're consistent with our earlier decisions.

N/A

Pre-expansion / post-expansion

Does this feature raise questions about what should be accepted pre-expansion (e.g. in code covered by #[cfg(false)]) versus what should be accepted post-expansion? What decisions were made about this?

N/A

Edition hygiene

If this feature is gated on an edition, how do we decide, in the context of the edition hygiene of tokens, whether to accept or reject code. E.g., what token do we use to decide?

N/A

SemVer implications

Does this feature create any new ways in which library authors must take care to prevent breaking downstreams when making minor-version releases? Describe these. Are these new hazards "major" or "minor" according to RFC 1105?

No.

Exposing other features

Are there any other unstable features whose behavior may be exposed by this feature in any way? What features present the highest risk of that?

No.

History

List issues and PRs that are important for understanding how we got here.

• This change was asked for here Stabilize assert_matches and move it to core::macros #137487 (comment)

Acknowledgments

Summarize contributors to the feature by name for recognition and so that those people are notified about the stabilization. Does anyone who worked on this not think it should be stabilized right now? We'd like to hear about that if so.

More or less solo developed by @Voultapher with some help from @petrochenkov.

Open items

List any known items that have not yet been completed and that should be before this is stabilized.

None.

[rustbot]

r? @ChrisDenton

rustbot has assigned @ChrisDenton.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[Voultapher]

r? @Amanieu

[Voultapher]

@Amanieu the tidy issue highlights an annoying and unforeseen side-effect of this change. The vec module is now part of the prelude. In effect this means that for example this code:

fn xx(i: vec::IntoIter<i32>) {
    let _ = i.as_slice();
}

fn main() {}

that currently doesn't compile on stable would now compile. Initially I thought this would cause name collisions if users define their own vec module but so far I wasn't able to produce those, it seems to always prefer the local module. But regardless, I think we don't want to allow access to a standard library namespace without going through std, alloc or core. AFAIK there is no way to pub use only the macro and not the module namespace without modifications. I have two ideas how to tackle this, maybe we can rename vec to vec_xx internally and have separate use expressions or we have to add another crate that we can #[macro_use] inject into the prelude that only contains the vec macro. Thoughts?

[traviscross]

See also:

• 2024 edition prelude item docs are not inlined, and cause some duplication and confusion #136102

[petrochenkov]

There's an issue for this change - #53977.

[dtolnay]

@Voultapher, avoiding the vec module re-export can be done like this:

#[macro_export]
macro_rules! myvec {
    () => {};
}

pub mod myvec {
    pub struct Vec;
}

pub mod prelude {
    // Bad: re-exports both macro and type namespace
    // pub use crate::myvec;
    
    mod vec_macro_only {
        #[allow(hidden_glob_reexports)]
        mod myvec {}
        pub use crate::*;
    }
    pub use self::vec_macro_only::myvec;
}

fn main() {
    prelude::myvec!();
    let _: prelude::myvec::Vec; // error
}

https://play.rust-lang.org/?version=stable&mode=debug&edition=2024&gist=5e50828c593e04ba0e98f48c9d8696b4

[Voultapher]

I've applied the suggestion by @dtolnay local tests seem promising. @Kobzol could we please do a timer run to see if this PR impacts compile-times.

[petrochenkov]

env and panic (and maybe something else now?) need to be treated in the same way as vec.

[Kobzol]

@Voultapher Based on the CI failure I think that a try build would fail now.

[Voultapher]

Ok, I'll try to get the CI passing first.

[Voultapher]

@petrochenkov I went through all macros and searched the docs and env and panic seem to be the only other ones affected.

[Voultapher]

@Amanieu this program previously worked:

use std::*;

fn main() {
    panic!("panic works")
}

and now runs into:

error[E0659]: `panic` is ambiguous
   --> src/main.rs:4:5
    |
4   |     panic!("panic works")
    |     ^^^^^ ambiguous name
    |
    = note: ambiguous because of a conflict between a name from a glob import and an outer scope during import or macro resolution
note: `panic` could refer to the macro imported here
   --> src/main.rs:1:5
    |
1   | use std::*;
    |     ^^^^^^
    = help: consider adding an explicit import of `panic` to disambiguate
    = help: or use `crate::panic` to refer to this macro unambiguously
note: `panic` could also refer to the macro defined here
   --> rust/library/std/src/prelude/mod.rs:157:13
    |
157 |     pub use super::v1::*;
    |             ^^^^^^^^^

I don't see how we can resolve that without changing language import rules and or special casing the prelude import.

[Amanieu]

@petrochenkov Do you have any ideas about that?

[petrochenkov]

Could you add a test making sure that the modules vec, env and panic are not in prelude?

[petrochenkov]

@petrochenkov Do you have any ideas about that?

The ambiguity wouldn't happen if it was the same panic in std root and in the stdlib prelude.
However, std and core have two different panic macros.

Previously #[macro_use] extern crate std; would add the std's panic to macro_use prelude, and #[macro_use] extern crate core; would add the core's panic.
This PR always adds the core's panic.

[petrochenkov]

Great.
r=me after squashing commits.
@rustbot author

[petrochenkov]

The wasmi case can be added to is_issue_147319_hack too, I guess, but I don't want to block this PR on it.

[rustbot]

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

[Voultapher]

@rusbot ready

[petrochenkov]

@bors r+

[rust-bors]

📌 Commit 506762f has been approved by petrochenkov

It is now in the queue for this repository.

[petrochenkov]

@bors rollup=never
Major library change, compiler change, known breakage, perf effects.

[rust-bors]

☀️ Test successful - CI
Approved by: petrochenkov
Pushing 9b81629 to main...

[github-actions]

What is this?

This is an experimental post-merge analysis report that shows differences in test outcomes between the merged PR and its parent PR.

Comparing db1484b (parent) -> 9b81629 (this PR)

Test differences

Show 634 test diffs

Stage 1

• [ui] tests/ui/imports/ambiguous-panic-glob-vs-multiouter.rs: [missing] -> pass (J0)
• [ui] tests/ui/imports/ambiguous-panic-globvsglob.rs: [missing] -> pass (J0)
• [ui] tests/ui/imports/ambiguous-panic-no-implicit-prelude.rs: [missing] -> pass (J0)
• [ui] tests/ui/imports/ambiguous-panic-non-prelude-core-glob.rs: [missing] -> pass (J0)
• [ui] tests/ui/imports/ambiguous-panic-non-prelude-std-glob.rs: [missing] -> pass (J0)
• [ui] tests/ui/imports/ambiguous-panic-pick-core.rs: [missing] -> pass (J0)
• [ui] tests/ui/imports/ambiguous-panic-pick-std.rs: [missing] -> pass (J0)
• [ui] tests/ui/imports/ambiguous-panic-re-emit.rs: [missing] -> pass (J0)
• [ui] tests/ui/imports/ambiguous-panic-rename-builtin.rs: [missing] -> pass (J0)
• [ui] tests/ui/imports/ambiguous-panic-rename-panics.rs: [missing] -> pass (J0)
• [ui] tests/ui/imports/ambiguous-panic.rs: [missing] -> pass (J0)

Stage 2

• [ui] tests/ui/imports/ambiguous-panic-glob-vs-multiouter.rs: [missing] -> pass (J1)
• [ui] tests/ui/imports/ambiguous-panic-globvsglob.rs: [missing] -> pass (J1)
• [ui] tests/ui/imports/ambiguous-panic-no-implicit-prelude.rs: [missing] -> pass (J1)
• [ui] tests/ui/imports/ambiguous-panic-non-prelude-core-glob.rs: [missing] -> pass (J1)
• [ui] tests/ui/imports/ambiguous-panic-non-prelude-std-glob.rs: [missing] -> pass (J1)
• [ui] tests/ui/imports/ambiguous-panic-pick-core.rs: [missing] -> pass (J1)
• [ui] tests/ui/imports/ambiguous-panic-pick-std.rs: [missing] -> pass (J1)
• [ui] tests/ui/imports/ambiguous-panic-re-emit.rs: [missing] -> pass (J1)
• [ui] tests/ui/imports/ambiguous-panic-rename-builtin.rs: [missing] -> pass (J1)
• [ui] tests/ui/imports/ambiguous-panic-rename-panics.rs: [missing] -> pass (J1)
• [ui] tests/ui/imports/ambiguous-panic.rs: [missing] -> pass (J1)

Additionally, 612 doctest diffs were found. These are ignored, as they are noisy.

Job group index

• J0: x86_64-gnu-llvm-20-3, x86_64-gnu-llvm-21-3
• J1: aarch64-apple, aarch64-gnu, aarch64-gnu-llvm-20-1, aarch64-msvc-1, arm-android, armhf-gnu, dist-i586-gnu-i586-i686-musl, i686-gnu-1, i686-gnu-nopt-1, i686-msvc-1, test-various, x86_64-gnu, x86_64-gnu-debug, x86_64-gnu-gcc, x86_64-gnu-llvm-20, x86_64-gnu-llvm-20-2, x86_64-gnu-llvm-21-2, x86_64-gnu-nopt, x86_64-gnu-stable, x86_64-mingw-1, x86_64-msvc-1

Test dashboard

Run

cargo run --manifest-path src/ci/citool/Cargo.toml -- \
    test-dashboard 9b81629631b382fd49ee3a20ac47797b1467e52d --output-dir test-dashboard

And then open test-dashboard/index.html in your browser to see an overview of all executed tests.

Job duration changes

1. test-various: 6108.1s -> 7545.5s (+23.5%)
2. dist-aarch64-llvm-mingw: 6381.3s -> 5628.0s (-11.8%)
3. dist-aarch64-msvc: 6256.2s -> 5538.7s (-11.5%)
4. aarch64-msvc-2: 5619.6s -> 6228.6s (+10.8%)
5. x86_64-gnu-llvm-20-2: 5407.1s -> 5947.4s (+10.0%)
6. i686-gnu-nopt-2: 8016.1s -> 8757.0s (+9.2%)
7. x86_64-gnu-llvm-21-2: 5293.5s -> 5723.3s (+8.1%)
8. aarch64-gnu-llvm-20-1: 3552.5s -> 3837.9s (+8.0%)
9. dist-arm-linux-musl: 5277.3s -> 5684.4s (+7.7%)
10. dist-aarch64-apple: 8059.3s -> 8676.2s (+7.7%)

How to interpret the job duration changes?

Job durations can vary a lot, based on the actual runner instance
that executed the job, system noise, invalidated caches, etc. The table above is provided
mostly for t-infra members, for simpler debugging of potential CI slow-downs.

[rust-timer]

Finished benchmarking commit (9b81629): comparison URL.

Overall result: ❌✅ regressions and improvements - please read the text below

Our benchmarks found a performance regression caused by this PR.
This might be an actual regression, but it can also be just noise.

Next Steps:

• If the regression was expected or you think it can be justified,
  please write a comment with sufficient written justification, and add
  @rustbot label: +perf-regression-triaged to it, to mark the regression as triaged.
• If you think that you know of a way to resolve the regression, try to create
  a new PR with a fix for the regression.
• If you do not understand the regression or you think that it is just noise,
  you can ask the @rust-lang/wg-compiler-performance working group for help (members of this group
  were already notified of this PR).

@rustbot label: +perf-regression
cc @rust-lang/wg-compiler-performance

Instruction count

Our most reliable metric. Used to determine the overall result above. However, even this metric can be noisy.

	mean	range	count
Regressions ❌ (primary)	0.5%	[0.5%, 0.5%]	1
Regressions ❌ (secondary)	0.1%	[0.0%, 0.5%]	10
Improvements ✅ (primary)	-	-	0
Improvements ✅ (secondary)	-0.1%	[-0.1%, -0.1%]	2
All ❌✅ (primary)	0.5%	[0.5%, 0.5%]	1

Max RSS (memory usage)

Results (primary 1.4%, secondary -0.2%)

A less reliable metric. May be of interest, but not used to determine the overall result above.

	mean	range	count
Regressions ❌ (primary)	1.4%	[0.6%, 2.1%]	2
Regressions ❌ (secondary)	3.2%	[3.2%, 3.2%]	1
Improvements ✅ (primary)	-	-	0
Improvements ✅ (secondary)	-1.9%	[-2.1%, -1.8%]	2
All ❌✅ (primary)	1.4%	[0.6%, 2.1%]	2

Cycles

Results (primary 2.5%, secondary -0.0%)

A less reliable metric. May be of interest, but not used to determine the overall result above.

	mean	range	count
Regressions ❌ (primary)	2.5%	[2.3%, 2.7%]	3
Regressions ❌ (secondary)	3.0%	[2.0%, 3.9%]	10
Improvements ✅ (primary)	-	-	0
Improvements ✅ (secondary)	-4.3%	[-7.4%, -1.7%]	7
All ❌✅ (primary)	2.5%	[2.3%, 2.7%]	3

Binary size

Results (primary 0.0%, secondary 0.0%)

A less reliable metric. May be of interest, but not used to determine the overall result above.

	mean	range	count
Regressions ❌ (primary)	0.0%	[0.0%, 0.0%]	8
Regressions ❌ (secondary)	0.0%	[0.0%, 0.0%]	6
Improvements ✅ (primary)	-	-	0
Improvements ✅ (secondary)	-	-	0
All ❌✅ (primary)	0.0%	[0.0%, 0.0%]	8

Bootstrap: 474.378s -> 476.337s (0.41%)
Artifact size: 383.16 MiB -> 383.08 MiB (-0.02%)

[eirnym]

I wish in the future there will be a global libraryapp attribute to disable implicit #[macro_use] for core/std on stable as well.

[ehuss]

It wasn't clear to me before this was merged that this approved a change for the 2026 edition. Can we remove that edition check and go through the process for adding new features to an edition? (Or, preferably, if this ends up changing for all editions, then there will be no additional work to do.)

[eirnym]

I agree, that by default it could be only in 2026 edition as the closest.

Following is my opinion and wishful thinking, reality might be different.

However, on my prediction, 2026 edition could be adopted in most libraries and apps in at least ~3-5 years after the release of it. Even today a library with 2024 edition is quite rare, and one can find apps with even 2015 edition.

I perceive that this feature doesn't change syntax or break stuff, but it's about how Rust compiler generates code and affects only macros in prelude, my proposition was eventually to add a macro similar to #![no_std], which could be turned on or off at least in tests. Multiple apps and their tests could've use this feature. With this gate, this feature could theoretically be backported to prior editions (but will require minimal Rust version to be higher.

As lack of this feature prevents assert_matches (and potentially other asserts) to be published (as far as I'm concerned), developers will most likely would prefer to use third-party libraries to cover these asserts many yeas after this feature will be shipped.