Rust for C-Programmers

23.3 Standard Project Directory Structure

cargo new and cargo init create a standard directory layout for a package:

my_package/
├── .git/            # Git repository data (if initialized by `cargo new`)
├── .gitignore       # Git ignore file (typically includes /target/)
├── Cargo.toml       # Package manifest file
├── Cargo.lock       # Locked dependency versions (generated after first build/add)
├── src/             # Source code directory for crates
│   └── main.rs      # Crate root for a binary crate
│   # Or:
│   └── lib.rs       # Crate root for a library crate
└── 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 dependency packages (direct and transitive) used in a build. This ensures reproducible builds. (See Section 23.4.3).
• src/: Contains the Rust source code for the package’s crates.
  • main.rs: The crate root for the default binary application crate within the package. Must contain a fn main().
  • lib.rs: The crate root for the default library crate within the package.
  • Subdirectories within src/ can contain modules (e.g., src/module_name.rs or src/module_name/mod.rs) that belong to the main crate (either lib or main) or separate binary crates (see below).
• target/: Where Cargo places all build output (compiled code for crates, downloaded dependencies, intermediate files). This directory should generally be excluded from version control. cargo new automatically creates a suitable .gitignore file for this purpose.
• .git/ and .gitignore: Created by cargo new to facilitate version control with Git. Rust projects/packages are typically managed with Git and hosted on platforms like GitHub or GitLab.
• Other optional directories:
  • tests/: Contains integration tests for the package’s library crate.
  • benches/: Contains benchmarks for the package’s library crate.
  • examples/: Contains example programs using the library crate.
  • src/bin/: Can contain multiple binary crates within the same package (e.g., src/bin/cli_tool.rs creates a binary named cli_tool).