Packages, crates and modules

Why organise code?

A 50-line program fits in main.rs. A 50,000-line program does not. You need to split code into parts with clear names, hide details that other parts should not touch, and reuse code written by others. Rust gives you three levels for this.

A binary crate has a main function and becomes a program you can run. A library crate has no main; it provides code for other crates to use. A package can have one library and several binaries. The library's root file is src/lib.rs, and the binary's root is src/main.rs.

Modules and privacy

mod billing {
    pub fn total_with_gst(amount: u32) -> u32 {
        amount + gst(amount)
    }

    fn gst(amount: u32) -> u32 {      // private: only usable inside billing
        amount * 18 / 100
    }
}

fn main() {
    println!("{}", billing::total_with_gst(1000));   // 1180
    // billing::gst(1000);   // error[E0603]: function `gst` is private
}

Privacy is a design tool. The billing module promises one public function; it can change how gst is calculated inside without breaking anyone. Struct fields are private by default too, even if the struct is pub; mark each field pub that outsiders may use.

Modules in separate files

src/
├── main.rs        // mod billing;  mod inventory;
├── billing.rs     // the contents of mod billing
└── inventory/
    ├── mod.rs     // (older style) or use inventory.rs next to the folder
    └── stock.rs   // mod stock; declared inside inventory

Paths and use

A path names an item: crate::billing::total_with_gst starts at the crate root; super:: means the parent module; self:: the current one. use creates a shortcut so you do not repeat long paths.

use std::collections::HashMap;
use crate::billing::total_with_gst;
use std::io::{self, Write};     // several items at once

fn report() {
    let mut m: HashMap<&str, u32> = HashMap::new();
    m.insert("bill", total_with_gst(500));
}

Using crates from crates.io

crates.io is the public registry of Rust libraries. To use one, add it to Cargo.toml, usually with cargo add, then build. cargo downloads it and its own dependencies.

cargo add rand
cargo add serde --features derive

[dependencies]
rand = "0.9"
serde = { version = "1", features = ["derive"] }

Semver means versions look like MAJOR.MINOR.PATCH. A MAJOR change may break your code; MINOR and PATCH should not. "1.2" in Cargo.toml means "at least 1.2.0 and below 2.0.0". Cargo.lock records the exact versions chosen so every build is the same; commit it for applications.

Common mistakes

• Forgetting pub: "function is private" (E0603). Add pub to the item, and to the module if it is nested.
• Creating billing.rs but forgetting mod billing; in main.rs or lib.rs. Files are not modules until declared.
• Making every field pub. Keep fields private and expose methods, so you can change the inside later.
• Using a crate without adding it to Cargo.toml: "unresolved import". Run cargo add.