Compilación de Programas (cargo build-sbf)
Compila programas on-chain a sBPF ELF con cargo build-sbf, inspecciona el tamaño del artefacto y prepara archivos .so para el despliegue.
Receta
Tarjeta de referencia rápida - lista para copiar y pegar.
cargo build-sbf
cargo build-sbf --release
ls -lh target/deploy/*.so
wc -c target/deploy/my_program.soCuándo usar esto:
- Crates nativos de
solana-programsin el wrapper de Anchor. - Pasos de compilación en CI antes de
solana program deploy. - Seguimiento de regresiones en el tamaño binario frente a los presupuestos de CU/renta.
- Verificación de optimizaciones de lanzamiento antes de mainnet.
Ejemplo de Trabajo
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 de Anchor (llama a build-sbf internamente)
cd ../../
anchor build
ls -lh target/deploy/my_program.soLo que esto demuestra:
cargo build-sbfemite un.soELF desplegable para el BPF Loader.--sbf-out-dircontrola la ubicación de salida para monorepos.anchor buildenvuelve el mismo pipeline con generación de IDL.
Análisis Profundo
Cómo Funciona
- El código fuente se compila a bytecode sBPF con el sysroot específico de Solana y las restricciones de
#![no_std]. - El perfil de lanzamiento habilita optimizaciones críticas para la CU y el tamaño binario.
- El tamaño del
.sode salida impulsa la renta de datos del programa en el momento del despliegue. - El par de claves del programa JSON está separado del artefacto
.so.
Flags de Compilación
| Flag | Propósito |
|---|---|
--release | Binario de producción optimizado |
--sbf-out-dir | Directorio de salida de despliegue personalizado |
--features | Habilitar flags de características del crate |
--tools-version | Sobrescritura de herramientas de plataforma (avanzado) |
Notas de bash
# Muestra advertencias de compilación que afectan a la CU (las importaciones no utilizadas aún consumen tiempo de análisis)
cargo build-sbf 2>&1 | tee build.log
# Compara el tamaño de depuración vs. lanzamiento
cargo build-sbf && wc -c target/deploy/*.so
cargo build-sbf --release && wc -c target/deploy/*.soTrampas
- Despliegue de compilaciones de depuración - 2-10 veces más grandes y lentas. Solución: siempre usar
--releasepara despliegues en devnet/mainnet. - Exceder el tamaño máximo del programa - el cargador rechaza ELFs enormes. Solución: eliminar logs, dividir lógica, optimizar tipos; ver guías de CU/tamaño.
- Ruta de salida incorrecta - el comando de despliegue apunta a un
.soobsoleto. Solución: script de despliegue desde la ruta fijatarget/deploy. - Crate
stdon-chain - el enlace falla o hincha el binario. Solución: usar solo las APIs desolana-program/anchor-lang. - Incompatibilidad de toolchain -
build-sbfde Agave 3.x con peculiaridades del validador 4.x. Solución: alinear con las herramientas de plataforma de Agave 4.1.1.
Alternativas
| Alternativa | Usar Cuando | No Usar Cuando |
|---|---|---|
anchor build | Espacios de trabajo de Anchor + IDL | Crates nativos puros |
cargo build-bpf (legado) | Tutoriales antiguos | Proyectos nuevos de Agave 4.x |
| Imagen Docker de CI con herramientas fijadas | Compilaciones reproducibles | Iteración local rápida |
solana-verify build | Pipeline de hash verificable | Pruebas rápidas en devnet |
Preguntas Frecuentes
¿Cuál es la diferencia entre build-sbf y build-bpf?
sbf es la denominación actual del bytecode de Solana; build-bpf es un alias legado en documentación antigua.
¿Dónde pone Anchor los artefactos?
target/deploy/<program>.so en la raíz del espacio de trabajo después de anchor build.
¿Qué tan grande puede ser un programa?
El cargador impone un tamaño máximo de despliegue (consultar las notas de la versión actual de Agave) - optimizar temprano si se acerca a los límites.
¿Las pruebas usan la misma compilación?
anchor test y cargo test-sbf compilan los harnesses de prueba; el despliegue aún usa el .so de lanzamiento que elijas explícitamente.
¿Puedo compilar cruzado en Apple Silicon?
Las herramientas de plataforma de Agave distribuyen binarios específicos del host - usa el instalador de Agave para tu SO/arquitectura.
¿Cómo afectan las características al tamaño?
Los módulos opcionales a través de #[cfg(feature)] mantienen el código no utilizado fuera del .so.
¿Qué causa tiempos de compilación largos?
El backend LLVM sBPF y LTO - las compilaciones incrementales ayudan; limpia al cambiar de toolchain.
¿Debería CI cachear target/?
Cachea target/deploy indexado por la toolchain + lockfile para pipelines más rápidos.
¿Cómo inspecciono los símbolos?
Usa llvm-objdump del paquete de herramientas de plataforma en el .so para verificar el punto de entrada.
¿`build-sbf` ejecuta clippy?
No - ejecuta cargo clippy por separado para crates off-chain; los lints on-chain son limitados.
Relacionado
- Despliegue de Programas - consume la salida
.so - Compilaciones Verificables (solana-verify) - artefactos reproducibles
- Descripción General de la Toolchain - origen de las herramientas de plataforma
- Optimización de CU y Tamaño - reduce binarios
Versiones de Stack: Esta página fue 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, y LiteSVM 0.6.x.