Project Setup

This page covers the requirements and setup for developing cascette-rs.

Requirements

Rust Toolchain

Minimum Supported Rust Version (MSRV): 1.92.0
Edition: Rust 2024

Install the required toolchain:

rustup install 1.92.0
rustup default 1.92.0

Required components:

rustup component add rustfmt clippy

For WASM development:

rustup target add wasm32-unknown-unknown

Development Tools

Tool	Purpose	Installation
`cargo-deny`	Dependency auditing	`cargo install cargo-deny`
`cargo-nextest`	Test runner	`cargo install cargo-nextest`
`cargo-llvm-cov`	Code coverage	`cargo install cargo-llvm-cov`
`mdbook`	Documentation	`cargo install mdbook` or via `mise install`

Optional Tools

Tool	Purpose	Installation
`ripgrep`	Code search	`cargo install ripgrep` or system package
`hyperfine`	Benchmarking	`cargo install hyperfine`
`cargo-watch`	Auto-rebuild	`cargo install cargo-watch`

Repository Structure

cascette-rs/
├── crates/                    # Workspace members
│   ├── cascette-crypto/       # Cryptographic primitives
│   ├── cascette-formats/      # Binary format parsers
│   └── ...
├── docs/                      # mdBook documentation
│   ├── src/                   # Documentation source
│   └── book.toml              # mdBook configuration
├── deny.toml                  # cargo-deny configuration
├── Cargo.toml                 # Workspace manifest
└── AGENTS.md                  # AI assistant guidance

First-Time Setup

Clone the repository:

git clone https://github.com/wowemulation-dev/cascette-rs.git
cd cascette-rs

Verify the toolchain:

rustc --version  # Should be 1.92.0 or later
cargo --version

Build the workspace:
```
cargo build --workspace
```
Run tests:
```
cargo nextest run --workspace
```

Verify lints pass:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets

IDE Configuration

VS Code

Recommended extensions:

rust-analyzer - Rust language support
Even Better TOML - TOML file support
crates - Dependency version management

Settings (.vscode/settings.json):

{
  "rust-analyzer.check.command": "clippy",
  "rust-analyzer.check.allTargets": true,
  "editor.formatOnSave": true,
  "[rust]": {
    "editor.defaultFormatter": "rust-lang.rust-analyzer"
  }
}

JetBrains (RustRover/IntelliJ)

Install the Rust plugin
Enable “Run rustfmt on save”
Configure clippy as the external linter

Quality Gate

All changes must pass the CI workflow before merging. Run these checks locally:

# Full CI check (run before committing)
cargo fmt --all -- --check && \
cargo clippy --workspace --all-targets && \
cargo nextest run --profile ci --workspace && \
cargo doc --workspace --no-deps

Individual checks:

Command	Purpose
`cargo fmt --all -- --check`	Format verification
`cargo clippy --workspace --all-targets`	Lint checks
`cargo nextest run --profile ci --workspace`	Unit and integration tests
`cargo doc --workspace --no-deps`	Documentation build
`cargo deny check`	Dependency audit

WASM Compatibility

Core libraries must compile to WASM:

cargo check --target wasm32-unknown-unknown -p cascette-crypto
cargo check --target wasm32-unknown-unknown -p cascette-formats

Documentation

Build and serve the documentation locally:

# Build HTML documentation
mdbook build docs

# Serve locally with auto-reload
mdbook serve docs --open

The documentation will be available at http://localhost:3000.

Workspace Configuration

The workspace uses strict linting. Key settings from Cargo.toml:

[workspace.lints.clippy]
# Lint groups
all = { level = "warn", priority = -1 }
pedantic = { level = "warn", priority = -1 }
nursery = { level = "warn", priority = -1 }
cargo = { level = "warn", priority = -1 }

# Safety lints (higher priority)
unwrap_used = { level = "warn", priority = 2 }
panic = { level = "warn", priority = 2 }
todo = { level = "warn", priority = 2 }
unimplemented = { level = "warn", priority = 2 }
expect_used = { level = "warn", priority = 2 }

Library code should avoid unwrap(), expect(), and panic!(). Use Result types and proper error handling instead.

Keyboard shortcuts

cascette-rs