Construindo Programas (cargo build-sbf)
Compile programas on-chain para ELF sBPF com cargo build-sbf, inspecione tamanho do artefato e prepare arquivos .so para deploy.
Receita
Card de receita de referência rápida - pronto para copiar e colar.
cargo build-sbf
cargo build-sbf --release
ls -lh target/deploy/*.so
wc -c target/deploy/my_program.soQuando usar:
- Crates
solana-programnativos sem wrapper Anchor. - Passos de compile CI antes de
solana program deploy. - Rastrear regressões de tamanho binário contra orçamentos CU/rent.
- Verificar otimizações release antes da mainnet.
Exemplo prático
cd programs/my_native_program
cargo build-sbf --manifest-path Cargo.toml --sbf-out-dir ../../target/deploy
ls -lh ../../target/deploy/
file ../../target/deploy/my_native_program.so
# Equivalente Anchor (chama build-sbf por baixo)
cd ../../
anchor build
ls -lh target/deploy/my_program.soO que isso demonstra:
cargo build-sbfemite.soELF deployável para BPF Loader.--sbf-out-dircontrola local de saída para monorepos.anchor buildencapsula o mesmo pipeline com geração de IDL.
Aprofundamento
Como funciona
- Fonte compila para bytecode sBPF com sysroot específico Solana e restrições
#![no_std]. - Profile release habilita otimizações críticas para CU e tamanho binário.
- Tamanho do
.sode saída dirige rent programdata no deploy. - Keypair JSON do programa é separado do artefato
.so.
Flags de Build
| Flag | Propósito |
|---|---|
--release | Binário de produção otimizado |
--sbf-out-dir | Diretório de saída deploy customizado |
--features | Habilitar feature flags de crate |
--tools-version | Override platform tools (avançado) |
Notas bash
# Mostre warnings de compile que afetam CU (imports não usados ainda custam parse time)
cargo build-sbf 2>&1 | tee build.log
# Compare tamanho debug vs release
cargo build-sbf && wc -c target/deploy/*.so
cargo build-sbf --release && wc -c target/deploy/*.soErros comuns
- Deploy de builds debug - 2-10x maiores e mais lentos. Correção: sempre
--releasepara deploys devnet/mainnet. - Exceder tamanho máximo de programa - loader rejeita ELFs enormes. Correção: remova logs, divida lógica, otimize tipos; veja guias CU/tamanho.
- Caminho de saída errado - comando deploy aponta para
.soobsoleto. Correção: scripte deploy de path fixotarget/deploy. - Crate std on-chain - linking falha ou incha binário. Correção: use apenas APIs
solana-program/anchor-lang. - Mismatch de toolchain - build-sbf de Agave 3.x com quirks validator 4.x. Correção: alinhe com platform tools Agave 4.1.1.
Alternativas
| Alternativa | Use quando | Não use quando |
|---|---|---|
anchor build | Workspaces Anchor + IDL | Crates puramente nativos |
cargo build-bpf (legado) | Tutoriais antigos | Projetos Agave 4.x novos |
| Imagem Docker CI com tools fixadas | Builds reproduzíveis | Iteração local rápida |
solana-verify build | Pipeline hash verificável | Testes devnet rápidos |
FAQs
Qual diferença entre build-sbf e build-bpf?
sbf é nomenclatura atual bytecode Solana; build-bpf é alias legado em docs antigos.
Onde Anchor coloca artefatos?
target/deploy/<program>.so na raiz do workspace após anchor build.
Quão grande pode ser um programa?
Loader impõe tamanho máximo de deploy (verifique release notes Agave atuais) - otimize cedo se aproximar limites.
Testes usam o mesmo build?
anchor test e cargo test-sbf compilam harnesses de teste; deploy ainda usa .so release que você escolhe explicitamente.
Posso cross-compilar em Apple Silicon?
Agave platform tools enviam binários específicos do host - use installer Agave para seu OS/arch.
Como features afetam tamanho?
Módulos opcionais via #[cfg(feature)] mantêm código não usado fora do .so.
O que causa tempos longos de compile?
Backend LLVM sBPF e LTO - builds incrementais ajudam; clean ao trocar toolchains.
CI deve cachear target/?
Cache target/deploy com chave em toolchain + lockfile para pipelines mais rápidos.
Como inspecionar símbolos?
Use llvm-objdump do bundle platform tools no .so para verificação de entrypoint.
build-sbf executa clippy?
Não - execute cargo clippy separadamente para crates off-chain; lints on-chain são limitados.
Relacionados
- Deploy de Programas - consumir saída
.so - Verifiable Builds (solana-verify) - artefatos reproduzíveis
- Visão Geral da Toolchain - origem platform tools
- Otimização de CU e Tamanho - reduzir binários
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.