Toolchain Best Practices

A condensed summary of the 25 most important toolchain practices drawn from every page in this section.

Pin Agave 4.1.1 everywhere: Use agave-install init 4.1.1 so CLI reports 3.0.10 on laptops and CI (Toolchain Overview).
Commit rust-toolchain.toml: Lock Rust 1.91.1 with rustfmt, clippy, and rust-analyzer components (Editor & rust-analyzer Setup).
Use avm per repo: Run avm use 0.32.1 when entering Anchor workspaces - global Anchor drift breaks IDL builds (Version Management).
Align anchor-lang crate to CLI: anchor-lang = "0.32.1" must match Anchor CLI 0.32.1.
Verify PATH order: which solana should resolve to Agave install, not stale Homebrew binaries.
Document install in README: New hires copy one script block - Agave, avm, rustup, Node for clients.
CI prints versions first: Fail fast when solana --version or anchor --version mismatches manifest pins.
Cache toolchain directories: Key Agave and cargo registry caches on version strings for pipeline speed.
Release builds for deploy: cargo build-sbf --release / anchor build before any devnet or mainnet upload (Building Programs).
Track .so size in CI: Log wc -c target/deploy/*.so to catch binary regressions early.
One scaffold per product: Pick create-solana-dapp, mucho, or manual - avoid mixing templates (create-solana-dapp, Mucho CLI).
Bump @solana/kit explicitly: Client package.json should pin 7.0.0 independently of Agave.
Run solana-verify before mainnet: Publish matching local and on-chain hashes for governance (Verifiable Builds).
Deploy only verify pipeline artifacts: Never upload ad-hoc laptop builds to production program IDs.
Pin Surfpool 0.12.0 for fork dev: Document alongside Agave when teams simulate mainnet state.
Pin LiteSVM 0.6.x in test crates: Fast unit tests stay consistent across machines.
Share .vscode/settings.json: linkedProjects and format-on-save reduce macro confusion.
Open workspace root in IDE: Open folder containing Anchor.toml, not isolated programs/* subcrates only.
Clean target on toolchain upgrades: cargo clean after Agave or Anchor version bumps.
Lock Cargo.lock for programs: Reproducible builds require committed lockfiles in program repos.
Avoid nightly Rust for programs: Stable 1.91.1 matches platform tools expectations.
Separate Node and Rust toolchains: nvm/fnm for frontend; rustup for programs - document both.
Automate doctor checks: Script version gates in pnpm doctor or make check-tools for workshops.
Announce toolchain upgrades: Changelog entry with re-test checklist before team-wide bump.
Keep platform tools bundled: Install Agave bundle holistically - partial copies miss cargo-build-sbf.

FAQs

What is the minimum pin set for a new repo?

Agave 4.1.1, Anchor 0.32.1, Rust 1.91.1, @solana/kit 7.0.0 in respective config files.

How do toolchain practices affect security?

Verifiable builds and lockfiles prevent undeclared dependency injection in deployed bytecode.

Should Docker replace local installs?

Docker helps CI; developers still benefit from local Agave for solana logs and deploy iteration.

How often to upgrade Agave?

On security releases or needed features - never auto-float latest in production pipelines.

What breaks most often on upgrade?

Proc-macro / anchor-lang skew and platform tools PATH - run full anchor test after every bump.

Toolchain Overview - stack introduction
Version Management (agave-install / avm) - pinning how-to
Solana CLI Best Practices - CLI operations
Environment Setup Checklist - onboarding

Stack versions: This page was written for Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0, and LiteSVM 0.6.x.

Toolchain Best Practices

A condensed summary of the 25 most important toolchain practices drawn from every page in this section.

Pin Agave 4.1.1 everywhere: Use agave-install init 4.1.1 so CLI reports 3.0.10 on laptops and CI (Toolchain Overview).

Commit rust-toolchain.toml: Lock Rust 1.91.1 with rustfmt, clippy, and rust-analyzer components (Editor & rust-analyzer Setup).

Use avm per repo: Run avm use 0.32.1 when entering Anchor workspaces - global Anchor drift breaks IDL builds (Version Management).

Align anchor-lang crate to CLI: anchor-lang = "0.32.1" must match Anchor CLI 0.32.1.

Verify PATH order: which solana should resolve to Agave install, not stale Homebrew binaries.

Document install in README: New hires copy one script block - Agave, avm, rustup, Node for clients.

CI prints versions first: Fail fast when solana --version or anchor --version mismatches manifest pins.

Cache toolchain directories: Key Agave and cargo registry caches on version strings for pipeline speed.

Release builds for deploy: cargo build-sbf --release / anchor build before any devnet or mainnet upload (Building Programs).

Track .so size in CI: Log wc -c target/deploy/*.so to catch binary regressions early.

One scaffold per product: Pick create-solana-dapp, mucho, or manual - avoid mixing templates (create-solana-dapp, Mucho CLI).

Bump @solana/kit explicitly: Client package.json should pin 7.0.0 independently of Agave.

Run solana-verify before mainnet: Publish matching local and on-chain hashes for governance (Verifiable Builds).

Deploy only verify pipeline artifacts: Never upload ad-hoc laptop builds to production program IDs.

Pin Surfpool 0.12.0 for fork dev: Document alongside Agave when teams simulate mainnet state.

Pin LiteSVM 0.6.x in test crates: Fast unit tests stay consistent across machines.

Share .vscode/settings.json: linkedProjects and format-on-save reduce macro confusion.

Open workspace root in IDE: Open folder containing Anchor.toml, not isolated programs/* subcrates only.

Clean target on toolchain upgrades: cargo clean after Agave or Anchor version bumps.

Lock Cargo.lock for programs: Reproducible builds require committed lockfiles in program repos.

Avoid nightly Rust for programs: Stable 1.91.1 matches platform tools expectations.

Separate Node and Rust toolchains: nvm/fnm for frontend; rustup for programs - document both.

Automate doctor checks: Script version gates in pnpm doctor or make check-tools for workshops.

Announce toolchain upgrades: Changelog entry with re-test checklist before team-wide bump.

Keep platform tools bundled: Install Agave bundle holistically - partial copies miss cargo-build-sbf.

FAQs

What is the minimum pin set for a new repo?

Agave 4.1.1, Anchor 0.32.1, Rust 1.91.1, @solana/kit 7.0.0 in respective config files.

How do toolchain practices affect security?

Verifiable builds and lockfiles prevent undeclared dependency injection in deployed bytecode.

Should Docker replace local installs?

Docker helps CI; developers still benefit from local Agave for solana logs and deploy iteration.

How often to upgrade Agave?

On security releases or needed features - never auto-float latest in production pipelines.

What breaks most often on upgrade?

Proc-macro / anchor-lang skew and platform tools PATH - run full anchor test after every bump.

Stack versions: This page was written for Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0, and LiteSVM 0.6.x.

Toolchain Best Practices

FAQs

Related

Search Documentation

Toolchain Best Practices

FAQs

Related