skip to content

In Rust, a CLI's main.rs says mod config; — where does rustc look for its code, and why is an undeclared src/storage.rs ignored?

level: juniorimportance: must knowfreq 70%

answer

  1. compilation starts at one file
  2. mod is a declaration, not an import
  3. two candidate paths beside the declarer
  4. the module tree decides what compiles

basics

~20 s

rustc loads mod config; from src/config.rs or src/config/mod.rs and makes it crate::config. It starts at the crate root and follows mod declarations, so a file that no mod (or include! call) names is never parsed or compiled.

solid answer

~40 s

A crate is compiled from one root file — `src/main.rs` for a binary, `src/lib.rs` for a library in Cargo's default layout — and every other file joins only when a `mod` declaration names it (or, rarely, an `include!` call pulls its text in). `mod config;` in `main.rs` creates the module `crate::config` and tells rustc to read its body from `src/config.rs` or `src/config/mod.rs`; if neither exists the build fails with E0583, and if both exist it fails with E0761. Nothing scans `src/`: a `storage.rs` that no `mod storage;` declares is never parsed, so even a syntax error inside it goes unnoticed. `use` loads no files either; it only shortens a path to a module that a `mod` already declared. Declare each module once, in its parent, and reach it everywhere else by path.

code

plaintext · 8 lines
plaintext
error[E0583]: file not found for module `config`
 --> src/main.rs:1:1
  |
1 | mod config;
  | ^^^^^^^^^^^
  |
  = help: to create the module `config`, create file "src/config.rs" or "src/config/mod.rs"
  = note: if there is a `mod config` elsewhere in the crate already, import it with `use crate::...` instead

go deeper

for a junior

Recall that the crate root is main.rs or lib.rs, that mod config; loads config.rs or config/mod.rs, and that a file nobody declares is not compiled.

for a middle

Explain that mod builds the module tree from the root and use only shortens paths, and read E0583's help line to see which file rustc wanted.

for a senior

Show you can split a large main.rs without behaviour changes, and catch the undeclared-file trap in review: code and tests that silently never build.

for a principal

The lead angle is review hygiene: a stray, undeclared file is dead code nobody notices, so layout changes deserve a look at what the module tree actually includes.

## Compilation starts at the crate root A Rust **crate** is the unit rustc compiles, and it begins at exactly one **crate root** file. In Cargo's default layout that is `src/main.rs` for a binary and `src/lib.rs` for a library (declaring other targets is Cargo's business, covered with the Cargo manifest). The root is the module `crate`, the top of the crate's **module tree**. rustc does not look at any other file until the code it is already reading tells it to. ## What `mod config;` does `mod` is an **item declaration**: it adds a named child module to the module tree at the point where it appears. It comes in two forms that produce the same kind of module: - **inline**: `mod config { ... }` — the body is written right there between braces; - **outlined**: `mod config;` — no body, so rustc loads the body from a file. For an outlined module declared in `src/main.rs`, rustc checks two candidate files: 1. `src/config.rs`, the module's name plus `.rs`, next to the declaring file; 2. `src/config/mod.rs`, a directory named after the module holding a `mod.rs`. Exactly one must exist. The outcomes are fixed by rustc: | Files present | Result | |---|---| | `src/config.rs` only | module `crate::config` built from it | | `src/config/mod.rs` only | module `crate::config` built from it | | neither | **E0583** "file not found for module `config`" | | both | **E0761** "file for module `config` found at both ..." | The module's path comes from where the `mod` line sits, not from the file's name alone: `mod config;` in the crate root makes `crate::config`. ## The module tree, not the file tree rustc walks the module tree, never the directory. Three consequences catch people splitting a growing single-file CLI into `config`, `commands` and `storage`: - **An undeclared file is invisible.** Create `src/storage.rs`, forget `mod storage;`, and the build still succeeds — rustc never opens the file, so even a syntax error in it is not reported, and none of its tests run. - **`use` loads nothing.** `use crate::config::Settings;` brings a name into scope for a module a `mod` already declared; it never causes a file to be read. Paths and `use` are covered in the lesson on paths and imports. - **Declare once, reach by path.** If `commands.rs` also wrote `mod config;`, rustc would look for `src/commands/config.rs` — a different file and a different module — and fail with E0583 when it is missing. The existing module is reached as `crate::config` instead. `mod` is therefore not a textual include: it creates a new, named scope in the tree, and the file's items live inside that scope. Whether those items are reachable from outside depends on `pub`, covered in the lesson on visibility. ## A worked split of the CLI Suppose the single-file tool grows a settings loader, a set of subcommands and an on-disk store. After the split, the crate root holds only declarations and `main`: ```rust // src/main.rs mod commands; mod config; mod storage; fn main() { let settings = config::load(); commands::dispatch(&settings); } ``` Each `mod` line pairs with one file — `src/commands.rs`, `src/config.rs`, `src/storage.rs` — and the three modules become `crate::commands`, `crate::config` and `crate::storage`. The order of the `mod` lines does not matter, and a module that `commands` needs from `storage` is reached as `crate::storage`, not declared again. If `storage.rs` is later deleted while `mod storage;` remains, the build stops with E0583 at that line; if the line is deleted while the file remains, the file silently drops out of the build, along with any `#[test]` functions inside it. That asymmetry is the practical reason to treat the `mod` lines, not the directory listing, as the table of contents of a crate. ## Inline and outlined modules are the same module Moving code from `mod config { ... }` in `main.rs` into `src/config.rs` and leaving `mod config;` behind changes nothing the compiler sees: same path `crate::config`, same privacy, same items. That is why the usual refactor of a long `main.rs` is mechanical: 1. cut the body of an inline module into a file named after it; 2. leave `mod name;` in the parent where the block was; 3. build, and let E0583's help line name the file rustc expected if the placement is wrong. ## Mistakes worth naming in an interview - assuming every `.rs` file under `src/` is compiled; - adding `mod config;` to each file that needs the module, instead of declaring it once in its parent; - expecting `use` to pull a file into the build; - believing the file's name, rather than the `mod` line's position, sets the module path.

  • Should commands.rs also write mod config; so it can call the config module?
    No. `mod config;` inside `commands.rs` declares a new child, `crate::commands::config`, and rustc looks for it at `src/commands/config.rs`, failing with E0583 if that file is missing. The module declared in `main.rs` already exists as `crate::config`; `commands.rs` reaches it by that path or a `use` of it. One `mod` per module, in its parent.
  • Does an inline mod config { ... } behave differently from mod config; with a file?
    No. Both declare the same module at the same path with the same privacy rules; only the location of the source text differs. Moving the block's body into `src/config.rs` and leaving `mod config;` in its place is invisible to the rest of the crate, which is why splitting a large `main.rs` needs no other edits.

The mod lines are a book's table of contents: a chapter file sitting in the manuscript folder is not part of the book until the contents page lists it, and listing a chapter that was never written stops the printing.

  • Every .rs file under src is compiled automatically by Cargo.
  • mod config; pastes the file's text into the current scope, like #include.
  • use crate::config; is what makes rustc read config.rs.
  • Each file that needs config must write its own mod config; line.
  • The file's name alone decides the module path, wherever mod is written.