project-rust

Rust Project Management Skill

Skill for managing Rust projects, from setup to deployment.

Purpose

Rust projects have unique requirements:

• Workspace management
• Dependency management with Cargo
• Build optimization
• Cross-compilation
• Testing and benchmarking

When to Use

• Creating new Rust projects
• Setting up Rust workspaces
• Managing dependencies
• Optimizing build times
• Setting up CI/CD
• Cross-compilation

---

Project Structure

Single Crate

my-project/
├── Cargo.toml
├── src/
│   └── main.rs
├── tests/
│   └── integration_test.rs
└── benches/
    └── benchmark.rs

Workspace

my-workspace/
├── Cargo.toml          # Workspace root
├── crates/
│   ├── core/
│   │   ├── Cargo.toml
│   │   └── src/
│   └── utils/
│       ├── Cargo.toml
│       └── src/
└── examples/

Workspace Cargo.toml

[workspace]
members = ["crates/*", "examples/*"]
resolver = "2"

[workspace.package]
version = "0.1.0"
edition = "2021"
authors = ["Author Name <[email protected]>"]

[workspace.dependencies]
# Simple version
serde = "1.0"

# With features
tokio = { version = "1.35", features = ["rt", "sync", "macros"] }

# Specific version with defaults
serde = { version = "1.0.190", default-features = false }

Inheriting Workspace Dependencies

In crate Cargo.toml:

[dependencies]
# Inherit from workspace (recommended)
serde = { workspace = true }

# Inherit with additional features
tokio = { workspace = true, features = ["rt-multi-thread"] }

# Override for specific crate
this-crate-only-dep = "1.0"

---

Dependency Management

Adding Dependencies

# Add dependency
cargo add serde

# Add dev dependency
cargo add --dev tokio

# Add build dependency
cargo add --build cc

# Add with specific version
cargo add [email protected]

Dependency Categories

[dependencies]
# Production dependencies
serde = "1.0"
tokio = { version = "1.0", features = ["full"] }

[dev-dependencies]
# Test only
mockall = "0.12"
criterion = "0.5"

[build-dependencies]
# Build scripts
cc = "1.0"

Feature Flags

[features]
default = ["client", "server"]
client = []
server = []
experimental = []

---

Project Setup

New Project

# Create binary
cargo new my-project

# Create library
cargo new --lib my-library

# Create workspace
mkdir my-workspace
cd my-workspace
cargo new crates/core

Initialize with Template

# Use cargo-generate
cargo install cargo-generate
cargo generate --git https://github.com/rustwasm/wasm-pack-template

# Use axum template
cargo generate --git https://github.com/tokio-rs/axum-template

# Or use a specific template
cargo generate --git https://github.com/tauri-apps/tauri-app-template

---

Build Optimization

Release Profile

[profile.release]
opt-level = 3
lto = "fat"           # Link-time optimization
codegen-units = 1     # Better optimization
strip = true          # Strip symbols
panic = "abort"       # Smaller binary

Tauri-Specific Profile

For Tauri desktop applications:

# For smaller binaries (recommended for desktop)
[profile.release]
opt-level = "s"       # Optimize for size
lto = true
codegen-units = 1
panic = "abort"       # Tauri recommended
strip = true

Or for faster execution:

# For faster execution
[profile.release]
opt-level = 3
lto = "fat"
codegen-units = 1
panic = "abort"

Dev Profile

[profile.dev]
opt-level = 0
debug = true

Incremental Compilation

# Set CARGO_INCREMENTAL
export CARGO_INCREMENTAL=1

# Or in .cargo/config.toml
[build]
incremental = true

---

Workspace Management

Crate Types

# Library
[lib]
name = "my_crate"
crate-type = ["lib", "cdylib", "staticlib"]

# Binary
[[bin]]
name = "my_binary"
path = "src/main.rs"

Internal Dependencies

[dependencies]
my-core = { path = "../core" }

# With features
my-utils = { path = "../utils", features = ["json"] }

Publishing

[package]
name = "my-crate"
version = "0.1.0"
edition = "2021"
license = "MIT"
repository = "https://github.com/user/repo"
description = "A short description"

[package.metadata.docs.rs]
all-features = true

[package.metadata.cargo-make]
# Make tasks

Rust Edition Migration

When migrating between editions:

# Check for edition issues
cargo fix --edition

# Preview changes without applying
cargo fix --edition --dry-run

# Apply migration
cargo fix --edition

Edition	Status	Notes
2015	Stable	Legacy
2018	Stable	Most code compatible
2021	Stable	Default for new projects
2024	Upcoming	Coming late 2024/2025

For Tauri projects, use edition = "2021" (current standard).

---

Testing

Test Configuration

[lib]
test = true

# Integration tests in tests/ directory are automatically discovered
# Only use [[test]] for custom configuration:
[[test]]
name = "integration"
path = "tests/integration/main.rs"
required-features = ["integration"]

Running Tests

# All tests
cargo test

# Specific test
cargo test test_name

# With output
cargo test -- --nocapture

# Doc tests
cargo test --doc

# Release tests
cargo test --release

# Run benchmarks
cargo bench

Test Organization

// Unit tests in same file
#[cfg(test)]
mod tests {
    #[test]
    fn it_works() {
        assert_eq!(2 + 2, 4);
    }
}

// Integration tests in tests/
#[cfg(test)]
mod integration {
    #[test]
    fn test_api() {
        // Test external behavior
    }
}

---

CI/CD

Modern GitHub Actions (Recommended)

name: CI

on:
  push:
    branches: [main]
  pull_request:

env:
  CARGO_TERM_COLOR: always
  SCCACHE_GHA_ENABLED: "true"
  RUSTC_WRAPPER: "sccache"

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # Use sccache for faster builds
      - name: Run sccache-cache
        uses: mozilla-actions/[email protected]

      - uses: dtolnay/rust-toolchain@stable
        with:
          components: rustfmt, clippy

      # Cache dependencies
      - uses: Swatinem/rust-cache@v2

      - run: cargo fmt -- --check
      - run: cargo clippy -- -D warnings
      - run: cargo test

  msrv:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
        with:
          toolchain: 1.75.0
      - run: cargo test

Legacy GitHub Actions (Still Working)

name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
        with:
          components: rustfmt, clippy
      - run: cargo test
      - run: cargo clippy -- -D warnings
      - run: cargo fmt -- --check

Cargo Make

# cargo-make.toml
[tasks.build]
command = "cargo"
args = ["build", "--release"]

[tasks.test]
command = "cargo"
args = ["test", "--all"]

[tasks.lint]
command = "cargo"
args = ["clippy", "--", "-D", "warnings"]

---

Cross-Compilation

Target Triple

# Add target
rustup target add x86_64-unknown-linux-gnu

# Build for target
cargo build --target x86_64-unknown-linux-gnu

# Windows
rustup target add x86_64-pc-windows-gnu
cargo build --target x86_64-pc-windows-gnu

# ARM64 Linux
rustup target add aarch64-unknown-linux-gnu
cargo build --target aarch64-unknown-linux-gnu

Using cross crate (Recommended)

# Install cross
cargo install cross

# Build for different targets
cross build --target x86_64-unknown-linux-gnu
cross build --target aarch64-unknown-linux-gnu

.cargo/config.toml

[build]
target = "x86_64-unknown-linux-gnu"

# Default linker for all targets
[target.x86_64-unknown-linux-gnu]
linker = "clang"

# Windows using lld
[target.x86_64-pc-windows-msvc]
linker = "lld-link"

# ARM cross-compilation
[target.aarch64-unknown-linux-gnu]
linker = "aarch64-linux-gnu-gcc"

---

Documentation

Doc Comments

/// Adds two numbers together.
///
/// # Examples
///
/// ```
/// assert_eq!(add(2, 2), 4);
/// ```
///
/// # Panics
///
/// The function panics if...
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

/// A struct representing a person.
pub struct Person {
    /// The person's name
    name: String,
}

Generate Docs

# Build docs
cargo doc

# Open docs
cargo doc --open

# With all features
cargo doc --all-features --no-deps

---

Best Practices

DO

• Use workspace for multi-crate projects
• Specify MSRV (Minimum Supported Rust Version)
• Use feature flags for optional functionality
• Run cargo update regularly
• Use cargo clippy for linting
• Format code with cargo fmt

DO NOT

• Don't commit lock files for libraries (but do commit for binaries)
• Don't use * in version specifications
• Don't skip tests before publishing
• Don't forget to update version in Cargo.toml

Cargo.lock Strategy

Project Type	Commit Cargo.lock?	CI Strategy
Binary	Yes (required)	Cache in CI
Library	No	Cache generated lock in CI
Workspace	Yes (if contains binaries)	Cache in CI

# In CI for libraries - generate and cache
- name: Cache Cargo.lock
  uses: actions/cache@v3
  with:
    path: |
      ~/.cargo/bin/
      ~/.cargo/registry/index/
      ~/.cargo/registry/cache/
      ~/.cargo/git/db/
      target/
    key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
    restore-keys: |
      ${{ runner.os }}-cargo-

---

Common Commands

# Build
cargo build              # Debug
cargo build --release    # Release

# Test
cargo test              # Run tests
cargo test --lib        # Library tests only
cargo test --doc        # Doc tests only

# Lint
cargo clippy            # Lint with warnings
cargo clippy -- -D warnings

# Format
cargo fmt              # Format code

# D

---

*Content truncated.*