From 1dd2a9dab6a9f625c362957d2da8e39fdf7c50c9 Mon Sep 17 00:00:00 2001 From: Chronocoder Date: Tue, 16 Jun 2026 22:56:32 -0400 Subject: [PATCH] Document module resolution inside `include!` A `mod` declaration in an included file is resolved relative to the included file's directory, not the directory of the file that contains the `include!` invocation. That trips people up, so spell it out in the macro docs and point at the `#[path]` attribute for overriding it. --- library/core/src/macros/mod.rs | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/library/core/src/macros/mod.rs b/library/core/src/macros/mod.rs index c21191dbc19be..1c396477aaaa3 100644 --- a/library/core/src/macros/mod.rs +++ b/library/core/src/macros/mod.rs @@ -1440,6 +1440,14 @@ pub(crate) mod builtin { /// for instance, an invocation with a Windows path containing backslashes `\` would not /// compile correctly on Unix. /// + /// Module declarations (`mod foo;`) inside the included file are resolved relative to the + /// directory of the included file, not the directory of the file that contains the `include!` + /// invocation. For example, if `include!("a/b.rs")` includes a file that contains `mod c;`, + /// the compiler looks for `a/c.rs` or `a/c/mod.rs`. The [`#[path]` attribute][path-attribute] + /// can point a module declaration at a different file when this is not what you want. + /// + /// [path-attribute]: https://doc.rust-lang.org/reference/items/modules.html#the-path-attribute + /// /// # Uses /// /// The `include!` macro is primarily used for two purposes. It is used to include