Rust (tempoxyz conventions)

Overview

Fast, reproducible Rust workflows aligned with tempoxyz repos: cached toolchains, mold + sccache, clippy-as-error, nextest, feature-matrix checks, docsrs parity, and xtask utilities.

Doc-first, no guessing: Always consult official docs (rust-lang.org/edition-guide, doc.rust-lang.org/std, crate docs on docs.rs). If the exact flag/API/version isn’t in docs or you’re unsure, pause and ask for the correct link instead of inferring.

When to Use

• •Working on Rust crates (tempo, reth-commonware, tempo-commonware, dex-kv, tempo-std, etc.).
• •Adding CI steps or local scripts to match repo expectations.
• •Verifying docs/build across MSRV and nightly.

Core Pattern

1. •

   Toolchain + components

   • •Default: stable; lint: nightly with clippy / rustfmt when required.
   • •MSRV guard: pin (e.g., toolchain: "1.88") and run cargo build --bin <name>.
2. •

   Standard commands (keep consistent with CI)

   • •Setup tools: install toolchains, sccache, mold, nextest, cargo-hack, typos, deny.
   • •Format: cargo fmt --all --check.
   • •Lint: cargo clippy --all-targets --all-features --locked -- -D warnings.
   • •Test: cargo nextest run --no-fail-fast -j num-cpus.
   • •Features: cargo hack check --feature-powerset --depth 1.
   • •Docs: cargo doc --workspace --all-features --no-deps with docsrs flags.
   • •MSRV: pinned-toolchain build (e.g., cargo +1.88 build --bin <name>).
3. •

   Performance

   • •Use mold linker (rui314/setup-mold@v1 or -Zshare-generics not needed).
   • •Enable sccache (mozilla-actions/sccache-action@v0.0.9); set RUSTC_WRAPPER=sccache.
4. •

   Checks

   • •Format: cargo fmt --all --check.
   • •Lint: cargo clippy --all-targets --all-features --locked -- -D warnings.
   • •Tests: cargo nextest run --no-fail-fast -j num-cpus (install via taiki-e/install-action@nextest).
   • •Feature surface: cargo hack check --feature-powerset --depth 1 for broad combos.
   • •Licenses/Deps: cargo deny check (reuse workflow), cargo vet if present.
   • •Typos: typos (crate-ci/typos@v1).
   • •Custom sanity: zepter run check (from tempo).
5. •

   Docs parity

   • •cargo doc --workspace --all-features --no-deps --document-private-items.
   • •RUSTDOCFLAGS: --cfg docsrs -D warnings --show-type-layout --generate-link-to-definition --enable-index-page -Zunstable-options.
6. •

   Xtask utilities

   • •Use existing cargo xtask commands (e.g., cargo xtask generate-genesis ...) instead of ad-hoc scripts.
   • •Keep generated artifacts compared into repo fixtures (diff & fail if drift).
7. •

   Env defaults

   • •CARGO_TERM_COLOR=always, RUST_BACKTRACE=full, RUSTFLAGS="-D warnings" for builds where appropriate.
8. •

   Caching

   • •Combine sccache with Swatinem/rust-cache@v2 in CI; keep lockfiles pinned.

Quick Reference

Common Mistakes

• •Running cargo test without nextest → slower/less parallel.
• •Skipping --locked causing feature drift.
• •Forgetting mold/sccache → slow CI.
• •Leaving RUSTFLAGS unset → warnings slip through.
• •Not updating docs when public API changes; docs job will fail in CI.
• •Missing Justfile or targets drift from CI steps → contributors can’t run parity commands locally.

Red Flags

• •No clippy -D warnings.
• •Feature-powerset not checked in multi-feature crates.
• •MSRV not validated when adding new dependencies.
• •Generated fixtures updated manually instead of via xtask.
• •Docsrs flags missing; doc build passes locally but fails on docs.rs.

Verification

• •cargo fmt && cargo clippy ... && cargo nextest ... passes locally with sccache/mold configured.
• •cargo hack check --feature-powerset --depth 1 passes or is consciously scoped.
• •MSRV build succeeds on pinned toolchain.
• •Docs build with docsrs flags succeeds.

Rationalizations Countered