Gerenciamento de Versão (agave-install / avm)
Fixe versões Agave/Solana CLI e Anchor com agave-install e avm para que toda máquina e job CI compile e faça deploy contra o mesmo runtime.
Receita
Card de receita de referência rápida - pronto para copiar e colar.
agave-install init 4.1.1
solana --version
avm install 0.32.1
avm use 0.32.1
anchor --versionQuando usar:
- Atualizar o time para Agave 4.1.1 / CLI 3.0.10.
- Alternar entre repos que exigem versões Anchor diferentes.
- Reproduzir ambiente de deploy de produção localmente.
- Corrigir CI após install silencioso de
latestquebrar builds.
Exemplo prático
# Fixar Agave / Solana CLI
sh -c "$(curl -sSfL https://release.anza.xyz/v4.1.1/install)"
agave-install init 4.1.1
solana --version
# Fixar Anchor via avm
cargo install --git https://github.com/coral-xyz/anchor avm --locked --force
avm install 0.32.1
avm use 0.32.1
anchor --version
# Anchor.toml por projeto impõe CLI para comandos anchor
grep '^anchor_version' Anchor.toml || echo 'anchor_version = "0.32.1"' >> Anchor.tomlO que isso demonstra:
agave-install initseleciona canal de release validator/CLI.avm usetroca binárioanchorno PATH.anchor_versionemAnchor.tomlavisa quando mismatch de CLI corromperia builds de IDL.
Aprofundamento
Como funciona
agave-installbaixa artefatos de release em~/.local/share/solana/install/active_release.- PATH do shell antecede aquele diretório
binparasolana,cargo-build-sbf, etc. avmarmazena múltiplos builds CLI Anchor em~/.avme symlink o ativo.- Rust em si é gerenciado separadamente via
rustup(fixe 1.91.1 comrust-toolchain.toml).
Checklist de Fixação
| Camada | Ferramenta | Método de pin |
|---|---|---|
| Validator/CLI | agave-install | init 4.1.1 |
| Anchor CLI | avm | use 0.32.1 |
| crate anchor-lang | Cargo.toml | 0.32.1 |
| Compilador Rust | rustup | rust-toolchain.toml |
Notas bash
# Listar releases Agave instaladas
agave-install list
# Listar versões Anchor instaladas
avm listErros comuns
- PATH shadowing -
solanado Homebrew sobrescreve install Agave. Correção:which solanae reordene PATH. - avm esquecido no CI - imagem Docker tem Anchor 0.30 enquanto repo precisa 0.32.1. Correção: passo explícito
avm useno pipeline. - Mismatch anchor-lang - CLI 0.32.1 com crate 0.30.x falha expansão de macro. Correção: atualize todos crates Anchor juntos.
- Atualizar no meio do sprint sem anúncio - quebra pairing sessions. Correção: documente upgrades no changelog do time.
- Drift default stable rustup - novo stable quebra
cargo build-sbf. Correção: commiterust-toolchain.tomlcom 1.91.1.
Alternativas
| Alternativa | Use quando | Não use quando |
|---|---|---|
Apenas rust-toolchain.toml | Serviços só Rust | Pin completo Solana CLI |
| Shells dev Nix / Docker | Ambientes de time herméticos | Setup rápido laptop solo |
Helpers de versão mucho | Repos template Foundation | Layouts multi-repo customizados |
| Extração manual tarball | Installs air-gapped | Dev normal com internet |
FAQs
agave-install substitui solana-install?
Sim - use URLs de release Anza (release.anza.xyz) para Agave 4.x em diante.
Como fixar Rust 1.91.1?
Adicione rust-toolchain.toml com channel = "1.91.1" na raiz do repo.
Dois repos podem usar versões Anchor diferentes?
Sim - execute avm use ao trocar diretórios ou use hooks direnv.
E se anchor build avisar mismatch de versão?
Alinhe avm use, Anchor.toml anchor_version e versão crate anchor-lang à mesma release.
Como atualizar Agave com segurança?
Instale nova versão, execute anchor test completo e dry-run de deploy no devnet, depois atualize docs do time.
avm gerencia crate anchor-lang?
Não - apenas binário CLI. Cargo.toml ainda fixa dependências de programa.
Como desinstalar versões Agave antigas?
agave-install list depois remova diretórios não usados conforme docs Anza, ou reinstale canal limpo.
CI deve chamar agave-install todo job?
Cache diretório de install com chave na versão 4.1.1 para velocidade; verifique com solana --version cada run.
E versão solana-verify?
Instale release correspondente junto ao Agave ao usar pipelines verifiable build.
Como fixar @solana/kit?
Use package.json "@solana/kit": "7.0.0" - separado de pins Agave/Anchor.
Relacionados
- Visão Geral da Toolchain - o que cada ferramenta faz
- Construindo Programas (cargo build-sbf) - compile após fixar
- Boas Práticas da Toolchain - política do time
- Configuração de Editor e rust-analyzer - IDE usa mesmo pin Rust
Versões da stack: Esta página foi escrita para 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 e LiteSVM 0.6.x.