Mapa de la Cadena de Herramientas
La cadena de herramientas de programas y dApps de Solana es una pila de binarios gestionados por versiones que convierten Rust (y a menudo TypeScript) en sBPF desplegable, clientes IDL y hashes verificables en cadena. Una vez que veas qué capa posee cada herramienta, los fallos aleatorios como "funciona en mi máquina", cargo build-sbf roto y la misteriosa deriva de Anchor/CLI dejarán de parecer fallos aleatorios y empezarán a parecer desajustes de la pila.
Visión General de la Cadena de Herramientas es la entrada orientada a recetas; Gestión de Versiones (agave-install / avm), Compilación de Programas (cargo build-sbf), create-solana-dapp, Mucho CLI, Configuración del Editor y rust-analyzer y Compilaciones Verificables (solana-verify) se centran en cada pieza. Esta página se sitúa debajo: cómo encajan las piezas, qué fijas y qué camino tomar desde el primer programa hasta la verificación de producción.
Resumen
- El desarrollo de Solana es una cadena de herramientas en capas — herramientas del lenguaje Rust, herramientas y CLI de plataforma Agave, Anchor opcional (vía avm), CLIs de scaffold, análisis del editor y compilaciones verificables opcionales — y cada capa debe estar fijada y alineada para una compilación y despliegue reproducibles.
- Por Qué Importa: Las versiones desajustadas de Agave, Anchor y crates causan falsos fallos de "Solana es difícil"; un mapa claro te permite elegir entre trabajo mínimo con CLI, un scaffold de pila completa o compilaciones verificables de grado CI sin adivinar qué binario realmente compila tu
.so. - Conceptos Clave: agave-install, Solana CLI / herramientas de plataforma, cargo build-sbf, avm / Anchor, scaffolding (create-solana-dapp, Mucho), rust-analyzer, solana-verify, fijaciones de pila (stack pins).
- Cuándo Usar: Incorporación de desarrolladores, diseño de CI de repositorios, depuración de deriva de versiones, elección entre scaffold nativo, Anchor o de pila completa, o decisión de cuándo las compilaciones verificables se vuelven obligatorias.
- Limitaciones / Compensaciones: Más capas significan más fijaciones y disciplina de PATH; los scaffolds aceleran la configuración pero aún dependen del mismo Agave y Anchor subyacentes; las compilaciones verificables añaden Docker o entornos controlados y ciclos de lanzamiento más lentos.
- Temas Relacionados: visión general de la cadena de herramientas, gestión de versiones, cargo build-sbf, create-solana-dapp, compilaciones verificables, configuración del editor.
Fundamentos
Solana no te proporciona una única "instalación IDE de Solana" que gestione todo el pipeline. Te proporciona herramientas componibles que cada una responde a una pregunta: qué compilador de lenguaje, qué sysroot de plataforma, qué macros y IDL del framework, qué diseño de proyecto, qué feedback del editor y qué prueba de que los bytes en cadena coinciden con el código fuente.
Esa composición es deliberada. Las herramientas de plataforma (cargo build-sbf, CLI orientada al cargador) rastrean el entorno de runtime y BPF. Anchor rastrea los contratos del framework y IDL. Los scaffolds rastrean el diseño del producto. Los clientes como @solana/kit rastrean las llamadas RPC y transacciones fuera de cadena. Mezclar versiones entre esas uniones es la principal fuente de dolor de compilación en todo el equipo.
Piensa en la pila como capas desde el lenguaje hasta la atestación:
+------------------------------------------+
| Compilaciones verificables (solana-verify) | <- prueba opcional de producción
+------------------------------------------+
| Scaffold / monorepo (create-solana-dapp,|
| Mucho, espacio de trabajo manual) |
+------------------------------------------+
| Framework (Anchor CLI vía avm) | <- opcional pero común
+------------------------------------------+
| Herramientas de plataforma + Solana CLI (Agave) | <- cargo build-sbf, deploy, operaciones RPC
+------------------------------------------+
| Rust (rustup / rust-toolchain.toml) | <- rustc, cargo, analyzer
+------------------------------------------+
| Editor (rust-analyzer, herramientas TS) | <- bucle de feedback, no ruta de despliegue
+------------------------------------------+Rust es la capa de lenguaje para programas en cadena y muchos servicios fuera de cadena. Fíjala con rustup y un rust-toolchain.toml comprometido para que la CI y los portátiles compartan el mismo rustc (este sitio apunta a Rust 1.91.1).
Agave es el linaje de validadores y herramientas mantenido por Anza que distribuye el paquete Solana CLI para desarrolladores y herramientas de plataforma. agave-install selecciona un canal de lanzamiento para que solana, solana-keygen y cargo-build-sbf aterricen juntos en PATH. Este sitio fija Agave 4.1.1 con Solana CLI 3.0.10.
cargo build-sbf es la entrada de compilación cruzada que convierte un crate de programa de Solana en un .so sBPF ELF utilizando sysroots específicos de Solana. Los programas nativos lo llaman directamente; Anchor lo llama bajo anchor build.
Anchor (CLI vía avm, crates como anchor-lang) añade macros de validación de cuentas, generación de IDL y un flujo estándar de pruebas/despliegue. La versión de la CLI y la versión del crate deben moverse juntas (este sitio fija Anchor 0.32.1).
Scaffolds (create-solana-dapp, Mucho CLI, o diseños manuales) no reemplazan a Agave o Anchor. Generan carpetas, scripts y cableado de cliente para que empieces desde una forma de programa-más-aplicación funcional.
Editores y rust-analyzer reducen el bucle de feedback para macros, tipos y refactorizaciones. No distribuyen herramientas de plataforma ni prueban hashes en cadena.
solana-verify reconstruye programas en un entorno controlado y compara los hashes ejecutables con los bytes del programa en cadena para que los auditores y las DAOs puedan confiar en que mainnet coincide con el código fuente público.
Los clientes TypeScript fuera de cadena (este sitio: @solana/kit 7.0.0) se sitúan junto al pipeline del programa para RPC y transacciones; no compilan sBPF ni despliegan programas.
Mecánicas e Interacciones
La gestión de versiones es la columna vertebral
Todo lo demás asume fijaciones alineadas. agave-install init (o el script de instalación de Anza para un lanzamiento) coloca las herramientas CLI y de plataforma bajo un lanzamiento activo compartido. avm install / avm use cambia el binario anchor. rust-toolchain.toml bloquea Rust. La versión anchor_version de Anchor.toml y las versiones de crate de Cargo.toml mantienen honestas las superficies del framework.
rust-toolchain.toml --> rustc / cargo
agave-install --> Solana CLI + cargo-build-sbf + bins del validador
avm + Anchor.toml --> anchor CLI
Cargo.toml --> anchor-lang / dependencias del programa
Imagen CI / Docker --> mismas fijaciones que el portátilSi alguna capa se desvía, los síntomas se manifiestan como cargo-build-sbf faltante, IDL que no coincide con las macros, o despliegues que solo funcionan para un ingeniero. Gestión de Versiones (agave-install / avm) es la inmersión operativa profunda; aquí, recuerda que el orden de PATH importa tanto como los números de versión (Homebrew o scripts de instalación antiguos a menudo sombrean los binarios de Agave).
Cómo un programa se convierte en un .so
El código fuente es Rust ordinario con restricciones de programa de Solana (no_std paths, crates restringidos, target sBPF). cargo build-sbf aplica el sysroot de plataforma y emite target/deploy/<nombre>.so más una ruta de par de claves del programa para la identidad de despliegue.
Anchor envuelve ese pipeline: las macros se expanden en comprobaciones de cuentas y puntos de entrada de instrucciones, anchor build ejecuta la compilación sBPF, y los artefactos IDL alimentan TypeScript u otros clientes. Bajo el capó, el paso de compilación sigue siendo build-sbf; el valor del framework es estructura, validación y codegen, no un segundo formato de bytecode.
programs/foo/src/lib.rs
|
v
[anchor build] -----> cargo build-sbf -----> target/deploy/foo.so
| |
+------> IDL / types +------> solana program deployLos equipos nativos se saltan Anchor y llaman directamente a cargo build-sbf (y a menudo a pruebas de estilo LiteSVM o Mollusk). Los equipos de producto a menudo empiezan con Anchor porque el IDL y las restricciones reducen el código repetitivo. Los detalles se encuentran en Compilación de Programas (cargo build-sbf).
El scaffolding se sitúa por encima de los binarios
create-solana-dapp genera un diseño de pila completa: programa Anchor (o el elegido en la plantilla), aplicación Next.js, hooks de wallet y scripts. Mucho CLI es un superconjunto orientado a la Fundación que envuelve flujos comunes de inicialización, compilación, prueba y despliegue. Ambos asumen que todavía tienes Agave, Rust y, por lo general, Anchor instalados correctamente debajo.
Scaffold para una forma de monorepo conocida; hazlo manualmente para arquitecturas multi-programa o personalizadas. Trata la salida del scaffold como un punto de partida, luego fija las versiones a esta pila antes del trabajo en equipo.
Bucle del editor frente a bucle de despliegue
rust-analyzer indexa crates, expande macros donde está configurado y muestra errores antes de una compilación completa de anchor build. Configura rust-toolchain.toml, enlaza los manifiestos de programas Anchor en monorepos y habilita scripts de compilación para que las superficies de Anchor generadas se resuelvan. Ver Configuración del Editor y rust-analyzer.
El bucle de despliegue sigue siendo impulsado por CLI: compilar, opcionalmente probar contra solana-test-validator o crates de prueba SVM en proceso, luego solana program deploy o anchor deploy contra una URL de clúster y un par de claves. El éxito del editor nunca reemplaza una compilación de lanzamiento limpia en herramientas fijadas.
Las compilaciones verificables cierran la brecha de confianza
cargo build-sbf local puede producir un .so desplegable que aún difiere del artefacto de otra máquina si las cadenas de herramientas, las banderas o la resolución de dependencias difieren. solana-verify reconstruye desde el código fuente en un entorno controlado, hashea el ejecutable y compara ese hash con el programa en cadena a través de RPC.
Código fuente público + herramientas fijadas
|
v
compilación de solana-verify --> hash ejecutable local
|
v
RPC get-program-hash -------> coincidencia / no coincidencia de atestaciónUtiliza la verificación cuando las autoridades de actualización, las auditorías o la gobernanza se preocupen de que el bytecode de mainnet coincida con un commit etiquetado. Detalles: Compilaciones Verificables (solana-verify).
Cómo interactúan las piezas en un día de trabajo
- Instala o cambia Agave 4.1.1 y confirma
solana --version/cargo-build-sbf. - Instala Rust 1.91.1 a través del archivo de toolchain; abre el programa en un editor con rust-analyzer.
avm use 0.32.1(si usas Anchor); asegúrate de que los crates coincidan.- Genera el scaffold o abre el espacio de trabajo; edita instrucciones y cuentas.
anchor buildocargo build-sbf; ejecuta pruebas.- Despliega en localnet o devnet con la configuración de CLI.
- Para lanzamientos de producción, ejecuta solana-verify y publica el hash junto con el commit.
El trabajo del cliente con @solana/kit puede proceder una vez que los IDL o los layouts se estabilicen; nunca sustituye a la ruta de compilación sBPF.
Consideraciones Avanzadas y Aplicaciones
Los equipos no necesitan todas las capas desde el primer día. Adapta el riesgo, el tamaño del equipo y el rigor del lanzamiento a un camino, y luego añade capas cuando el coste de la deriva o la desconfianza supere el coste de las herramientas.
| Camino | Qué instalas y ejecutas | Fortalezas | Debilidades | Mejor ajuste |
|---|---|---|---|---|
| CLI Mínima | rustup, agave-install, cargo build-sbf, solana program deploy | Pocas partes móviles; control total de crates y diseño | Sin IDL/framework; más validación y clientes escritos a mano | Programas nativos/pinocchio, crates críticos para CU, aprendiendo la plataforma básica |
| Scaffold de Anchor | Arriba + avm/Anchor 0.32.1 + plantillas de create-solana-dapp o Mucho | Bucle de producto rápido; IDL; pruebas estándar; valores predeterminados de pila completa | Acoplamiento de versiones del framework; opiniones del scaffold a desmantelar después | La mayoría de los equipos de producto que envían programa + UI web |
| CI Completa con Compilación Verificable | Camino Anchor o nativo + imagen CI bloqueada + solana-verify + compuertas de hash | Artefactos reproducibles; atestaciones listas para auditoría/gobernanza | Pipelines más lentos; disciplina requerida de Docker/fijación de herramientas | Programas de Mainnet con autoridad de actualización, DAOs, aplicaciones reguladas o de alto TVL |
El camino de CLI Mínima es la tabla de verdad para la compilación de Solana: si build-sbf funciona, las herramientas de plataforma están en buen estado. Úsalo para depurar problemas de "Anchor falla" aislando si el fallo es del framework o de la plataforma.
El camino de scaffold de Anchor optimiza para el envío. Fija Anchor CLI, crates y Agave juntos; trata los scripts de plantilla como envoltorios alrededor de la misma historia de despliegue.
La CI completa con compilación verificable trata el artefacto de lanzamiento como un producto. La CI instala versiones exactas de Agave/Anchor/Rust, compila con solana-verify, falla ante desajustes de hash después del despliegue y almacena el SHA del commit con la atestación.
Consejos para Monorepos: enlaza los archivos Cargo.toml del programa para rust-analyzer; fija Node para kit 7.x en .nvmrc; nunca permitas que una instalación global "latest" reescriba PATH a mitad de sprint sin un registro de cambios.
No confundas capas: kit no es despliegue, los scaffolds no son agave-install, el verde del analizador no es la preparación para el lanzamiento de CU, y un hash local casual no es verificación comunitaria.
Para revisiones de diseño, responde primero: qué camino, qué versiones exactas, propiedad de PATH, autoridad de actualización después del despliegue y si el lanzamiento requiere solana-verify.
Conceptos Erróneos Comunes
- "Solo necesito Anchor; Solana CLI es opcional." Las compilaciones y despliegues de Anchor todavía dependen de las herramientas de plataforma de Agave y de Solana CLI en PATH.
- "create-solana-dapp instala toda la cadena de herramientas." Genera archivos de proyecto; tú sigues instalando Rust, Agave y, por lo general, avm/Anchor tú mismo.
- "cargo build-sbf es una cosa de Anchor." Es la ruta de compilación de la plataforma; Anchor lo envuelve, los programas nativos lo llaman directamente.
- "Cualquier rustc reciente está bien para los programas." Las herramientas de plataforma esperan una cadena de herramientas estable compatible; fija 1.91.1 (o la fijación documentada de tu equipo) con
rust-toolchain.toml. - "Coincidir con Anchor CLI es suficiente."
anchor-langy los crates relacionados deben coincidir con la línea principal/secundaria de la CLI o las macros y la generación de IDL fallarán. - "Las compilaciones verificables son solo para investigadores de seguridad." Cualquier programa con confianza pública, autoridad de actualización compartida o requisitos de auditoría se beneficia de la atestación de hash.
- "Los errores del editor equivalen a estar listo para la cadena." El análisis ayuda a la velocidad de edición; la preparación para el despliegue es la compilación de lanzamiento, las pruebas, la configuración del clúster y, a menudo, la verificación.
- "Mucho reemplaza a solana y anchor." Mucho orquesta flujos comunes; los binarios subyacentes siguen siendo Agave CLI y Anchor.
Preguntas Frecuentes
¿Cuál es la idea más importante en la cadena de herramientas de Solana?
Trata el desarrollo como herramientas en capas y con versiones fijadas (Rust, plataforma/CLI de Agave, Anchor opcional, scaffolds, verify) que deben alinearse para que cada máquina produzca el mismo comportamiento de compilación y despliegue.
¿Qué gestiona realmente agave-install?
Instala y cambia los artefactos de lanzamiento de Agave para que los binarios de Solana CLI y las herramientas de plataforma como cargo-build-sbf compartan un lanzamiento activo en PATH.
¿Cómo se relaciona Agave con Solana CLI?
Agave es el linaje de validadores y herramientas mantenido; los comandos orientados al operador siguen teniendo la marca solana y se distribuyen con ese lanzamiento (este sitio: CLI 3.0.10 con Agave 4.1.1).
¿Para qué sirve avm?
Anchor Version Manager instala y selecciona versiones de Anchor CLI de la misma manera que nvm selecciona Node, para que varios repositorios puedan requerir diferentes líneas de Anchor sin caos global.
¿Necesito Anchor para enviar un programa?
No. Los programas nativos se compilan con cargo build-sbf y se despliegan con Solana CLI. Anchor es una herramienta de framework y IDL opcional preferida por muchos equipos de producto.
¿De dónde viene cargo build-sbf?
Se distribuye con las herramientas de plataforma de Agave instaladas junto con el paquete CLI; si falta, reinstala o arregla PATH en lugar de inventar una ruta de gestor de paquetes separada.
¿Cuándo debo usar create-solana-dapp frente a Mucho o un repositorio hecho a mano?
Usa create-solana-dapp para inicios de producto completos de pila completa estilo Next.js, Mucho para flujos de taller y guionizados alineados con la Fundación, y diseños hechos a mano cuando la arquitectura multi-programa o personalizada domine.
¿El scaffolding me fija Agave y Anchor?
Generalmente no por completo. Alinea las versiones después de la generación del scaffold con agave-install, avm y los archivos de toolchain comprometidos para que la plantilla no se desvíe silenciosamente.
¿Qué papel juega rust-analyzer?
Proporciona análisis IDE, navegación y errores tempranos para el código del programa Rust; no reemplaza las herramientas de plataforma, las compilaciones de Anchor o los pipelines de lanzamiento verificables.
¿Cómo encaja solana-verify en el mapa mental?
Es la capa de atestación por encima de las compilaciones ordinarias: reconstruye en condiciones controladas, hashea el ELF y compara con los bytes del programa en cadena para la confianza en la cadena de suministro.
¿Por qué las compilaciones del portátil y de la CI discrepan?
Diferentes versiones de Agave/Anchor/Rust, sombras de PATH, banderas de características o dependencias no bloqueadas cambian el artefacto; fija cada capa y prefiere la CI hermética para el lanzamiento.
¿Es @solana/kit parte de la ruta de compilación en cadena?
No. Kit es una pila de clientes TypeScript para RPC y transacciones (este sitio: 7.0.0). La compilación del programa sigue siendo Rust más cargo build-sbf (y opcionalmente Anchor).
¿Qué debería instalar primero un nuevo ingeniero?
Rust a través de rustup con la fijación de toolchain del repositorio, luego Agave/Solana CLI a través de agave-install, luego avm/Anchor si el repositorio usa Anchor, luego abre el editor con rust-analyzer antes de generar extras de scaffolding.
¿Cuándo vale la pena el camino completo de CI con compilación verificable?
Cuando las actualizaciones de mainnet, las auditorías o la gobernanza requieren pruebas de que el bytecode desplegado coincide con un commit público específico, no solo que una máquina de desarrollador produjo una vez un .so.
¿Cómo sé que mi pila coincide con las fijaciones de este sitio?
Ejecuta rustc --version, solana --version, anchor --version, y confirma kit en los manifiestos de paquetes contra Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, Rust 1.91.1 y @solana/kit 7.0.0.
Relacionados
- Visión General de la Cadena de Herramientas - tarjeta de receta y mapa de pila para herramientas fijadas
- Gestión de Versiones (agave-install / avm) - fijación de versiones de Agave/CLI y Anchor
- create-solana-dapp - scaffolding completo de programa + Next.js
- Compilación de Programas (cargo build-sbf) - pipeline de compilación sBPF y artefactos
- Compilaciones Verificables (solana-verify) - compilaciones reproducibles y comprobaciones de hash en cadena
- Configuración del Editor y rust-analyzer - bucle IDE para crates de programas
Versiones de la pila: Esta página fue escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, Rust 1.91.1 y @solana/kit 7.0.0.