Structuring a Rust Project with Modules

Rust Programming Language

Lesson: Structuring a Rust Project with Modules

In this lesson, we'll explore how to structure a basic Rust project by organizing code into modules. This involves setting up a project, separating functionality into different files, and ensuring visibility across modules using the pub keyword.

1. Creating a New Project

Start by creating a new Rust project using Cargo, Rust's package manager.

Create the project:

cargo new my_project

This command creates a new directory named my_project with the following structure:

my_project/

├── Cargo.toml

└── src/

└── main.rs

Cargo.toml: The configuration file for the project. It defines the project name, version, and dependencies.

src/main.rs: The main entry point of the project. The Rust compiler will look for this file to start running your program.

Navigate to the project directory:

cd my_project

1. Adding a Module

Rust uses modules to help organize code. Let’s create a module to separate out some functionality.

Step 1: Create a New Module File

In the src/ directory, create a new file named helper.rs:

Create helper.rs in src/:

touch src/helper.rs

Now, the structure of your project looks like this:

css

my_project/

├── Cargo.toml

└── src/

    ├── main.rs

    └── helper.rs

Step 2: Define a Function in the helper.rs Module

Open helper.rs and define a public function:

// src/helper.rs

pub fn helper_function() {

println!("Hello from helper function!");

}

pub fn: The pub keyword makes the helper_function public, meaning it can be accessed from outside the helper module (e.g., from main.rs).

The function prints the message "Hello from helper function!".

Step 3: Modify main.rs to Use the helper Module

Now, let’s use the helper module from main.rs.

Open main.rs and modify it to declare the helper module and call the helper_function:

// src/main.rs

mod helper;

fn main() {

    println!("Hello from main!");

    helper::helper_function();

}

    mod helper;: This tells Rust to include the helper module, which is defined in helper.rs.

    helper::helper_function();: This calls the helper_function from the helper module.

1. Building and Running the Project

Now that we have set up the module, let’s build and run the project.

Build the project:

cargo build

This command compiles the project and generates an executable binary. Rust ensures that the project structure and module linkage are correct.

Run the project:

cargo run

The output should be:

Hello from main!

Hello from helper function!

1. Key Concepts Introduced

This lesson introduces several important concepts in Rust’s module system and project structure:

Modules (mod)

The mod keyword is used to declare a module in Rust. In this lesson, we declared the helper module in main.rs using mod helper;, which tells Rust to include the helper.rs file as a module.

Visibility (pub)

In Rust, functions, structs, and other items are private by default. This means they are only accessible within the module where they are defined. To make items accessible from other modules, you must use the pub keyword. In this example, we used pub fn helper_function() to make the helper_function available for use in main.rs.

Project Layout

A typical Rust project is structured with the src/main.rs file as the entry point. You can add additional modules in separate files (like helper.rs) to keep your code organized.

1. Common Mistakes to Avoid

File Not Found for Module (mod helper; Error):

When you declare a module with mod helper;, Rust looks for a file named helper.rs in the src/ directory. If this file doesn't exist, you will get an error. Make sure you create helper.rs in the correct location.

Function Not Found in Module:

If you forget to make your function public by using the pub keyword, it will not be accessible from other modules. Always use pub fn to make the function visible outside its module.

1. Summary of Commands

Here’s a summary of the commands used to build and run the project:

Create a new project:

cargo new my_project

cd my_project

Create a new module file:

touch src/helper.rs

Build the project:

cargo build

Run the project:

cargo run

By following this lesson, you’ve learned how to structure a basic Rust project by splitting code into modules. This modular approach allows you to scale your project as it grows, keeping the code clean and manageable. You also learned how to use the pub keyword to control visibility between modules.

This project structure is foundational for larger Rust projects, enabling better code organization and reusability.

Ben Santora - October 2024