SOP: Project Setup

Updated Mar 2026

Overview

How to initialize, structure, and configure a new Rust project from zero to buildable.

Decision Tree

Step-by-Step

1. Create the Project

// Binary project
// $ cargo new my_project
// Creates: src/main.rs, Cargo.toml, .gitignore

// Library project
// $ cargo new my_lib --lib
// Creates: src/lib.rs, Cargo.toml, .gitignore

2. Configure Cargo.toml

[package]
name = "my_project"
version = "0.1.0"
edition = "2021"
rust-version = "1.75"  # Minimum supported Rust version
description = "A brief description"
license = "MIT"

[dependencies]
serde = { version = "1", features = ["derive"] }
tokio = { version = "1", features = ["full"] }  # If async needed
anyhow = "1"  # Application error handling
thiserror = "1"  # Library error types

[dev-dependencies]
pretty_assertions = "1"
tokio = { version = "1", features = ["test-util", "macros"] }

[profile.release]
opt-level = 3
lto = true
strip = true
codegen-units = 1

3. Standard Project Structure

my_project/
├── Cargo.toml
├── Cargo.lock          # Commit for binaries, gitignore for libraries
├── src/
│   ├── main.rs         # Binary entry point
│   ├── lib.rs          # Library root (optional for binaries)
│   ├── error.rs        # Custom error types
│   └── config.rs       # Configuration handling
├── tests/              # Integration tests
│   └── integration.rs
├── benches/            # Benchmarks
│   └── my_bench.rs
├── examples/           # Example programs
│   └── basic.rs
└── .cargo/
    └── config.toml     # Local Cargo config

4. Workspace Setup (Multi-Crate)

# Root Cargo.toml
[workspace]
members = [
    "crates/core",
    "crates/api",
    "crates/cli",
]
resolver = "2"

[workspace.dependencies]
serde = { version = "1", features = ["derive"] }
tokio = { version = "1", features = ["full"] }

# In member Cargo.toml:
[dependencies]
serde = { workspace = true }

5. Configure Tooling

# rustfmt.toml
max_width = 100
edition = "2021"
use_field_init_shorthand = true

# clippy.toml
too-many-arguments-threshold = 8

# .cargo/config.toml
[build]
rustflags = ["-D", "warnings"]

6. Verify Setup

cargo check       # Fast compilation check
cargo clippy       # Lint check
cargo fmt --check  # Format check
cargo test         # Run all tests
cargo build        # Full build

Common Mistakes

Mistake	Fix
Forgetting edition = "2021"	Always specify edition in Cargo.toml
Not committing Cargo.lock for binaries	Commit it for reproducible builds
Using unwrap() in library code	Use ? operator and proper error types
No rust-version field	Set it to prevent builds on old toolchains

Checklist

• [ ] cargo new with correct type (binary/library)
• [ ] Cargo.toml configured with edition, dependencies, profiles
• [ ] Project structure follows conventions
• [ ] rustfmt.toml and clippy configuration
• [ ] cargo check passes
• [ ] cargo clippy passes with no warnings
• [ ] cargo test runs (even if no tests yet)