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?
answer
- two roots, two crates
- one file compiled twice
- type identity includes the crate
- reach the library by its name
basics
~20 slib.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.
solid answer
~40 sIn Cargo's default layout `src/lib.rs` roots a library crate and `src/main.rs` roots a binary crate that depends on it. A `mod` declaration belongs to the crate whose tree it sits in, so `mod storage;` in both roots compiles `src/storage.rs` twice. The library's `notes::storage::Record` and the binary's `crate::storage::Record` share source text but are different types, because a type's identity includes the crate that defines it — hence rustc's "expected `notes::storage::Record`, found `storage::Record`" (E0308). The fix is to declare modules once, in `lib.rs`, make what the binary needs `pub`, and write `use notes::storage::Record;` in `main.rs`. Writing `mod lib;` instead is worse: rustc warns with `special_module_name`, and `lib.rs` then resolves its own children under `src/lib/`.
code
rust · 12 lines// src/main.rs of a package named `notes`.
// src/lib.rs holds `pub mod storage;` and
// `pub fn save(r: &storage::Record)`; src/storage.rs holds
// `pub struct Record { pub id: u32 }`.
use notes::storage::Record;
fn main() {
// Record comes from the library crate's module tree,
// so it is the same type that notes::save expects.
let r = Record { id: 7 };
notes::save(&r); // prints "saved 7"
}go deeper
Recall that src/lib.rs and src/main.rs are two crate roots, and that main.rs reaches library items through the package name, as in notes::storage.
Explain that a mod line belongs to one crate's tree, so a file declared from both roots is compiled twice into distinct types.
Diagnose the E0308 with matching type names quickly, see through the misleading multiple-versions note, and restructure so the library owns every shared module.
The lead angle is package shape: a thin binary over a library keeps logic testable and avoids duplicate modules; set that as the default layout for new tools.
## Two crate roots in one package A Cargo **package** with both `src/lib.rs` and `src/main.rs` builds **two crates** by default (target discovery itself is Cargo's subject, covered with the manifest). Each file is a **crate root** with its own module tree: - the **library crate**, named after the package (here `notes`), rooted at `src/lib.rs`; - the **binary crate**, rooted at `src/main.rs`, which gets the library as a dependency and refers to it as `notes::...`. A `mod` declaration adds a module to the tree of the crate it is written in. It does not and cannot reach into another crate's tree. ## What goes wrong when both roots say `mod storage;` Picture the CLI split into modules: `lib.rs` has `pub mod storage;` and `pub fn save(r: &storage::Record)`, and someone also writes `mod storage;` at the top of `main.rs` "so main can see it". Now `src/storage.rs` is compiled **once per crate**: | Declared in | Module path | Type produced | |---|---|---| | `src/lib.rs` | `notes::storage` | `notes::storage::Record` | | `src/main.rs` | `crate::storage` (binary) | the binary's own `storage::Record` | A **type's identity includes the crate that defines it**, so these are two unrelated types that happen to share source text. Passing the binary's `Record` to `notes::save` fails: ```plaintext error[E0308]: mismatched types --> src/main.rs:5:17 | 5 | notes::save(&r); | ----------- ^^ expected `notes::storage::Record`, found `storage::Record` ``` rustc 1.99.1 also adds a note that there are multiple different versions of crate `notes` in the dependency graph. Read it carefully: there is one `notes` crate; the duplication is a module compiled into two crates. Other symptoms of the same mistake: - `dead_code` warnings in the binary's copy for items only the library uses (Clippy's `duplicate_mod` stays silent, since each crate loads the file once); - the module compiled twice, which costs build time; - `static` items that exist twice, so state set through one copy is invisible through the other. ## Reading the diagnostic The error is easy to misread because both types print with the same final name. The tell is the **prefix**: `notes::storage::Record` names the library crate's copy, while the bare `storage::Record` is printed relative to the crate being compiled, the binary. Whenever rustc says it expected one type and found another with an identical name and fields, ask which crate each one belongs to: - two copies of a module declared from two crate roots, as here; - two versions of a real dependency in the graph, the situation the multiple-versions note usually points at; - a type re-declared by hand instead of imported. Only the first is a source-layout problem, and only a `mod` line can cause it. ## The fix: the library owns the modules 1. Declare every shared module **once**, in `src/lib.rs`. 2. Make the items the binary needs `pub` (visibility rules are covered in the lesson on visibility). 3. In `src/main.rs`, reach them through the library's crate name: `use notes::storage::Record;` (`crate::` in `main.rs` means the binary's own root, which has no `storage`). 4. Keep `main.rs` thin: argument parsing and a call into the library. This layout also makes the logic testable from integration tests, which can only see the library crate. ## Why `mod lib;` is not the shortcut it looks like Writing `mod lib;` in `main.rs` makes `lib.rs` a **child module of the binary**, not a reference to the library crate. rustc warns with the `special_module_name` lint ("found module declaration for lib.rs", with the help "to refer to it from other targets, use the library's name as the path"). Worse, `lib.rs` is now an ordinary non-mod-rs module file, so its own `pub mod storage;` is looked up as `src/lib/storage.rs`, and the build fails with E0583. The library crate is still built separately, so even when it compiles you have two copies again. ## Interview checklist - one package can hold two crates; each root has its own tree; - a module file declared from both roots is compiled twice into distinct types; - declare in `lib.rs`, import in `main.rs` by the crate name; - `mod lib;` triggers `special_module_name` and breaks child lookup.
- Does Clippy's duplicate_mod lint catch mod storage; written in both lib.rs and main.rs?No. `duplicate_mod` reports a file loaded as a module more than once within one crate, and here each crate loads it once. In a Clippy run on 1.99.1 over that layout, the only hint was a `dead_code` warning that a field in the binary's copy is never read. The E0308 at the first place the two types meet, or a reviewer, is what catches it.
- Would pub mod storage; in main.rs let the library see the binary's copy?No. Dependencies point one way: the binary depends on the library, never the reverse, so nothing in `lib.rs` can name an item from `main.rs` whatever its visibility. `pub` on a module in a binary root only matters inside that binary. The library must own the module.
- lib.rs and main.rs form one crate, so their modules are shared.
- Declaring mod storage; in both roots just reuses the same compiled module.
- mod lib; in main.rs is how a binary reaches its own library.
- Two structs with identical fields from one file are the same type.
- The E0308 means Cargo pulled two versions of the package from the registry.