Modules

mod geometry {
    pub fn square_area(side: f64) -> f64 {
        side * side
    }

    fn internal_helper() {}          // private: invisible outside geometry

    pub mod circle {
        pub fn area(radius: f64) -> f64 {
            std::f64::consts::PI * radius * radius
        }
    }
}

fn main() {
    println!("{}", geometry::square_area(2.0));
    println!("{}", geometry::circle::area(1.0));
    // geometry::internal_helper();   // ERROR: function `internal_helper` is private
}

// src/main.rs
mod geometry;     // tells the compiler: the module is in geometry.rs

fn main() {
    geometry::square_area(2.0);
}

// src/geometry.rs — no `mod geometry { }` around it: the file IS the module
pub fn square_area(side: f64) -> f64 {
    side * side
}

A .rs file that is declared by no mod is not compiled at all: its errors do not even show up.

Layout 1 (2018+ edition, recommended)         Layout 2 (historical)
src/                                          src/
├── main.rs                                   ├── main.rs
├── geometry.rs         ← mod circle;         └── geometry/
└── geometry/                                     ├── mod.rs      ← mod circle;
    └── circle.rs                                 └── circle.rs

Both are equivalent for the compiler. The first avoids having ten mod.rs tabs open in the editor; the second keeps the whole module in a single folder. Pick one and stick to it across the whole project (you cannot have both geometry.rs and geometry/mod.rs).

#[path = "tools/old_code.rs"]
mod compat;

Keep this for special cases (generated code, a file shared between several crates).

src/
├── lib.rs
├── auth.rs
├── auth/
│   ├── login.rs
│   └── session.rs
└── forms.rs

// src/lib.rs
pub mod auth;
pub mod forms;

// src/auth.rs
pub mod login;
mod session;          // private: usable only in auth and its submodules

crate
├── auth
│   ├── login
│   └── session   (private)
└── forms

// src/lib.rs
mod utils;            // declaration: only once

// src/forms.rs
use crate::utils::clean;      // import: in each file that uses it
// mod utils;                 // common ERROR: it would look for src/forms/utils.rs

// These declarations are in a submodule of crate::auth
// (pub(in ...) must name an ancestor of the current module).
pub fn everywhere() {}                 // visible to all, including other crates
pub(crate) fn in_the_crate() {}        // visible in the whole crate, not outside
pub(super) fn at_the_parent() {}       // visible in the parent module
pub(in crate::auth) fn in_auth() {}    // visible in crate::auth and its descendants
pub(self) fn here() {}                 // same as private
fn private() {}

mod internal {
    pub fn tool() {}
}

tool is pub, but internal is private: outside the crate, you cannot reach it (internal::tool is not accessible). The effective visibility is the most restrictive one along the path. The compiler does not complain: pub is useful here for the other modules of the crate.

pub mod bank {
    pub struct Account {
        pub owner: String,   // public
        balance: i64,        // private
    }

    impl Account {
        pub fn new(owner: String) -> Self {
            Self { owner, balance: 0 }
        }
        pub fn balance(&self) -> i64 {
            self.balance
        }
    }
}

fn main() {
    let c = bank::Account::new("Ada".into());
    println!("{}", c.owner);         // OK
    println!("{}", c.balance());     // OK through the method
    // c.balance = 1_000;            // ERROR: private field
    // bank::Account { owner: "x".into(), balance: 5 };   // ERROR: cannot be built outside the module
}

Making Account public does not make its fields public. A single private field forces the other modules to go through a constructor.

pub mod network {
    pub enum State {
        Connected,       // the variants of a pub enum are all public
        Disconnected,
    }
}

let e = network::State::Connected;

A public enum exposes all its variants and all their data. To hide a representation, wrap it in a struct with a private field.

// Absolute: from the root of the crate
crate::auth::login::verify();

// Relative: from the current module
login::verify();            // a submodule of the current module
self::login::verify();      // same, explicit

// Relative to the parent
super::forms::validate();
super::super::config();     // two levels up

// Another crate (dependency)
serde_json::to_string(&x);
::serde_json::to_string(&x);  // :: forces an external crate in case of ambiguity with a local module

use std::collections::HashMap;                     // one name
use std::collections::{HashMap, HashSet};          // several names
use std::io::{self, Read, Write};                  // the module itself + items
use std::{fmt, collections::BTreeMap};             // nested
use std::fmt::Result as FmtResult;                 // rename
use std::io::Result as IoResult;
use std::collections::*;                           // everything (glob): avoid outside tests and preludes
use crate::auth::login;                            // a module of your own crate
use super::Config;                                 // from the parent
use self::internal::tool;                          // from a submodule

use std::fmt;
use std::io;

// Option 1: keep the module as a prefix
fn a() -> fmt::Result { Ok(()) }
fn b() -> io::Result<()> { Ok(()) }

// Option 2: rename at import
use std::fmt::Result as FmtResult;
fn c() -> FmtResult { Ok(()) }

use std::io::Write;     // without this import, .write_all() does not exist

fn write(f: &mut std::fs::File) -> std::io::Result<()> {
    f.write_all(b"hello")
}

use std::fmt::Write as _;   // import the trait without reserving its name

The methods of a trait can only be called if the trait is in scope. as _ is for when another item is already called Write (for example std::io::Write and std::fmt::Write in the same file).

// src/lib.rs
mod forms;
mod auth;

pub use forms::fields::TextField;      // users write my_lib::TextField
pub use auth::login::{login, logout};

The internal organization (forms::fields::...) can change without breaking anyone: only the re-exported path is part of the API.

// src/prelude.rs
pub use crate::forms::{Form, TextField};
pub use crate::auth::{login, logout};
pub use crate::Request;

// src/lib.rs
pub mod prelude;

// On the user's side
use my_lib::prelude::*;

This is what runique::prelude does: a single import gives access to the common types. Keep the prelude for items that are really used everywhere, otherwise it clashes with the user's own names.

// src/lib.rs
pub use sea_orm;          // users write my_lib::sea_orm::...

What it is for: the user does not have to declare the dependency themselves, and they use exactly the version your library uses. Without this, if they declare another version, the types of one are not the types of the other.

#[doc(hidden)]
pub mod __internal {
    pub fn used_by_macros() {}
}

An item sometimes has to be pub because a macro calls it from the user's crate. #[doc(hidden)] removes it from the documentation and signals that it is not a stable API.

#[cfg(test)]
mod tests;                   // compiled only for cargo test

#[cfg(feature = "admin")]
pub mod admin;               // compiled only with the admin feature

#[cfg(unix)]
mod unix;
#[cfg(windows)]
mod windows;

pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

fn internal(x: i32) -> i32 { x * 2 }

#[cfg(test)]
mod tests {
    use super::*;          // imports the whole parent module, private items included

    #[test]
    fn adds() {
        assert_eq!(add(2, 3), 5);
        assert_eq!(internal(2), 4);     // unit tests see private items
    }
}

my_project/
├── Cargo.toml
└── src/
    ├── lib.rs          ← library crate `my_project`
    ├── main.rs         ← binary `my_project`
    └── bin/
        ├── import.rs   ← binary `import`
        └── tool/
            └── main.rs ← binary `tool` (with its own modules)

cargo run                  # runs main.rs
cargo run --bin import

// src/main.rs
use my_project::config::load;     // we go through the crate name, not crate::

fn main() {
    let c = load();
}

A binary is a separate crate: it only sees what is pub in the library. A pub(crate) item in lib.rs is invisible from main.rs or src/bin/. For a command-line tool to use it, it must be pub.

// Option 1: everything in main.rs — impossible to test with integration tests
// Option 2: logic in lib.rs, main.rs only reads the arguments and calls

// src/main.rs
fn main() {
    let args: Vec<String> = std::env::args().collect();
    if let Err(e) = my_project::run(&args) {
        eprintln!("{e}");
        std::process::exit(1);
    }
}

The second form lets the tests (tests/*.rs), the other binaries and other projects reuse the logic.

my_api/
├── Cargo.toml
└── src/
    ├── lib.rs
    ├── main.rs
    ├── models.rs
    ├── models/
    │   ├── user.rs
    │   └── post.rs
    ├── api.rs
    ├── api/
    │   └── routes.rs
    └── database.rs

// src/lib.rs
pub mod models;
pub mod api;
mod database;                         // private: implementation detail

pub use models::{Post, User};         // short API
pub use api::routes::configure;

// src/models.rs
mod post;
mod user;

pub use post::Post;                   // the submodules stay private,
pub use user::User;                   // only the types are exposed

// src/models/user.rs
#[derive(Debug)]
pub struct User {
    pub id: u32,
    pub name: String,
}

impl User {
    pub fn new(id: u32, name: impl Into<String>) -> Self {
        Self { id, name: name.into() }
    }
}

// src/database.rs
use crate::models::User;

pub(crate) fn save(u: &User) {
    println!("saving {}", u.name);
}

// src/api/routes.rs
use crate::database;
use crate::models::User;

pub fn configure() {
    let u = User::new(1, "Alice");
    database::save(&u);
}

// src/main.rs
use my_api::{configure, User};

fn main() {
    configure();
    println!("{:?}", User::new(2, "Bob"));
}

mod a;                    // declares a (a.rs or a/mod.rs), once, in the parent
mod b { }                 // inline module
pub mod c;                // public module

use crate::a::X;          // absolute path
use super::Y;             // parent
use self::b::Z;           // submodule
use std::io::{self, Read};
use std::fmt::Result as FmtResult;
use std::io::Write as _;  // trait in scope, without reserving the name
pub use a::X;             // re-export

pub            pub(crate)            pub(super)            pub(in crate::a)
#[cfg(test)] mod tests { use super::*; }
#[cfg(feature = "x")] pub mod x;