Specify the behavior of `file!` #134442

epage · 2024-12-17T21:52:25Z

This takes the current behavior of file! and documents it so it is safe to make assumptions about.
For example, Cargo could provide a CARGO_RUSTC_CURRENT_DIR as a base path for file!.

Example use cases

Being able to look up test assets relative to the current file (example)
Inline snapshotting libraries being able to update Rust source code (example)

See rust-lang/cargo#3946 for more context.

T-libs-api discussed two solutions in rust-lang/libs-team#478

file_absolute!:
- Has less meaning in other build tools like buck2
- Bakes in the assumption that a full path is available (e.g. with trim-paths)
Specifying file!s behavior (this PR):
- Leaves it to the user to deal with trim-paths
- Even though file! is currently unspecified, changing it would likely have too large of an impact on the ecosystem at this time.

A future possibility is that rustc could have a flag that controls modifies the base path used for file!.
That seems purely additive with specifying the behavior and we do not want to block on it.
It would also likely be too disruptive for Cargo users (as mentioned). However, we tried to keep this in mind when specifying the behavior.

rustbot · 2024-12-17T21:52:35Z

r? @workingjubilee

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

epage · 2024-12-17T21:53:15Z

I assume @rust-lang/libs-api would want to review the text but, from what I understand, T-lang is the ultimate decider on built-in macros.

library/core/src/macros/mod.rs

joshtriplett · 2024-12-17T22:11:12Z

This documents the existing behavior, and it is hedging about potential future changes (compiler command-line options). Nonetheless, since this could be interpreted as a new guarantee, it's a potential one-way door, so:

@rfcbot merge

Nominating for T-lang discussion.

rfcbot · 2024-12-17T22:11:15Z

Team member @joshtriplett has proposed to merge this. The next step is review by the rest of the tagged team members:

Concerns:

~~tension-between-uses~~ resolved by Specify the behavior of file! #134442 (comment)

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

cc @rust-lang/lang-advisors: FCP proposed for lang, please feel free to register concerns.
See this document for info about what commands tagged team members can give me.

nikomatsakis · 2024-12-18T00:33:22Z

@rfcbot reviewed

traviscross · 2024-12-18T01:22:33Z

@rfcbot reviewed

rfcbot · 2024-12-18T01:22:51Z

🔔 This is now entering its final comment period, as per the review above. 🔔

library/core/src/macros/mod.rs

tmandry · 2024-12-18T21:34:50Z

@rfcbot reviewed

traviscross · 2024-12-19T00:13:48Z

@rustbot labels -I-lang-nominated

We discussed this in our lang call today. It's now in FCP.

library/core/src/macros/mod.rs

traviscross · 2024-12-19T00:32:14Z

library/core/src/macros/mod.rs

+    /// The file name is derived from the root module's source path passed to the Rust compiler
+    /// (e.g. `./src/lib.rs`)
+    /// end the sequence the compiler takes to get from root module to the module containing `file!`.
+    /// (e.g. inside `mod foo;` in `./src/lib.rs`, `file!` would be `./src/foo.rs`),


...or ./src/foo/mod.rs :) Perhaps something like:

Suggested change

/// (e.g. inside `mod foo;` in `./src/lib.rs`, `file!` would be `./src/foo.rs`),

/// (e.g. if the root file of the crate is `./src/lib.rs`, and within that

/// crate there is a module `foo` whose source file is `./src/foo.rs`, then

/// `file!` called within will return `./src/foo.rs`),

Since there is a complete sentence before this, I think the parentheses could be removed and "e.g." replaced with "For example,".

As-is this parenthetical clause starts a sentence and then is followed by , modified by any..., I think that trailer is meant to go with the first sentence (before this example) in either case.

Agreed. The full stop ahead of the parenthetical seems an error, as the sentence does continue after the parenthetical. As you say, probably it'd be better to keep the sentence together and state the "For example" after it.

I pulled the example out into a sentence at the end so that the longer example doesn't break the flow of the explanation.

traviscross · 2024-12-27T16:22:11Z

@rfcbot concern tension-between-uses
@rustbot labels -I-lang-easy-decision +I-lang-nominated

There is a conflict between use of file! to discover or read paths from disk, and use of file! to embed error information...

That's a good point. Let's discuss that and confirm whether we're still happy here.

joshtriplett · 2024-12-28T03:08:02Z

I don't think those two uses conflict here. If you want to use a library (e.g. a testing framework) that relies on having paths in file! that provide enough information to find the original file, you shouldn't pass options that completely hide the information. (You can still use options that strip out parts of it, as long as your testing framework has enough to work with, and I think the defaults are likely to preserve enough information.)

The documentation says what the default behavior is, and notes that compiler options might change that behavior.

library/core/src/macros/mod.rs

joshtriplett · 2025-05-28T18:45:31Z

Some further context: we discussed this in today's @rust-lang/lang meeting, and @traviscross raised the concern about this potentially limiting our ability to change file! further, because people might rely on the documentation as written here. So, this is adding some further hedging.

This takes the current behavior of `file!` and documents it so it is safe to make assumptions about. For example, Cargo could provide a `CARGO_RUSTC_CURRENT_DIR` as a base path for `file!`. Example use cases - Being able to look up test assets relative to the current file ([example](https://github.com/rust-lang/cargo/blob/b9026bf654d7fac283465e58b8b76742244ef07d/tests/testsuite/cargo_add/add_basic/mod.rs#L34)) - Inline snapshotting libraries being able to update Rust source code ([example](https://github.com/rust-lang/cargo/blob/b9026bf654d7fac283465e58b8b76742244ef07d/tests/testsuite/alt_registry.rs#L36-L45)) T-libs-api discussed two solutions - `file_absolute!`: - Has less meaning in other build tools like buck2 - Bakes in the assumption that a full path is available (e.g. with trim-paths) - Specifying `file!`s behavior (this PR): - Leaves it to the user to deal with trim-paths - Even though `file!` is currently unspecified, changing it would likely have too large of an impact on the ecosystem at this time. A future possibility is that rustc could have a flag that controls modifies the base path used for `file!`. That seems purely additive with specifying the behavior and we do not want to block on it. It would also likely be too disruptive for Cargo users (as mentioned). However, we tried to keep this in mind when specifying the behavior.

traviscross · 2025-05-28T19:06:19Z

@rfcbot resolve tension-between-uses

Good. Where I had landed is that we should weaken the guarantees sufficiently that the output of file! can be changed in the ways we'd expect we might want to change it in its role as a tool for diagnostic output, per what @kornelski had said. Probably I still feel like anything that expects a path that can be opened should be using something that isn't meant for diagnostic output, and that maybe we should add such a thing for these use cases, but I'm happy to document what file! does given the caveat that someone using it in a library should expect that it might emit arbitrary other things, as its behavior could be affected by compiler options that author does not control.

rfcbot · 2025-05-28T19:06:25Z

🔔 This is now entering its final comment period, as per the review above. 🔔

rfcbot · 2025-06-07T19:06:34Z

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

This will be merged soon.

workingjubilee

One nit on word choice, take it or leave it, then r=me

workingjubilee · 2025-06-07T19:24:57Z

library/core/src/macros/mod.rs

@@ -1273,6 +1273,19 @@ pub(crate) mod builtin {
    /// first macro invocation leading up to the invocation of the `file!`
    /// macro.
    ///
+    /// The file name is derived from the root module's source path passed to the Rust compiler


@epage ...So, looking on a new day with clearer eyes, I think 80% of my confusion was just the usage of "root module" instead of

Suggested change

/// The file name is derived from the root module's source path passed to the Rust compiler

/// The file name is derived from the crate's source path passed to the Rust compiler

as I believe "crate" is indeed the technically correct thing to say, here? But I am not inclined to argue much here if you think "root module" is preferable, because of the common confusion with "package" that we both know well.

how about this?

Suggested change

/// The file name is derived from the root module's source path passed to the Rust compiler

/// The file name is derived from the crate root's source path passed to the Rust compiler

I think "crate root" is the least ambiguous and most clear description

workingjubilee · 2025-06-07T19:26:39Z

library/core/src/macros/mod.rs

@@ -1273,6 +1273,19 @@ pub(crate) mod builtin {
    /// first macro invocation leading up to the invocation of the `file!`
    /// macro.
    ///
+    /// The file name is derived from the root module's source path passed to the Rust compiler
+    /// and the sequence the compiler takes to get from root module to the


This would then naturally be

Suggested change

/// and the sequence the compiler takes to get from root module to the

/// and the sequence the compiler takes to get from the crate root to the

workingjubilee · 2025-06-07T19:31:25Z

library/core/src/macros/mod.rs

+    /// The file name is derived from the root module's source path passed to the Rust compiler
+    /// and the sequence the compiler takes to get from root module to the
+    /// module containing `file!`, modified by any flags passed to the Rust compiler (e.g.
+    /// `--remap-path-prefix`).  If the root module's source path is relative, the initial base


Suggested change

/// `--remap-path-prefix`). If the root module's source path is relative, the initial base

/// `--remap-path-prefix`). If the crate's source path is relative, the initial base

epage added the T-lang Relevant to the language team label Dec 17, 2024

rustbot assigned workingjubilee Dec 17, 2024

rustbot added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Dec 17, 2024

epage mentioned this pull request Dec 17, 2024

file_absolute! macro rust-lang/libs-team#478

Closed

joshtriplett reviewed Dec 17, 2024

View reviewed changes

library/core/src/macros/mod.rs Outdated Show resolved Hide resolved

rfcbot added proposed-final-comment-period Proposed to merge/close by relevant subteam, see T-<team> label. Will enter FCP once signed off. disposition-merge This issue / PR is in PFCP or FCP with a disposition to merge it. labels Dec 17, 2024

rfcbot added final-comment-period In the final comment period and will be merged soon unless new substantive objections are raised. and removed proposed-final-comment-period Proposed to merge/close by relevant subteam, see T-<team> label. Will enter FCP once signed off. labels Dec 18, 2024

epage mentioned this pull request Dec 18, 2024

fix(env): dont track envs set by cargo in dep-info file rust-lang/cargo#14811

Closed

workingjubilee reviewed Dec 18, 2024

View reviewed changes

library/core/src/macros/mod.rs Outdated Show resolved Hide resolved

epage force-pushed the change branch from aa67d1a to ef50938 Compare December 18, 2024 23:10

rustbot removed the I-lang-nominated Nominated for discussion during a lang team meeting. label Dec 19, 2024

traviscross reviewed Dec 19, 2024

View reviewed changes

library/core/src/macros/mod.rs Outdated Show resolved Hide resolved

traviscross reviewed Dec 19, 2024

View reviewed changes

rfcbot added proposed-final-comment-period Proposed to merge/close by relevant subteam, see T-<team> label. Will enter FCP once signed off. and removed final-comment-period In the final comment period and will be merged soon unless new substantive objections are raised. labels Dec 27, 2024

rustbot added I-lang-nominated Nominated for discussion during a lang team meeting. and removed I-lang-easy-decision Issue: The decision needed by the team is conjectured to be easy; this does not imply nomination labels Dec 27, 2024

workingjubilee added S-waiting-on-concerns Status: Awaiting concerns to be addressed by the author and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jan 4, 2025

epage force-pushed the change branch from a297e97 to 2f1c21d Compare January 27, 2025 19:57

epage force-pushed the change branch from 2f1c21d to 6481479 Compare May 6, 2025 18:11

hanna-kruppe mentioned this pull request May 10, 2025

file!() returns incorrect Paths on WASM target built on Windows. #140883

Open

traviscross added the P-lang-drag-3 Lang team prioritization drag level 3.https://rust-lang.zulipchat.com/#narrow/channel/410516-t-lang. label May 16, 2025

joshtriplett reviewed May 28, 2025

View reviewed changes

library/core/src/macros/mod.rs Show resolved Hide resolved

This comment has been minimized.

Sign in to view

epage force-pushed the change branch from a4af480 to f5c9d51 Compare May 28, 2025 18:59

rfcbot added final-comment-period In the final comment period and will be merged soon unless new substantive objections are raised. and removed proposed-final-comment-period Proposed to merge/close by relevant subteam, see T-<team> label. Will enter FCP once signed off. labels May 28, 2025

rfcbot added finished-final-comment-period The final comment period is finished for this PR / Issue. and removed final-comment-period In the final comment period and will be merged soon unless new substantive objections are raised. labels Jun 7, 2025

rfcbot added the to-announce Announce this issue on triage meeting label Jun 7, 2025

rustbot mentioned this pull request Jun 7, 2025

Tracking issue for release notes of #134442: Specify the behavior of file! #142178

Open

workingjubilee approved these changes Jun 7, 2025

View reviewed changes

-    /// (e.g. inside `mod foo;` in `./src/lib.rs`, `file!` would be `./src/foo.rs`),
+    /// (e.g. if the root file of the crate is `./src/lib.rs`, and within that
+    /// crate there is a module `foo` whose source file is `./src/foo.rs`, then
+    /// `file!` called within will return `./src/foo.rs`),

	/// The file name is derived from the root module's source path passed to the Rust compiler
	/// The file name is derived from the crate's source path passed to the Rust compiler

	/// and the sequence the compiler takes to get from root module to the
	/// and the sequence the compiler takes to get from the crate root to the

	/// `--remap-path-prefix`). If the root module's source path is relative, the initial base
	/// `--remap-path-prefix`). If the crate's source path is relative, the initial base

Specify the behavior of file! #134442

Are you sure you want to change the base?

Specify the behavior of file! #134442

Conversation

epage commented Dec 17, 2024

Uh oh!

rustbot commented Dec 17, 2024

Uh oh!

epage commented Dec 17, 2024

Uh oh!

Uh oh!

joshtriplett commented Dec 17, 2024

Uh oh!

rfcbot commented Dec 17, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nikomatsakis commented Dec 18, 2024

Uh oh!

traviscross commented Dec 18, 2024

Uh oh!

rfcbot commented Dec 18, 2024

Uh oh!

Uh oh!

tmandry commented Dec 18, 2024

Uh oh!

traviscross commented Dec 19, 2024

Uh oh!

Uh oh!

traviscross Dec 19, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tgross35 Dec 19, 2024

Choose a reason for hiding this comment

Uh oh!

traviscross Dec 19, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

epage Dec 19, 2024

Choose a reason for hiding this comment

Uh oh!

traviscross commented Dec 27, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

joshtriplett commented Dec 28, 2024

Uh oh!

Uh oh!

joshtriplett commented May 28, 2025

Uh oh!

This comment has been minimized.

traviscross commented May 28, 2025

Uh oh!

rfcbot commented May 28, 2025

Uh oh!

rfcbot commented Jun 7, 2025

Uh oh!

workingjubilee left a comment

Choose a reason for hiding this comment

Uh oh!

workingjubilee Jun 7, 2025

Choose a reason for hiding this comment

Uh oh!

Noratrieb Jun 8, 2025

Choose a reason for hiding this comment

Uh oh!

workingjubilee Jun 7, 2025

Choose a reason for hiding this comment

Uh oh!

workingjubilee Jun 7, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Specify the behavior of `file!` #134442

Specify the behavior of `file!` #134442

rfcbot commented Dec 17, 2024 •

edited

Loading

traviscross Dec 19, 2024 •

edited

Loading

traviscross Dec 19, 2024 •

edited

Loading

traviscross commented Dec 27, 2024 •

edited

Loading