Rust Modules and Crates Explained: mod, pub, use and cargo add

Welcome to episode 17 of Rust for Beginners, a series for complete beginners (no programming experience needed). In the last video, we learned about HashMap. Today, we'll learn how to organise code into modules, and how to use other people's code from crates. Every code block below is the exact code from the video, ready to copy.

• All episodes are in the Rust Tutorial for Beginners playlist.
• Versions used: Rust 1.99.1 on Ubuntu, VS Code with rust-analyzer.

1. New project

Let's create a new project called modules, and open it in VS Code.

cargo new modules
cd modules

2. mod

A module groups related code under a name. We write mod, the name, and the code inside curly braces. Here, a math module with an add function.

src/main.rs:

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

fn main() {
    println!("2 + 3 = {}", math::add(2, 3));
}

Error:

error[E0603]: function `add` is private
 --> src/main.rs:8:34
  |
8 |     println!("2 + 3 = {}", math::add(2, 3));
  |                                  ^^^ private function
  |
note: the function `add` is defined here
 --> src/main.rs:2:5
  |
2 |     fn add(a: i32, b: i32) -> i32 {
  |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Stage A2 – line 2 becomes pub fn add(a: i32, b: i32) -> i32 {

Output: 2 + 3 = 5

3. Path

From main, we reach it with a path: math, two colons, add.

4. Private

Let's run it.

cargo run

5. Error

Error: add is private. Everything in a module is private by default. Only the module itself can use it.

6. pub

To share it, we add pub, short for public. Now it works.

cargo run

7. Own file

As a project grows, each module gets its own file. We create math dot r s, next to main dot r s, and move the functions there.

src/math.rs:

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

pub fn multiply(a: i32, b: i32) -> i32 {
    a * b
}

src/main.rs:

mod math;

use math::{add, multiply};

fn main() {
    println!("2 + 3 = {}", add(2, 3));
    println!("4 * 5 = {}", multiply(4, 5));
}

Output: 2 + 3 = 5 / 4 * 5 = 20

8. mod;

In main, mod math with a semicolon tells Rust: load the module from the file math dot r s.

9. use

And use brings names into scope, so we can write just add, instead of math colon colon add.

10. Run B

Let's run it.

cargo run

11. Crates

A crate is a Rust package. Our project is a crate, and thousands more are shared on crates dot io.

12. cargo add

Let's add one called colored, to print text in colour. cargo add puts it into Cargo.toml for us.

cargo add colored

After cargo add colored, Cargo.toml ends with:

[dependencies]
colored = "3.1.1"

src/main.rs:

mod math;

use colored::Colorize;
use math::{add, multiply};

fn main() {
    println!("2 + 3 = {}", add(2, 3).to_string().green());
    println!("4 * 5 = {}", multiply(4, 5).to_string().blue().bold());
    println!("{}", "Modules and crates!".red().underline());
}

Output: 2 + 3 = 5 (5 in green) / 4 * 5 = 20 (20 in bold blue) / Modules and crates! (red, underlined)

13. Use it

We bring in its Colorize trait with use, and now our strings get new methods, like green, blue, bold, and red.

14. Run C

Let's run it. Cargo downloads and builds the crate the first time, and there are our colours.

cargo run

15. Docs

Every crate's documentation is on docs dot r s, with examples.

Recap

To recap: mod creates a module, private by default. pub makes things public. A module can live in its own file. use shortens paths. And cargo add brings in crates from crates dot io.