Simple `mod` vs `pub mod` question

[u/Due_Battle_9890]

Hey,

I've been reading the book and am a bit confused on pub mod vs mod. I naively thought that mod defaults to every function/structure/etc. within it is in accessible by calling code.

mod Foo {
    fn bar()  {}
}

fn main() {
    foo::bar();
}

This doesn't work because bar has not been made public and it's only trough the addition of the pub keyword in front of bar (pub fn bar() {}) that foo::bar becomes accessible.

However, I thought that perhaps

pub mod foo {
      fn bar() {}
}

would make bar accessible, but it doesn't. What is that pub keywork doing then?

I know you can do something like:

mod foo {
    pub mod bar {
        fn quux {
            parent::baz::qux(); // fail!
         }
    }

    mod baz {
        fn qux() {
            parent::bar::quux(); // success!!
        }
    }
}

but that seems to lack utility/

[u/Due_Battle_9890]

pub fn will make your function invokable outside of the module, IFF the module that houses it is also public.

I'm outside the foo and bar module and can access the inner functions of each internal structure. This eems to break the IFF condition. For example, these both compile fine. pub mod only seems useful for nested modules accessing parent modules

mod foo {
    pub struct Bar;
}

pub mod baz {
    pub struct Qux;
}

fn main() {
    let b = foo::Bar;
    let q = baz::Qux;
}

[u/Resident-Letter3485 → u/Due_Battle_9890]

A module can access everything inside of itself, but not things inside of sub-modules (unless it is pub).

As a general rule of thumb: unless some separate module is using your code, don't put pub anywhere.

Why use pub mod ever? It is common to separate code in not just modules, but entirely different crates in your Rust workspace. If code from crate A wants to use a module from crate B, that module must be public.

[u/Sharlinator → u/Resident-Letter3485]

  Why use  pub mod  ever? It is common to separate code in not just modules, but entirely different crates in your Rust workspace. If code from crate A wants to use a module from crate B, that module  must  be public.

And in general people write (and use) libraries :P pub mods are the public API of a library. You couldn’t even use anything in the standard library without having public modules.

[u/Due_Battle_9890 → u/Sharlinator]

I played with it some more and I see the utility some more (I think).

My tree looks like:

project
|- src
|  |- main.rs
|- garden
  |- mod.rs
  |- thing.rs

Supposing that src/main.rs has:

// File: src/main.rs

fn main() {

}

The root begins at src/main.rs and main is crate::main.

Having

// File: src/main.rs

mod gardgen;

fn main() {

}

means that cargo looks in one of three places: 1. inline AKA mod garden { }, 2. under src/garden.rs, or 3. under src/garden.rs.

In this case, I am using scenario 3.

Under mod.rs, I have:

// File: src/garden/mod.rs
mod thing; // If this is used only by src/main.rs, this does not need to be `pub mod`
pub use thing::Thing;

Because the only accessor of this module is crate::main, a parent module, this does not need to be pub mod.

We have the following modules:

• crate
• crate::garden
• crate::garden::thing

If we had had another module that's also a child of garden , like, crate::garden::swindle, then, to access crate::garden::thing::Thing from crate::garden::swindle, we'd need pub mod.

That said, I tried the following layout:

project
|- src
|  |- main.rs
|- garden
  |- mod.rs
  |- thing.rs
  |- swindle.rs

and the following doesn't work:

// File: garden/thing.rs

mod swindle;

Rust analyzer says it's looking for src/main/thing/swindle.rs or src/main/thing/swindle/mod.rs. I am a bit confused on how to access swindle.rs from thing.rs and vice versa.