In Rust, organizing code is achieved through a system of crates, packages, and modules, which bear similarities to concepts found in other programming languages like Java.

A Rust executable program is fundamentally structured around the concept of a "crate." A crate serves as a compilation unit, essentially a library or an executable. For an application to be runnable, it must contain at least one binary crate, typically defined by src/main.rs which includes the main function as its entry point. A "package" in Rust is a collection of one or more crates, managed by Cargo, Rust's build system and package manager. Creating a new package with cargo new generates a project structure that can include both binary and library crates.

Rust differentiates between binary crates and library crates. Binary crates produce executable files, while library crates provide reusable code that can be dependend upon by other crates. A library crate is conventionally located at src/lib.rs. You can specifically create a library-only package using cargo new --lib <package_name>.

An illustration showing a library crate (lzfmatch) and an executable program package (school) containing a binary crate.

The Module System

At a lower level, applications are composed of modules. Similar to many other languages, Rust allows modules to be nested within each other, creating a hierarchical structure for code organization. There isn't a strict limit on the depth of this nesting, though practical considerations usually prevent excessive layering.

A simplified diagram illustrating the relationship between crates and modules.

Practical Examples

To better grasp these concepts, let's examine practical implementations.

Code Structure

Consider a scenario with a main application that utilizes modules for student and teacher functionalities. These top-level modules can contain further sub-modules.

For instance, the student module might have sub-modules like student_info and student_course, potentially defined in separate files within a student subdirectory (e.g., student/student_info.rs). In contrast, sub-modules of the teacher module could be defined inline within the same file as the teacher module itself.

// src/teacher.rs

/**
 * Sub-module 1 - Common teacher utilities
 */
pub mod teacher_common {
    // This function can be called from outside the teacher module.
    pub fn teach() {
        println!("Teacher is teaching.");
        // Accessing a private function in another sibling module requires explicit use.
        // Even though they share the same parent, direct access to private members is restricted.
        super::teacher_inner::learn();
        // super::teacher_inner::laugh(); // Attempting to access private members will cause a compile error.
    }
}

/**
 * Sub-module 2 - Family-related utilities (currently empty)
 */
pub mod teacher_family {}

/**
 * Inner module - Private to the teacher module.
 */
mod teacher_inner {
    /**
     * Even if within the same level, if not defined as `pub`,
     * other methods at the same level cannot access it because they belong to different modules.
     */
    pub fn learn() {
        println!("Student is learning.");
    }

    fn laugh() {
        println!("Teacher is laughing.");
    }
}

// Public function within the teacher module.
pub fn go() {
    println!("Entering the teacher module.");
}

Importing and Referencing Items (use statement)

Rust uses the use keyword to bring items (like functions, structs, or enums) into the current scope, making them directly accessible without their full path.

// Typically, you don't need to start with `crate::` for imports within the same crate.
// use crate::student::student_info::stru_student;

// Importing a specific item.
use student::student_info::stru_student;

// Importing all public items from a module. Be cautious with this in larger projects.
use student::student_info::*;

// Importing an item and giving it an alias.
use student::student_course::Course as Subject;

// Declare modules. These lines tell Rust to look for `teacher.rs` and `student.rs`
// (or `teacher/mod.rs` and `student/mod.rs`, etc.) for their definitions.
mod teacher;
mod student;

fn main() {
    // Calling public functions from the declared modules.
    teacher::go();
    student::go();

    // Directly using methods from nested sub-modules.
    teacher::teacher_common::teach();

    // Creating an instance of a struct imported via `use`.
    let stu = stru_student {
        name: "Alice".to_string(),
        sex: "Female".to_string(),
        age: 10,
    };

    // Assuming `print_student` is a function available in this scope.
    // print_student(stu);

    // Using the imported enum with an alias.
    let sub = Subject::Math;
    println!("Selected subject: {:?}", sub);
}

In the example above, the mod keyword is used to declare the existence of modules within the current crate. Subsequently, the use statement brings specific items from these modules into the current scope for easier access.

Re-exporting with pub use

Rust offers a feature called "re-exporting" using pub use. This allows a module to expose items from another module as if they were its own. This is useful for creating cleaner public APIs for your crates.

1. Define a new sub-module, say study, within the teacher module, containing a function study_hard.
2. In teacher.rs, use pub use study::study_hard; to re-export the functon.
3. In main.rs, you can then access study_hard directly through the teacher module, like teacher::study_hard(), without needing to explicitly import the study module.

In summary, Rust organizes code using a hierarchical system of packages, crates (binary or library), and modules. This structure, while seemingly complex initially, provides a robust and familiar way to manage codebases, akin to systems found in languages like Java. Modules can be nested, and pub use offers a powerful mechanism for re-exporting items, enhancing API design.