Rust Reference ยท Concepts
Rust modules and paths
Reference for Rust modules: mod blocks, paths (crate, self, super), use declarations and re-exports, pub visibility levels, the file layout and name resolution rules.
A module is a named namespace that groups items (functions, types, traits, constants, other modules) and controls their visibility. Every crate has a root module; mod name { ... } declares a child. Items are private to their module (and its descendants) by default, and pub exposes them.
A path names an item. crate::a::b starts at the crate root, self::b at the current module, super::b at the parent, and a plain a::b starts at a name in scope. A use declaration brings a path into scope under a shorter name.
mod shapes { pub fn area(w: f64, h: f64) -> f64 { w * h } } use shapes::area;
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.
Visibility
| Modifier | Visible from |
|---|---|
| (none) | the current module and its descendants |
pub |
everywhere the parent module is reachable |
pub(crate) |
the whole crate |
pub(super) |
the parent module |
pub(self) |
same as private |
pub(in path) |
the named ancestor module |
Visibility applies per item. Making a struct pub does not expose its fields; each field needs its own pub. The variants of a pub enum and the items of a pub trait are public automatically.
File layout
A module declared as mod name; (with a semicolon) loads its body from a file. For a module a in the crate root file (main.rs or lib.rs) the compiler looks for a.rs or a/mod.rs; for a child a::b declared inside a.rs it looks for a/b.rs. The modern style prefers a.rs plus an a/ folder for children over mod.rs. A mod declaration is what adds a file to the crate; a file that is never named by mod is ignored. The #[path = "x.rs"] attribute overrides the lookup. Our runner compiles a single main.rs, so use inline mod name { ... } blocks there.
Name resolution rules
- Edition 2018+ paths: a
usepath starts withcrate,self,super, a crate name (such asstd) or a name in scope. There is no need forextern crate. - Two namespaces for values and types: a unit struct and a function can share a name in different namespaces; modules live with types.
- Prelude:
Option,Vec,String,Box,Some,Okand others are brought in automatically. The edition decides the exact prelude (2024 addsFutureandIntoFuture). - Shadowing: a local item or
useshadows the prelude; a glob import (use a::*) is lower priority than explicit names. - Enum variants can be imported:
use Color::*;oruse Color::{Red, Green};.
Usage notes
- Group imports by crate:
use std::{fmt, io::{self, Read}};. - Idiom: import types and traits directly (
use std::collections::HashMap;) but call functions through their module (fs::read_to_string) so the origin stays visible. pub usebuilds a facade: keep a deep internal layout and expose a flat public API from the crate root.- Unused imports produce a warning (
unused_imports);use ... as _;imports a trait only for its methods, without a name. - Cyclic references between modules are fine within a crate; cycles between crates are not.
- Tests: a
#[cfg(test)] mod tests { use super::*; ... }child module sees private items of its parent.