Construindo Programas (cargo build-sbf)

Q: Qual diferença entre build-sbf e build-bpf?

sbf é nomenclatura atual bytecode Solana; build-bpf é alias legado em docs antigos.

Q: Onde Anchor coloca artefatos?

target/deploy/.so na raiz do workspace após anchor build.

Q: Testes usam o mesmo build?

anchor test e cargo test-sbf compilam harnesses de teste; deploy ainda usa .so release que você escolhe explicitamente.

Q: Como features afetam tamanho?

Módulos opcionais via #[cfg(feature)] mantêm código não usado fora do .so.

Q: CI deve cachear target/?

Cache target/deploy com chave em toolchain + lockfile para pipelines mais rápidos.

Q: Como inspecionar símbolos?

Use llvm-objdump do bundle platform tools no .so para verificação de entrypoint.

Q: build-sbf executa clippy?

Não - execute cargo clippy separadamente para crates off-chain; lints on-chain são limitados.

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.so

Quando usar:

Crates solana-program nativos 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.so

O que isso demonstra:

cargo build-sbf emite .so ELF deployável para BPF Loader.
--sbf-out-dir controla local de saída para monorepos.
anchor build encapsula 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 .so de 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/*.so

Erros comuns

Deploy de builds debug - 2-10x maiores e mais lentos. Correção: sempre --release para 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 .so obsoleto. Correção: scripte deploy de path fixo target/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.

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.so

Quando usar:

Crates solana-program nativos 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.so

O que isso demonstra:

cargo build-sbf emite .so ELF deployável para BPF Loader.
--sbf-out-dir controla local de saída para monorepos.
anchor build encapsula 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 .so de 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/*.so

Erros comuns

Deploy de builds debug - 2-10x maiores e mais lentos. Correção: sempre --release para 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 .so obsoleto. Correção: scripte deploy de path fixo target/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.

Construindo Programas (cargo build-sbf)

Buscar na documentação

Construindo Programas (cargo build-sbf)