Rust Project Setup

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

Quick Reference

Topic	Reference
Cargo.toml configuration, profiles, dependencies	references/cargo-config.md
Workspace organization, member layout, shared deps	references/workspace-layout.md
GitHub Actions CI, caching, MSRV checks	references/ci-setup.md
Feature flags, conditional compilation, build scripts	references/features-conditional.md
no_std development, embedded targets, cross-compilation	references/no-std.md

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

Use	When
Single crate	Small project, CLI tool, simple library
Workspace	Multiple related crates, shared dependencies, separate compile targets

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

Project Structure

Binary

my-app/
  Cargo.toml
  rustfmt.toml
  src/
    main.rs
    lib.rs      # separate logic from entry point
  tests/
    integration_test.rs

Library

my-lib/
  Cargo.toml
  rustfmt.toml
  src/
    lib.rs
    module_a.rs
    module_b/
      mod.rs
      types.rs
  tests/
    api_test.rs
  examples/
    basic_usage.rs

Workspace

my-workspace/
  Cargo.toml          # [workspace] definition
  rustfmt.toml        # shared formatting
  crates/
    core/             # shared types and logic
    api/              # HTTP server
    cli/              # command-line interface

Dependency Best Practices

• Pin exact versions for binaries:

  serde = "=1.0.210"

• Use version ranges for libraries:

  serde = "1"

• Group features explicitly:

  tokio = { version = "1", features = ["rt-multi-thread", "macros"] }

• Use

  [dev-dependencies]

  for test-only crates
• Review

  cargo tree

  for duplicate versions
• Run

  cargo audit

  for security vulnerabilities
• Replace

  once_cell

  /

  lazy_static

  with

  std::sync::LazyLock

  (stable since Rust 1.80)

Edition 2024 Migration Notes

When migrating existing projects to edition 2024:

• unsafe fn

  bodies now require explicit

  unsafe {}

  blocks around unsafe operations

• extern "C" {}

  blocks must be written as

  unsafe extern "C" {}

• #[no_mangle]

  and

  #[export_name]

  require

  #[unsafe(no_mangle)]

  and

  #[unsafe(export_name)]

• gen

  is a reserved keyword — rename any

  gen

  identifiers to

  r#gen

  or choose a different name

• -> impl Trait

  captures all in-scope lifetimes by default; use

  + use<'a>

  for precise control

• !

  (never type) falls back to

  !

  instead of

  ()

  — review match arms and diverging expressions
• Temporaries in

  if let

  and tail expressions drop earlier — review code holding locks or guards in these positions

Run

cargo fix --edition

to auto-fix most mechanical changes.

Related Skills

• beagle-rust:rust-best-practices

  — idiomatic patterns and edition 2024 coding guidance

• beagle-rust:rust-code-review

  — code review covering ownership, unsafe, and trait design