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.

Author: epage

library/core/src/macros/mod.rs

@@ -1287,13 +1287,19 @@ pub(crate) mod builtin {
 
     /// Expands to the file name in which it was invoked.
     ///
-    /// With [`line!`] and [`column!`], these macros provide debugging information for
-    /// developers about the location within the source.
-    ///
-    /// The expanded expression has type `&'static str`, and the returned file
-    /// is not the invocation of the `file!` macro itself, but rather the
-    /// first macro invocation leading up to the invocation of the `file!`
-    /// macro.
+    /// With [`line!`] and [`column!`], these macros provide debugging information for developers
+    /// about the location within the source.
+    ///
+    /// The expanded expression has type `&'static str`, and the returned file is not the invocation
+    /// of the `file!` macro itself, but rather the 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
+    /// (e.g. `./src/lib.rs`) and 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`), modified by any flags passed to the Rust compiler (e.g.
+    /// `--remap-path-prefix`).  If the source path is relative, the initial base directory will be
+    /// the working directory of the Rust compiler.
     ///
     /// # Examples
     ///