skip to content

Source File Layout

mod declarations build a module tree from the crate root, and file layout follows it. Interviewers ask how foo.rs and foo/mod.rs differ and where a submodule's file goes.

on this pageshow

questions

4

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.
open as a page

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%

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.

open as a page

In a Rust package with src/lib.rs and src/main.rs that both declare mod storage;, why does passing a storage::Record to a library function fail with E0308?

level: seniorimportance: should knowfreq 40%

basics

~20 s

lib.rs and main.rs are roots of two crates, so each mod storage; compiles storage.rs into its own tree, making two distinct Record types. Declare storage only in the library and use it from main.rs through the package's crate name.

open as a page

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%

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.

open as a page