Skip to content

Update path to use the attribute template #1915

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Update path to use the attribute template #1915

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e93bffc
Unwrap path
ehuss Jun 23, 2025
ffedf0c
Update `path` to use the attribute template
ehuss Jun 23, 2025
9bd7001
Update path for updated attribute template
ehuss Oct 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 27 additions & 17 deletions src/items/modules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,17 +84,37 @@ alternately be expressed with `crate::util`'s contents in a file named
> [!NOTE]
> Prior to `rustc` 1.30, using `mod.rs` files was the way to load a module with nested children. It is encouraged to use the new naming convention as it is more consistent, and avoids having many files named `mod.rs` within a project.

<!-- template:attributes -->
r[items.mod.outlined.path]
### The `path` attribute

r[items.mod.outlined.path.intro]
The directories and files used for loading external file modules can be
influenced with the `path` attribute.
The *`path` [attribute][attributes]* specifies the file to load for a module.

> [!EXAMPLE]
> <!-- ignore: requires external files -->
> ```rust,ignore
> #[path = "other_file.rs"]
> pub mod example;
> ```

r[items.mod.outlined.path.syntax]
The `path` attribute uses the [MetaNameValueStr] syntax to specify the path to the file.

r[items.mod.outlined.path.allowed-positions]
The `path` attribute may only be applied to module declarations.

> [!NOTE]
> `rustc` ignores use in other positions but lints against it. This may become an error in the future.

r[items.mod.outlined.path.duplicates]
Only the first use of `path` on a module has effect.

> [!NOTE]
> `rustc` lints against any use following the first. This may become an error in the future.

r[items.mod.outlined.path.search]
For `path` attributes on modules not inside inline module blocks, the file
path is relative to the directory the source file is located. For example, the
following code snippet would use the paths shown based on where it is located:
For `path` attributes on modules not inside inline module blocks, the file path is relative to the directory the source file is located. For example, the following code snippet would use the paths shown based on where it is located:

<!-- ignore: requires external files -->
```rust,ignore
Expand All @@ -108,16 +128,7 @@ Source File | `c`'s File Location | `c`'s Module Path
`src/a/mod.rs` | `src/a/foo.rs` | `crate::a::c`

r[items.mod.outlined.path.search-nested]
For `path` attributes inside inline module blocks, the relative location of
the file path depends on the kind of source file the `path` attribute is
located in. "mod-rs" source files are root modules (such as `lib.rs` or
`main.rs`) and modules with files named `mod.rs`. "non-mod-rs" source files
are all other module files. Paths for `path` attributes inside inline module
blocks in a mod-rs file are relative to the directory of the mod-rs file
including the inline module components as directories. For non-mod-rs files,
it is the same except the path starts with a directory with the name of the
non-mod-rs module. For example, the following code snippet would use the paths
shown based on where it is located:
For `path` attributes inside inline module blocks, the relative location of the file path depends on the kind of source file the `path` attribute is located in. "mod-rs" source files are root modules (such as `lib.rs` or `main.rs`) and modules with files named `mod.rs`. "non-mod-rs" source files are all other module files. Paths for `path` attributes inside inline module blocks in a mod-rs file are relative to the directory of the mod-rs file including the inline module components as directories. For non-mod-rs files, it is the same except the path starts with a directory with the name of the non-mod-rs module. For example, the following code snippet would use the paths shown based on where it is located:

<!-- ignore: requires external files -->
```rust,ignore
Expand All @@ -132,8 +143,7 @@ Source File | `inner`'s File Location | `inner`'s Module Path
`src/a/b.rs` | `src/a/b/inline/other.rs` | `crate::a::b::inline::inner`
`src/a/mod.rs` | `src/a/inline/other.rs` | `crate::a::inline::inner`

An example of combining the above rules of `path` attributes on inline modules
and nested modules within (applies to both mod-rs and non-mod-rs files):
An example of combining the above rules of `path` attributes on inline modules and nested modules within (applies to both mod-rs and non-mod-rs files):

<!-- ignore: requires external files -->
```rust,ignore
Expand Down