skip to content

In Rust, how does a #[path] attribute on a mod declaration change where rustc loads the module's file, and how do enclosing inline mod blocks change that lookup?

level: seniorimportance: nice to knowfreq 20%

answer

  1. overrides the mirror rule
  2. relative to the declaring file's directory
  3. inline blocks add directory components
  4. module path stays the same

basics

~20 s

#[path = "x.rs"] on mod name; loads that file instead of name.rs, relative to the declaring file's directory, while the module path stays unchanged. Inside inline mod blocks the base directory gains one component per enclosing block.

solid answer

~40 s

Without an attribute, an outlined module's file mirrors its module path. `#[path = "foo.rs"] mod c;` overrides that: in `src/a/b.rs`, outside any inline block, it loads `src/a/foo.rs`, relative to the directory holding the declaring file — but the module is still `crate::a::b::c`, because the path attribute changes only where the text comes from. Inside an inline block, the inline modules become directory components: `mod inline { #[path = "other.rs"] mod inner; }` in `src/a/b.rs` loads `src/a/b/inline/other.rs`. A file module inside a function body is rejected unless it carries `#[path]`. Since Rust 1.99, a `#[path]` on an inline module with no outlined children draws an `unused_attributes` warning. It is a tool for generated or shared files, used sparingly, because the file tree stops mirroring the module tree.

code

plaintext · 7 lines
plaintext
error: cannot declare a file module inside a block unless it has a path attribute
 --> fnbody.rs:2:5
  |
2 |     mod helper;
  |     ^^^^^^^^^^^
  |
  = note: file modules are usually placed outside of blocks, at the top level of the file

go deeper

for a junior

Recall that #[path] lets a mod declaration load a file with a different name or place, and that the module keeps its normal path.

for a middle

Explain that the path is relative to the declaring file's directory, and how inline mod blocks add directory components to nested lookups.

for a senior

Use #[path] for generated or shared files without loading one file twice, and recognise the block and unused-attribute diagnostics rustc 1.99 emits.

for a principal

The lead angle is readability: every #[path] breaks the file-tree-mirrors-module-tree guarantee, so reserve it for generated code and document each use.

## The default: files mirror the module tree An **outlined module** (`mod name;`) normally lives at a file whose location mirrors its **module path**: ancestors are directories, and the module itself is `name.rs` or `name/mod.rs`. The `path` attribute is the one built-in way to break that mirror. It is listed in the Reference among the attributes that have meaning on a module, alongside `cfg`, `deprecated`, `doc`, the lint attributes and `no_implicit_prelude`. ## `#[path]` outside any inline block Written on an outlined module that is not inside a `mod { ... }` block, the attribute's value is a file path **relative to the directory containing the declaring source file**, for both kinds of source file: | Declaring file | Declaration | File loaded | Module path | |---|---|---|---| | `src/a/b.rs` | `#[path = "foo.rs"] mod c;` | `src/a/foo.rs` | `crate::a::b::c` | | `src/a/mod.rs` | `#[path = "foo.rs"] mod c;` | `src/a/foo.rs` | `crate::a::c` | | `src/lib.rs` | `#[path = "gen/schema_out.rs"] mod schema;` | `src/gen/schema_out.rs` | `crate::schema` | Two points interviewers probe: - **The module path does not change.** `#[path]` swaps the source file; the module is still named by where its `mod` line sits. Callers write `crate::schema`, never anything derived from the file name. - **The base is the file's directory, not a module directory.** In `src/commands.rs`, `#[path = "config.rs"]` means `src/config.rs`, not `src/commands/config.rs`; `"../config.rs"` would point one level above `src/`. ## `#[path]` inside inline module blocks Inline modules (`mod name { ... }`) add **directory components** to the lookup of any outlined module written inside them: 1. In a **mod-rs file** (a crate root or a `mod.rs`), the base is the file's directory plus one directory per enclosing inline module. 2. In a **non-mod-rs file** such as `src/a/b.rs`, the base additionally starts with a directory named after the file's own module. So `mod inline { #[path = "other.rs"] mod inner; }` in `src/a/b.rs` loads `src/a/b/inline/other.rs`, and from `src/a/mod.rs` it loads `src/a/inline/other.rs`. The same nesting applies without the attribute: `mod inline { pub mod inner; }` in `src/main.rs` loads `src/inline/inner.rs`. A `#[path]` on the inline module itself renames that directory component — in `src/main.rs`, `#[path = "thread_files"] mod thread { #[path = "tls.rs"] mod local_data; }` loads `src/thread_files/tls.rs`. ## Rules rustc 1.99 enforces - **File modules in blocks need a path.** `fn main() { mod helper; }` fails with "cannot declare a file module inside a block unless it has a path attribute". - **A useless `#[path]` warns.** Since Rust 1.99, `#[path]` on an inline module that contains no outlined module triggers `unused_attributes` ("`#[path]` is unused on this inline module"); with an outlined child, as in the `thread` example, it is used and no warning appears. - **Loading one file twice is legal but suspicious.** Pointing a second `mod` at a file another `mod` already loads creates a second, distinct module; Clippy's warn-by-default `duplicate_mod` lint reports "file is loaded as a module multiple times" and suggests `use` instead. ## Checking a `#[path]` by hand When a review shows a `#[path]`, three questions settle where the file must be: 1. Is the `mod` inside any inline `mod { ... }` block? If not, start from the directory holding the declaring file. 2. If it is, is the declaring file a mod-rs file (crate root or `mod.rs`)? Then append one directory per enclosing inline module; otherwise first append a directory named after the file's own module. 3. Append the attribute's value. The module's name for callers is still read from the `mod` line alone. When the computed file is missing, rustc stops the build with a "couldn't find file" error naming the path it tried, which is the quickest way to confirm the calculation. ## When it is worth it `#[path]` earns its place for **generated code** written outside the normal layout, for a source file deliberately shared between two crates, and, combined with `cfg_attr`, for choosing a per-platform file (platform layout is covered in the lesson on conditional compilation). Each use costs readers the guarantee that the directory tree shows the module tree, so most codebases treat it as an exception that needs a comment.

  • Since Rust 1.99, what does a custom attribute macro on mod storage; receive?
    Rust 1.99 stabilised custom attribute macros on outlined modules (`#[my_macro] mod storage;`); stable rustc rejected that as unstable before. In a run on 1.99.1 an identity attribute macro printed its input as just `mod storage;`: the macro saw the declaration, not the file's contents, and rustc loaded `src/storage.rs` from the returned tokens afterwards.
  • Does #[path] change how other modules refer to the module it loads?
    No. The module path is fixed by where the `mod` line is written, so `#[path = "gen/schema_out.rs"] mod schema;` in `lib.rs` is still `crate::schema` to every caller. Only the source file behind the module changes, which is why the attribute can be swapped, for example per platform, without touching any call site.

  • #[path] renames the module, so callers use the file's name.
  • #[path] values are relative to the package root, where Cargo.toml lives.
  • Inline mod blocks have no effect on where nested outlined modules are found.
  • A function body may contain mod helper; like any other item.
  • Loading one file from two mod lines shares a single module.

Assumes Rust 1.99: it added the unused_attributes warning for #[path] on inline modules and stabilised custom attribute macros on outlined mod declarations.