Gerenciamento de Versão (agave-install / avm)

Q: agave-install substitui solana-install?

Sim - use URLs de release Anza (release.anza.xyz) para Agave 4.x em diante.

Q: Como fixar Rust 1.91.1?

Adicione rust-toolchain.toml com channel = "1.91.1" na raiz do repo.

Q: Dois repos podem usar versões Anchor diferentes?

Sim - execute avm use ao trocar diretórios ou use hooks direnv.

Q: E se anchor build avisar mismatch de versão?

Alinhe avm use, Anchor.toml anchor_version e versão crate anchor-lang à mesma release.

Q: 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.

Q: Como desinstalar versões Agave antigas?

agave-install list depois remova diretórios não usados conforme docs Anza, ou reinstale canal limpo.

Q: 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.

Q: Como fixar @solana/kit?

Use package.json "@solana/kit": "7.0.0" - separado de pins Agave/Anchor.

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 --version

Quando 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 latest quebrar 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.toml

O que isso demonstra:

agave-install init seleciona canal de release validator/CLI.
avm use troca binário anchor no PATH.
anchor_version em Anchor.toml avisa quando mismatch de CLI corromperia builds de IDL.

Aprofundamento

Como funciona

agave-install baixa artefatos de release em ~/.local/share/solana/install/active_release.
PATH do shell antecede aquele diretório bin para solana, cargo-build-sbf, etc.
avm armazena múltiplos builds CLI Anchor em ~/.avm e symlink o ativo.
Rust em si é gerenciado separadamente via rustup (fixe 1.91.1 com rust-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 list

Erros comuns

PATH shadowing - solana do Homebrew sobrescreve install Agave. Correção: which solana e reordene PATH.
avm esquecido no CI - imagem Docker tem Anchor 0.30 enquanto repo precisa 0.32.1. Correção: passo explícito avm use no 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: commite rust-toolchain.toml com 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.

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 --version

Quando 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 latest quebrar 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.toml

O que isso demonstra:

agave-install init seleciona canal de release validator/CLI.
avm use troca binário anchor no PATH.
anchor_version em Anchor.toml avisa quando mismatch de CLI corromperia builds de IDL.

Aprofundamento

Como funciona

agave-install baixa artefatos de release em ~/.local/share/solana/install/active_release.
PATH do shell antecede aquele diretório bin para solana, cargo-build-sbf, etc.
avm armazena múltiplos builds CLI Anchor em ~/.avm e symlink o ativo.
Rust em si é gerenciado separadamente via rustup (fixe 1.91.1 com rust-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 list

Erros comuns

PATH shadowing - solana do Homebrew sobrescreve install Agave. Correção: which solana e reordene PATH.
avm esquecido no CI - imagem Docker tem Anchor 0.30 enquanto repo precisa 0.32.1. Correção: passo explícito avm use no 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: commite rust-toolchain.toml com 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.

Gerenciamento de Versão (agave-install / avm)

Buscar na documentação

Gerenciamento de Versão (agave-install / avm)