Crate Root

A crate root is the primary source file that the Rust compiler (rustc) uses as the entry point to compile a crate and construct its module tree. It serves as the root node of the crate’s namespace hierarchy, implicitly defining a top-level module named crate.

Standard File Conventions

By default, the Cargo build system looks for specific file paths to identify crate roots:

• Binary Crate: src/main.rs
• Library Crate: src/lib.rs

If a package contains both src/main.rs and src/lib.rs, it possesses two distinct crate roots, resulting in two separate crates (one binary, one library) compiled from the same package. Additional binary crate roots can be defined by placing files in the src/bin/ directory.

Module Tree Construction

The compiler only processes files that are explicitly included in the module tree. The crate root is responsible for declaring top-level child modules using the mod keyword. When the compiler encounters a mod declaration in the crate root, it searches the file system for the corresponding module implementation.

// src/lib.rs (Library Crate Root)

// Declares a child module. The compiler will look for `network.rs` or `network/mod.rs`.
pub mod network; 

// Declares another child module. The compiler will look for `storage.rs` or `storage/mod.rs`.
mod storage;

// Inline module defined directly within the crate root.
mod config {
    pub const TIMEOUT: u32 = 60;
}

Path Resolution

Because the crate root establishes the base of the module hierarchy, absolute paths within the crate always begin with the crate:: prefix, which explicitly references the crate root.

// src/main.rs (Binary Crate Root)

mod parser;
mod engine;

fn main() {
    // Absolute path starting from the crate root
    crate::engine::initialize();
    
    // Relative path (resolves successfully because main is in the crate root)
    parser::parse_input();
}

Compilation Unit Boundary

The crate root defines the strict boundary of the compilation unit. Any .rs file in the project directory that is not declared via a mod statement originating from the crate root—either directly or transitively through child modules—is entirely ignored by the compiler. The compiler parses the crate root first, follows the mod declarations to other files, and aggregates all reachable modules into a single Abstract Syntax Tree (AST) to produce the final binary or library artifact.

Master Rust with Deep Grasping Methodology!

Learn More