> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Rust 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.
```rust theme={"dark"}
// 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.
```rust theme={"dark"}
// 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.
Tired of Poor Rust Skills? Fix That With Deep Grasping!
Learn More
