Rust Project Setup

Step-by-step guidance for setting up new Rust projects with proper configuration, linting, and CI.

Quick Reference

New Project Checklist

1. Create the Project

# Binary
cargo init my-app

# Library
cargo init --lib my-lib

# Workspace (create Cargo.toml manually)
mkdir my-workspace && cd my-workspace

2. Configure Cargo.toml

Set edition, rust-version (MSRV), and metadata:

[package]
name = "my-app"
version = "0.1.0"
edition = "2024"
rust-version = "1.85"

3. Set Up Linting

Add clippy and rustfmt configuration:

# Cargo.toml
[lints.clippy]
all = { level = "deny", priority = 10 }
pedantic = { level = "warn", priority = 3 }

[lints.rust]
future-incompatible = "warn"
nonstandard_style = "deny"
# unsafe_op_in_unsafe_fn is deny-by-default in edition 2024 — no need to set it

Edition 2024 lint defaults: unsafe_op_in_unsafe_fn is deny by default. Unsafe operations inside unsafe fn require explicit unsafe {} blocks. The gen keyword is reserved — use r#gen if needed as an identifier.

# rustfmt.toml
edition = "2024"
reorder_imports = true
imports_granularity = "Crate"
group_imports = "StdExternalCrate"

4. Configure Profiles

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

5. Set Up CI

Add GitHub Actions workflow for check, clippy, test, and fmt. See references/ci-setup.md.

6. Cargo.lock Policy

• Binaries: Commit Cargo.lock (reproducible builds)
• Libraries: Do NOT commit Cargo.lock (consumers resolve their own versions)
• Add to .gitignore for libraries: Cargo.lock

7. Documentation Setup

For library crates, enable doc lints:

// src/lib.rs
#![deny(missing_docs)]

Prefer #[expect(lint)] over #[allow(lint)] for temporary suppressions — it warns when the suppression becomes unnecessary:

#[expect(dead_code, reason = "used in next PR")]
fn upcoming_feature() {}

Workspace vs Single Crate

Workspaces reduce compile times by sharing dependencies and build artifacts across members.

Project Structure

Binary