skip to content

In Rust, commands.rs declares pub mod run; — where must run's file go, and how do commands.rs and commands/mod.rs differ?

level: middleimportance: should knowfreq 55%

answer

  1. children live in the parent's directory
  2. two names for one parent file
  3. the newer style versus the older
  4. both at once is an error

basics

~10 s

run's code goes in src/commands/run.rs (or src/commands/run/mod.rs). src/commands.rs and src/commands/mod.rs are two allowed locations for the same module's own file; using both at once is error E0761.

solid answer

~40 s

A submodule's file sits in a directory named after its parent module. So `pub mod run;` inside the `commands` module loads `src/commands/run.rs` or `src/commands/run/mod.rs` — and that holds whichever file `commands` itself lives in. The difference between the two styles is only where the parent's own code goes: `src/commands.rs` next to a `src/commands/` directory (the style the Reference recommends), or `src/commands/mod.rs` inside it (the older style, still supported). Putting `run.rs` directly in `src/` fails with E0583, whose help line names `src/commands/run.rs`. Having both `commands.rs` and `commands/mod.rs` is E0761. Mixing the styles across different modules compiles; a team that wants one style enforces it with Clippy's opt-in `mod_module_files` or `self_named_module_files` lints.

code

plaintext · 7 lines
plaintext
error[E0583]: file not found for module `run`
 --> src/commands.rs:1:1
  |
1 | pub mod run;
  | ^^^^^^^^^^^^
  |
  = help: to create the module `run`, create file "src/commands/run.rs" or "src/commands/run/mod.rs"

go deeper

for a junior

Recall that a child module's file goes in a folder named after its parent, so pub mod run; in commands.rs means src/commands/run.rs.

for a middle

Explain mod-rs versus non-mod-rs files, why both styles find run in the same directory, and what E0583 and E0761 each mean.

for a senior

Show you can migrate a crate from mod.rs files to name.rs files without leaving duplicates, and read the help lines to fix placement fast.

for a principal

The lead angle is consistency: pick one style for the codebase and enforce it with a single opt-in Clippy lint rather than review comments.

## The rule rustc applies An **outlined module** (`mod run;`, no body) is loaded from a file whose location mirrors the module's path. **Ancestor modules become directories**, and the module's own code sits in either `<name>.rs` or `<name>/mod.rs` inside its parent's directory. For a CLI being split into `config`, `commands` and `storage`, with `main.rs` declaring `mod commands;` and the commands module declaring `pub mod run;`: | Module path | Where its code can live | |---|---| | `crate` | `src/main.rs` (the crate root) | | `crate::commands` | `src/commands.rs` **or** `src/commands/mod.rs` | | `crate::commands::run` | `src/commands/run.rs` **or** `src/commands/run/mod.rs` | The directory for `run` is `src/commands/` in both styles. What changes between them is only where the **parent's own body** lives. ## Two styles for the same module The Reference names two kinds of source file: - **mod-rs files** — crate roots (`main.rs`, `lib.rs`) and files named `mod.rs`. Their child modules are looked up in the **same directory** as the file, so `src/commands/mod.rs` finds `run` in `src/commands/`. - **non-mod-rs files** — every other module file, such as `src/commands.rs`. Their children are looked up in a **directory named after the module**, so `src/commands.rs` also finds `run` in `src/commands/`. The two layouts on disk: ```plaintext src/main.rs src/main.rs src/commands.rs src/commands/mod.rs src/commands/run.rs src/commands/run.rs ``` The left-hand style is the one the Reference recommends: it is more consistent and avoids an editor full of tabs all named `mod.rs`. The right-hand style was the only way to give a module children before Rust 1.30 and remains fully supported, so older crates still use it. ## The errors that come out of mistakes 1. **The child file in the wrong directory.** Put `run.rs` in `src/` next to `commands.rs` and rustc reports E0583 "file not found for module `run`", with the help line `create file "src/commands/run.rs" or "src/commands/run/mod.rs"`. A file in `src/` belongs to a module declared in the crate root, not to a child of `commands`. 2. **Both parent files present.** With `src/commands.rs` and `src/commands/mod.rs` both on disk, `mod commands;` fails with E0761 "file for module `commands` found at both ...", and the help says to delete or rename one. rustc never picks a winner. 3. **A half-finished migration.** Converting `commands/mod.rs` into `commands.rs` means moving the file, not copying it: a leftover copy is exactly the E0761 case. ## Moving a module from one style to the other Converting `src/commands/mod.rs` to the `commands.rs` style touches one file and no code: 1. move `src/commands/mod.rs` to `src/commands.rs` (a move, not a copy); 2. leave `src/commands/run.rs` where it is — the child's directory is the same in both styles; 3. rebuild: nothing that names `crate::commands::run` changes, because the module path never depended on which style held the parent. The reverse move works the same way. Because the children stay put, a crate can be migrated one module at a time, and a pull request that only renames `mod.rs` files should produce no other diff. If the build reports E0761 afterwards, a copy of the old file survived; if it reports E0583 for a child, a child file was moved along with the parent by mistake. ## Mixing styles, and enforcing one Using `storage/mod.rs` for one module and `commands.rs` for another in the same crate **compiles without a warning**; the Book only notes that it can confuse readers. rustc has no lint for it. Clippy has two **restriction** lints, both allow-by-default, for a team that wants a rule: - `clippy::mod_module_files` warns on every `mod.rs` file ("`mod.rs` files are not allowed") and suggests the `name.rs` form; - `clippy::self_named_module_files` does the reverse ("`mod.rs` files are required") for teams that prefer the older style. Enabling one of them, and only one, is how a codebase stops drifting between the two. Configuring Clippy in a manifest is covered with Cargo's lint settings. ## What to say in an interview - the child's directory is named after the parent module, in both styles; - `foo.rs` with `foo/` and `foo/mod.rs` are two homes for one module's body, never both at once; - E0583 means no candidate file, E0761 means two; - the module tree is set by `mod` lines, so the files must follow it, not the other way round.

  • Does a crate root such as main.rs follow the mod.rs rule or the commands.rs rule for its children?
    The mod.rs rule. Crate roots count as mod-rs files, so `mod commands;` in `src/main.rs` looks in `src/` itself, not in a `src/main/` directory. That is why `src/commands.rs` sits next to `main.rs`. A root behaves like a `mod.rs` for its own directory.
  • How would a team make the whole crate use only the commands.rs plus commands/ style?
    Enable Clippy's restriction lint `clippy::mod_module_files`, which warns on every `mod.rs` file and suggests moving it to the `name.rs` form; it is allow-by-default, so it must be turned on explicitly, for example with `#![warn(clippy::mod_module_files)]` in the crate root. rustc itself accepts both styles, mixed.

  • run.rs goes next to commands.rs, in the same src directory.
  • If both commands.rs and commands/mod.rs exist, rustc prefers the newer one.
  • Only the mod.rs style allows a module to have child files.
  • Mixing both styles in one crate is a compile error.
  • Converting commands/mod.rs to commands.rs means moving run.rs as well.