`include!` docs don't explain how `mod` is resolved

[StanleyRoberts]

Location (URL)

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

Summary

The include! macro appears to resolve modules before being 'pasted' into the current file. E.g. The following crate fails to compile

/
├── module/
│   └── file.rs
├── module.rs
├── include/
│   └── include_src.rs
└── lib.rs

with file.rs:

pub fn foo() { todo!() }

include_src.rs:

mod file;

fn bar() { file::foo() }

and module.rs:

include!("include/include_src.rs");

The include! macro documentation does not mention this behaviour.

As an aside:
This behaviour is very unintuitive to me, I expected include! to behave exactly like pasting the included code into the current file.
This also makes writing build scripts whose outputs contain mod problematic. In my project, include_src.rs is an output of a build script; I've had to replace the mods with mod file { include!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/module/file.rs")); } which isn't ideal and also seems to disable r-a's Intellisense for file.rs.
It would be useful to have a macro that does not do any sort of parsing/resolution to allow this pattern.

[lolbinarycat]

This definitely should be specified in the docs, but also note you can use the #[path] attribute to manually override what filepath is read for a particular module.

[StanleyRoberts]

@lolbinarycat Thanks for pointing me to #[path], that lets me do what I wantes.
Regarding the documentation, is this something I can just open a PR for?

[ehuss]

There some more context about this in https://github.com/rust-lang/rust/pull/69838/files#r395217057 and #70184.

[carloskiki]

This is unfortunate...

I can fix my use case with #[path = "..."], but this is still unexpected for sure. I assume fixing this would be a breaking change?

[carloskiki]

Here is another footgun on mod resolution.

consider the following structure:

├── first
│   ├── inner.rs
│   └── mod.rs
├── lib.rs
└── second
    ├── inner.rs
    └── mod.rs

lib.rs:

mod first;
mod second;

first/mod.rs

mod inner;

second/mod.rs

include!("../first/mod.rs");

In this case, crate::second::inner points to first/inner.rs, not second/inner.rs!