Insufficiently precise documentation of `std::file!` macro

[JohnScience]

Location

https://doc.rust-lang.org/std/macro.file.html

Summary

When describing properties of paths, it's useful to specify whether the given path is absolute or relative. After reading the documentation of std::file, which didn't mention whether it expands to absolute or relative path, I assumed (and rightly so!) that the path must be absolute. However, in my case it expanded to src/lib\nifti_image.rs, to a relative path with alternating component separators. Based on that, I assume that std::file expands to a path that is either

• relative to manifest, regardless of the platform.
• relative to manifest or absolute, depending on the platform.

Since it returns &str instead of OsStr, it would be weird if it would attempt to return absolute paths. However, this is not immediately obvious (to me).

[est31]

Whether it's an absolute or relative path depends on how rustc is invoked. Say you have a program like:

pub fn main() {
    println!("{}", file!());
}

Then you store it in /tmp/a.rs and invoke it via rustc a.rs ; ./a. It will print a.rs. If you now invoke it via rustc /tmp/a.rs ; ./a, it will print /tmp/a.rs.

In cargo, I wasn't able to create an invocation that prints an absolute path. Correct me if I'm wrong, but I think cargo always changes the pwd and then passes relative paths to the program.

One needs to also consider the include!() macro as well as #[path = "..."]mod foo;. If you have a main.rs like:

include!("./b.rs");
fn main() {
    foo();
}

and a b.rs with:

fn foo() {
    println!("{}", file!());
}

Then it will print src/./b.rs. If you include it via include!("b.rs"), it will print src/b.rs, and if you include it via ../src/b.rs, it will print src/../src/b.rs. If the file path passed to include is absolute, the path will also be absolute. Same goes for #[path = "..."] mod foo;

So one cannot say that it's always absolute or always relative. That being said, docs could definitely be improved in that regard. They should however make the distinction between rustc and cargo clear, as not everyone uses rustc through cargo and the intended audience of the standard library docs is all standard library users, including those who use it through buck (folks at meta), bazel (fuchsia), or make (linux kernel).

[the8472]

It will also depend on path-trimming. https://rust-lang.github.io/rfcs/3127-trim-paths.html

[jaques-sam]

include! parses the file where it can be guaranteed at compile time that the given file exists. It would be nice to have a macro available which just retrieves the absolute path (and not the content) of the current file, also validated at compile time.

[RalfJung]

It would indeed be quite useful to have a macro that always gives an absolute path, since otherwise one has to depend on how cargo picks the working directory for the rustc invocation, which has changed in the past and is AFAIK not a stable guarantee.

[RalfJung]

Also see rust-lang/libs-team#478.
Cc @Amanieu