Organizing rust projects

August 12, 2022

Introduction

Rust, a system programming language known for its safety and performance, offers several powerful features for code organization. Understanding Rust's project structure—including modules, crates, and workspaces—is fundamental for developers aiming to build scalable, maintainable, and efficient software. This article delves into the nuances of these features, highlighting their purposes, differences, and best practices.

Package, Crate and Module

A package is a collection of one or more crates that provides a set of functionality. A package contains a Cargo.toml file that describes how to build those crates. A package can contain multiple crates, but it must contain at least one crate (either library or binary). The Cargo.toml file is used to manage dependencies, build processes, and other metadata associated with the package.

[package]
name = "my_package"
version = "0.1.0"

A crate is a compilation unit in Rust. It can be either a binary crate (which produces an executable) or a library crate (which produces a library). Crates are the smallest amount of code that the Rust compiler can process. Each crate has its own namespace and is compiled into a binary or a library.

Modules in Rust are the primary way to encapsulate and organize code within a crate (Rust's term for a package or library).

Purpose and Usage

Encapsulation: Modules help in dividing the code within a crate into logical segments.
Namespace Management: They manage namespaces, allowing for the same names to be used in different contexts without conflict.

Defining modules

Defining modules in Rust can be done in several ways, depending on the size and complexity of your codebase. Let's go through each method with code examples and the corresponding folder structure.

1. Basic Module Declaration

For smaller projects or parts of a project, you can define modules directly within a file.

Code Example:

// main.rs
mod greetings {
    pub fn hello() {
        println!("Hello, Rust!");
    }
}
fn main() {
    greetings::hello(); // Using the greetings module
}

Folder Structure:

my_project/
└── src/
    └── main.rs

2. Module in Separate Files

As your project grows, you can move modules to separate files for better organization.

Code Example:

// main.rs
mod greetings;
fn main() {
    greetings::hello(); // Using the greetings module
}

// greetings.rs
pub fn hello() {
    println!("Hello, Rust from a separate file!");
}

Folder Structure:

my_project/
└── src/
    ├── main.rs
    └── greetings.rs

3. Module in Separate Folders

For even larger projects, you might want to organize modules into separate directories, especially when a module has multiple sub-modules.

Code Example:

// main.rs
mod greetings;
fn main() {
    greetings::hello(); // Using the greetings module
    greetings::farewell::goodbye(); // Using a function from a sub-module
}

// greetings/mod.rs
pub mod farewell;
pub fn hello() {
    println!("Hello, Rust from a separate folder!");
}

// greetings/farewell.rs
pub fn goodbye() {
    println!("Goodbye, Rust from a sub-module!");
}

Folder Structure:

my_project/
└── src/
    ├── main.rs
    └── greetings/
        ├── mod.rs
        └── farewell.rs

Common Project Structures

A typical binary crate project (created by `cargo new my_project`) might have the following structure:

my_project/
├── Cargo.toml
├── Cargo.lock
├── src/
│   └── main.rs  // binary crate
├── .gitignore
└── README.md

For a library crate (crated by `cargo new --lib my_project`):

my_library/
├── Cargo.toml
├── src/
│   └── lib.rs. // library crate
├── .gitignore
└── README.md

Package with two crates:

my_library/
├── Cargo.toml
├── src/
│   ├── main.rs  // binary crate
│   └── lib.rs.  // library crate
├── .gitignore
└── README.md

Package with two crates and module:

my_library/
├── Cargo.toml
├── src/
│   ├── main.rs  // binary crate
│   ├── lib.rs.  // library crate
│   └── my_module.rs.  // module with additional code
├── .gitignore
└── README.md

Package with three crates, a package can have multiple binary crates:

my_library/
├── Cargo.toml
├── src/
│   ├── main.rs  // binary crate
│   ├── lib.rs.  // library crate
│   ├── my_module.rs.  // module with additional code
│   └── bin/
│       └── my_bin.rs.  // binary crate
├── .gitignore
└── README.md

Best Practices

Keep the codebase modular with well-defined functionalities.
Regularly update dependencies in Cargo.toml.

Workspaces: Managing Multiple Crates

Workspaces in Rust are a Cargo feature for managing multiple related crates in a single project. They are ideal for large projects with interdependent crates.

Why Use Workspaces?

Unified Dependency Management: A single Cargo.lock file manages dependencies for all member crates.
Efficient Compilation: Shared target directories mean dependencies are compiled only once.
Simplified Project Management: Run tests, builds, and other commands from the workspace root.

Workspace Project Structure

A typical Rust workspace might look like this:

workspace_project/
├── Cargo.toml
├── crate_one/
│   ├── Cargo.toml
│   └── src/
│       └── lib.rs
├── crate_two/
│   ├── Cargo.toml
│   └── src/
│       └── main.rs
├── tests/
├── .gitignore
└── README.md

Note on Workspaces:

In the root Cargo.toml file, you'll need to add a [workspace] section to define the workspace members, like so:

[workspace]
members = [
    "crate_one",
    "crate_two",
]

This setup ensures that crate_one and crate_two are part of the same workspace, allowing them to share dependencies and configurations. Workspaces are particularly useful for larger projects where you need to manage multiple related crates.

Best Practices

Use workspaces for large-scale projects with multiple binaries and/or libraries.
Maintain consistency across crates in coding standards and configurations.

Conclusion

Rust's project organization features—from modules and crates to workspaces—provide a robust framework for building complex software. Modules offer a way to internally structure code within a crate, crates encapsulate code into reusable packages, and workspaces manage multiple interrelated crates. By effectively utilizing these features, developers can create well-organized, efficient, and maintainable Rust applications suitable for a wide range of software development needs.