23.3 Standard Project Directory Structure

cargo new and cargo init create a standard directory layout:

my_project/
├── .git/              # Git repository data (if initialized)
├── .gitignore         # Git ignore file (typically includes /target/)
├── Cargo.toml         # Project manifest file
├── Cargo.lock         # Locked dependency versions
├── src/               # Source code directory
│   └── main.rs        # Main entry point (for binary crates)
│   # Or:
│   └── lib.rs         # Library entry point (for library crates)
└── target/            # Build artifacts (compiled code, cache) - not version controlled
  • Cargo.toml: The manifest file defining the package metadata, dependencies, and build settings. (See Section 23.4).
  • Cargo.lock: An auto-generated file recording the exact versions of all dependencies (direct and transitive) used in a build. This ensures reproducible builds. (See Section 23.4.3).
  • src/: Contains the Rust source code.
    • main.rs: The crate root for a binary application. Must contain a fn main().
    • lib.rs: The crate root for a library.
    • Subdirectories within src/ can contain modules (e.g., src/module_name.rs or src/module_name/mod.rs).
  • target/: Where Cargo places all build output (compiled code, downloaded dependencies, intermediate files). This directory should generally be excluded from version control (e.g., via .gitignore). cargo new automatically creates a suitable .gitignore.
  • Other optional directories:
    • tests/: Contains integration tests.
    • benches/: Contains benchmarks.
    • examples/: Contains example programs using the library.
    • src/bin/: Can contain multiple binary targets within the same crate.