Stabilize assert_matches and move it to core::macros

[Voultapher]

Closes #82775

This is a revive of #120234, with the suggested move from the public assert_matches module to macros. This necessitates the rename of the internal macros modules to core_macros and std_macros respectively.

[rustbot]

r? @scottmcm

rustbot has assigned @scottmcm.
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

[rustbot]

HIR ty lowering was modified

cc @fmease

Some changes occurred to the core trait solver

cc @rust-lang/initiative-trait-system-refactor

The run-make-support library was changed

cc @jieyouxu

Some changes occurred to the CTFE machinery

cc @rust-lang/wg-const-eval

Some changes occurred in src/tools/rustfmt

cc @rust-lang/rustfmt

Some changes occurred in src/tools/clippy

cc @rust-lang/clippy

Some changes occurred to MIR optimizations

cc @rust-lang/wg-mir-opt

Some changes occurred to the CTFE / Miri interpreter

cc @rust-lang/miri

[Voultapher]

To all the people that got cc'd feel free to check the changes, but they should only amount to import renames.

[Voultapher]

Changing the filename of the private macros modules has wide reaching effects inside the rustc source code. Mostly the fix is to rename mentions to the path outside of rust code as in the error tests, but there are some places like src/tools/cargo/tests/testsuite/fix.rs that reference the path and I don't know why they do that.

[rustbot]

The Miri subtree was changed

cc @rust-lang/miri

The rustc-dev-guide subtree was changed. If this PR only touches the dev guide consider submitting a PR directly to rust-lang/rustc-dev-guide otherwise thank you for updating the dev guide with your changes.

cc @BoxyUwU, @jieyouxu, @Kobzol

[scottmcm]

Hmm, I found the FCP to stabilize in #82775 (comment)

But I couldn't find any decision on the module. So nominating for libs-api to weigh in on that part.

[Voultapher]

The module name was suggested here #120234 (comment) and here #120234 (comment)

We discussed this in today's @rust-lang/libs-api meeting. The consensus we came up with was:

We want to stabilize this. We're not thrilled with the module name assert_matches (std::assert_matches::assert_matches!), and would prefer a more general name there. However, we don't want to delay stabilization while trying to bikeshed that name.

Ah -- then maybe core::assertions, though that's a bit more of a mouthful. A broader core::macros wouldn't be horrible either IMO, but I could understand hesitation about that.

Given how popular this feature is and the previously expressed desires of the libs-api team to avoid blocking on bikesheding, I'd appreciate it if we could avoid another round of bikesheding here. std::macros and core::macros are about as intuitive a place for a macro to be in. In the future we can pull assert_matches into the prelude for Rust edition 2027.

[Voultapher]

Plus this PR has to touch a lot of files by necessity, so it be great if we could move forward in a reasonable amount of time to limit the amount of merge conflict resolution I'll have to do.

[scottmcm]

Process-wise, a meeting consensus is generally not enough to make a one-way decision like picking a stable path, and it seems clear that this wasn't part of the previous FCP, so I'm not comfortable merging it without explicit libs-api assent.

If they disagree with my assessment that's fine, but it's their decision to make.

[Voultapher]

so I'm not comfortable merging it without explicit libs-api assent.

Neither am I. Let's please ask for their approval. What I'd like to avoid is a situation where we block this because the team is happy enough with the name but maybe there could be a better one and so the discussion starts.

[joshtriplett]

In a libs-api meeting, @Amanieu asked whether enough time has passed for compatibility to improve to the point that we could ship this in the crate root alongside all the other macros.

(I don't know the answer to that question; I'm passing it along.)

[Voultapher]

The issue of macro collision was raised here #82913 and from what I can tell it's still relevant. I'd prefer to do the breakage via a Rust edition change. The vast majority of users uses stable, and there if they want to use assert_matches they will do so via the third-party crate. Looking at common usage https://grep.app/search?f.lang=Rust&q=assert_matches%21 supports this.

I suggest moving forward with the minimal breakage path.

@joshtriplett is the libs-api team happy enough with the use std::macros::assert_matches; module name?

[Amanieu]

I don't think a macros module is the right way to go around this. What we really want is for assert_matches to live in the same place as all the other macros in the standard library, which is currently the crate root (macros are imported with use std::assert;).

Fundamentally the breakage comes from the fact that assert_matches is in the prelude and the way macro name resolution works means that we can't prioritize prelude macros lower than glob-imported macros (#82775 (comment)). However we can avoid this problem by exporting assert_matches from the crate root just like other macros but not including it in the prelude. It can be included in the prelude in a future edition.

Now, the standard library prelude is imported by injecting this code into each crate:

#[prelude_import]
use ::std::prelude::rust_2024::*;
#[macro_use]
extern crate std;

Instead of importing all macros from std with #[macro_use], we can explicitly re-export all macros in the rust_20xx prelude and remove #[macro_use] from the implicit prelude. This allows new macros to be added to the standard library without being a breaking change, while adding them to the prelude can be deferred to a future edition.

[Voultapher]

@Amanieu I like the idea, I'll look into implementing it. Could you please give me some pointers into non obvious things I'd need to keep in mind when changing the prelude, or other side-effects of such a change.

[Amanieu]

In theory it should be as easy as removing #[macro_use] in compiler/rustc_builtin_macros/src/standard_library_imports.rs and then updating library/{core,std}/src/prelude/v1.rs to explicitly include all macros that are exported from the prelude.

[Voultapher]

@Amanieu I've implemented your suggestion as a separate PR #139493. I've also implemented this PR on top of said PR locally and haven't encountered any road blockers, so we should be able to proceed with this stabilization PR when #139493 is merged.

[joshtriplett]

Unrelated to the stabilization, I think that for the next edition we should put this in that edition's prelude.