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.

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

library/core/src/macros/mod.rs

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.

workingjubilee · 2025-06-10T03:07:46Z

@bors r+ rollup

bors · 2025-06-10T03:07:49Z

📌 Commit fea6a22 has been approved by workingjubilee

It is now in the queue for this repository.

Specify the behavior of `file!` 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)) 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.

Rollup of 13 pull requests Successful merges: - #134442 (Specify the behavior of `file!`) - #134841 (Look at proc-macro attributes when encountering unknown attribute) - #140372 (Exhaustively handle parsed attributes in CheckAttr) - #140766 (Stabilize keylocker) - #141061 (Change __rust_no_alloc_shim_is_unstable to be a function) - #142042 (Make E0621 missing lifetime suggestion verbose) - #142101 (core::ptr: deduplicate more method docs) - #142176 (tests: Split dont-shuffle-bswaps along opt-levels and arches) - #142258 (platform-support.md: Mention specific Linux kernel version or later) - #142260 (Miri subtree update) - #142262 (Mark `core::slice::memchr` as `#[doc(hidden)]`) - #142272 (tests: Change ABIs in tests to more future-resilient ones) - #142275 (rustdoc: Refractor `clean_ty_generics`) r? `@ghost` `@rustbot` modify labels: rollup

Specify the behavior of `file!` 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)) 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.

Rollup of 12 pull requests Successful merges: - #134442 (Specify the behavior of `file!`) - #134841 (Look at proc-macro attributes when encountering unknown attribute) - #140372 (Exhaustively handle parsed attributes in CheckAttr) - #140766 (Stabilize keylocker) - #141061 (Change __rust_no_alloc_shim_is_unstable to be a function) - #142042 (Make E0621 missing lifetime suggestion verbose) - #142101 (core::ptr: deduplicate more method docs) - #142258 (platform-support.md: Mention specific Linux kernel version or later) - #142260 (Miri subtree update) - #142262 (Mark `core::slice::memchr` as `#[doc(hidden)]`) - #142272 (tests: Change ABIs in tests to more future-resilient ones) - #142275 (rustdoc: Refractor `clean_ty_generics`) r? `@ghost` `@rustbot` modify labels: rollup

Specify the behavior of `file!` 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)) 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.

Rollup of 14 pull requests Successful merges: - #134442 (Specify the behavior of `file!`) - #134841 (Look at proc-macro attributes when encountering unknown attribute) - #140372 (Exhaustively handle parsed attributes in CheckAttr) - #140766 (Stabilize keylocker) - #141642 (Note the version and PR of removed features when using it) - #141909 (Add central execution context to bootstrap) - #141992 (use `#[naked]` for `__rust_probestack`) - #142102 (docs: Small clarification on the usage of read_to_string and read_to_end trait methods) - #142124 (Allow transmute casts in pre-runtime-MIR) - #142240 (deduplicate the rest of AST walker functions) - #142258 (platform-support.md: Mention specific Linux kernel version or later) - #142262 (Mark `core::slice::memchr` as `#[doc(hidden)]`) - #142271 (compiler: fn ptrs should hit different lints based on ABI) - #142288 (const_eval: fix some outdated comments) r? `@ghost` `@rustbot` modify labels: rollup

Rollup of 16 pull requests Successful merges: - #134442 (Specify the behavior of `file!`) - #140372 (Exhaustively handle parsed attributes in CheckAttr) - #140766 (Stabilize keylocker) - #141642 (Note the version and PR of removed features when using it) - #141818 (Don't create .msi installer for gnullvm hosts) - #141909 (Add central execution context to bootstrap) - #141992 (use `#[naked]` for `__rust_probestack`) - #142101 (core::ptr: deduplicate more method docs) - #142102 (docs: Small clarification on the usage of read_to_string and read_to_end trait methods) - #142124 (Allow transmute casts in pre-runtime-MIR) - #142240 (deduplicate the rest of AST walker functions) - #142258 (platform-support.md: Mention specific Linux kernel version or later) - #142262 (Mark `core::slice::memchr` as `#[doc(hidden)]`) - #142271 (compiler: fn ptrs should hit different lints based on ABI) - #142275 (rustdoc: Refractor `clean_ty_generics`) - #142288 (const_eval: fix some outdated comments) r? `@ghost` `@rustbot` modify labels: rollup

Rollup merge of #134442 - epage:change, r=workingjubilee Specify the behavior of `file!` 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)) 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.

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 removed the proposed-final-comment-period Proposed to merge/close by relevant subteam, see T-<team> label. Will enter FCP once signed off. label 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

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

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

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

epage force-pushed the change branch from c182007 to fea6a22 Compare June 9, 2025 20:25

bors added the S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. label Jun 10, 2025

workingjubilee mentioned this pull request Jun 10, 2025

Rollup of 13 pull requests #142278

Closed

workingjubilee mentioned this pull request Jun 10, 2025

Rollup of 12 pull requests #142283

Closed

fmease mentioned this pull request Jun 10, 2025

Rollup of 14 pull requests #142290

Closed

fmease mentioned this pull request Jun 10, 2025

Rollup of 16 pull requests #142299

Merged

bors merged commit ea1d186 into rust-lang:master Jun 10, 2025
10 checks passed

rustbot added this to the 1.89.0 milestone Jun 10, 2025

-    /// (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`),

Specify the behavior of file! #134442

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!

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!

Uh oh!

Uh oh!

Uh oh!

workingjubilee commented Jun 10, 2025

Uh oh!

bors commented Jun 10, 2025

Uh oh!

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