Specify the behavior of file!

[epage]

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]

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]

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.

[joshtriplett]

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]

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

• @joshtriplett
• @nikomatsakis
• @scottmcm
• @tmandry
• @traviscross

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]

@rfcbot reviewed

[traviscross]

@rfcbot reviewed

[rfcbot]

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

[tmandry]

@rfcbot reviewed

[traviscross]

@rustbot labels -I-lang-nominated

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

[traviscross]

...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`),

[tgross35]

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.

[traviscross]

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.

[epage]

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

[joshtriplett]

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.

[traviscross]

@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]

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

[rfcbot]

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]

@bors r+ rollup

[bors]

📌 Commit fea6a22 has been approved by workingjubilee

It is now in the queue for this repository.