rust-lang / rust-lang/book

Section 7.2: Ambiguous description of module resolution

Open
#4,334 8 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Rust
Stars
18.3k
Forks
4.1k
Avg merge
14m
Merged PRs (30d)
1

Description

In Chapter 7 of rustbook, Section 7.2 -> Modules Cheat Sheet -> Declaring modules:, the preference of the compiler for module declarations is clearly defined. However, when I tried experimenting with all the three ways, namely:
1 of 3) Inline, within curly brackets that replace the semicolon following mod garden
2 of 3) In the file src/garden.rs
3 of 3) In the file src/garden/mod.rs
I observed inconsistency in the compiler's behaviour when using multiple ways.

To check how these three ways might conflict with each other, I first tried 1 of 3) and 2 of 3) above. The behaviour of the compiler was to silently (as in, no error or warning) prefer 1 of 3) over 2 of 3), effectively ignoring 2 of 3). So, the compilation was successful.

However, when I tried 2 of 3) and 3 of 3), the compiler threw error[E0761], complaining about the module being found in multiple places.

Code (1 of 3) and 2 of 3))
restaurant$ tree
.
├── Cargo.lock
├── Cargo.toml
└── src
    ├── front_of_house
    │   └── hosting.rs
    ├── front_of_house.rs
    ├── lib.rs
    └── main.rs

2 directories, 6 files

restaurant$ cat Cargo.toml 
[package]
name = "restaurant"
version = "0.1.0"
edition = "2021"

[dependencies]

restaurant$ cat src/main.rs 
use restaurant::eat_at_restaurant;

fn main() {
    println!("{}:{}: Hello, world!", file!(), line!());
    eat_at_restaurant();
}

restaurant$ cat src/lib.rs 
mod front_of_house;

pub use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();

restaurant$ cat src/front_of_house.rs 
pub mod hosting {
    pub fn add_to_waitlist() {
        println!("{}:{}: I was called!", file!(), line!());
    }
}

restaurant$ cat src/front_of_house/hosting.rs 
pub fn add_to_waitlist() {
    println!("{}:{}: I was called!", file!(), line!());
}

restaurant$ cargo run
   Compiling restaurant v0.1.0 (/media/nibu/ext4_data/ext4_progprac/Basics/restaurant)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.16s
     Running `target/debug/restaurant`
src/main.rs:4: Hello, world!
src/front_of_house.rs:3: I was called!
Code (2 of 3) and 3 of 3))
restaurant$ tree
.
├── Cargo.lock
├── Cargo.toml
└── src
    ├── front_of_house
    │   ├── hosting
    │   │   └── mod.rs
    │   └── hosting.rs
    ├── front_of_house.rs
    ├── lib.rs
    └── main.rs

3 directories, 7 files

restaurant$ cat Cargo.toml 
[package]
name = "restaurant"
version = "0.1.0"
edition = "2021"

[dependencies]

restaurant$ cat src/main.rs 
use restaurant::eat_at_restaurant;

fn main() {
    println!("{}:{}: Hello, world!", file!(), line!());
    eat_at_restaurant();
}

restaurant$ cat src/lib.rs 
mod front_of_house;

pub use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();

restaurant$ cat src/front_of_house.rs 
pub mod hosting;

restaurant$ cat src/front_of_house/hosting.rs 
pub fn add_to_waitlist() {
    println!("{}:{}: I was called!", file!(), line!());
}

restaurant$ cat src/front_of_house/hosting/mod.rs 
pub fn add_to_waitlist() {
    println!("{}:{}: I was called!", file!(), line!());
}

restaurant$ cargo run
   Compiling restaurant v0.1.0 (/home/user/restaurant)
error[E0761]: file for module `hosting` found at both "src/front_of_house/hosting.rs" and "src/front_of_house/hosting/mod.rs"
 --> src/front_of_house.rs:1:1
  |
1 | pub mod hosting;
  | ^^^^^^^^^^^^^^^^
  |
  = help: delete or rename one of them to remove the ambiguity

error[E0425]: cannot find function `add_to_waitlist` in module `hosting`
 --> src/lib.rs:6:14
  |
6 |     hosting::add_to_waitlist();
  |              ^^^^^^^^^^^^^^^ not found in `hosting`

Some errors have detailed explanations: E0425, E0761.
For more information about an error, try `rustc --explain E0425`.
error: could not compile `restaurant` (lib) due to 2 previous errors

rustc --version --verbose:

rustc 1.84.0-nightly (32b17d56e 2024-10-28)
binary: rustc
commit-hash: 32b17d56eb02495f9865028e1f7271a3a48c0b9b
commit-date: 2024-10-28
host: x86_64-unknown-linux-gnu
release: 1.84.0-nightly
LLVM version: 19.1.1

cargo --version --verbose:

cargo 1.84.0-nightly (e75214ea4 2024-10-25)
release: 1.84.0-nightly
commit-hash: e75214ea4936d2f2c909a71a1237042cc0e14b07
commit-date: 2024-10-25
host: x86_64-unknown-linux-gnu
libgit2: 1.8.1 (sys:0.19.0 vendored)
libcurl: 8.9.0-DEV (sys:0.4.74+curl-8.9.0 vendored ssl:OpenSSL/3.0.2)
os: Ubuntu 22.4.0 (jammy) [64-bit]

I had originally raised this issue as an internal rust compiler issue due to the biased/inconsistent behaviour of the compiler. However, I was advised to open this issue here instead:
https://github.com/rust-lang/rust/issues/139685

Thanks!

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with Chapter 7, Section 7.2, especially the “Modules Cheat Sheet” and “Declaring modules” text, then compare it with the reported Rust compiler behavior and linked compiler issue. Update the explanation so the interaction between inline modules, src/garden.rs, and src/garden/mod.rs is unambiguous, including what happens when multiple forms are present.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.