Referencia

Compilar un sketch en el navegador

Cómo un sketch se convierte en firmware sin ningún servidor de compilación.

Los archivos de una placa los compila un clang real y un lld real, ejecutándose como WebAssembly dentro de la página. No hay servidor de compilación, no se sube nada, y el ELF que sale es del mismo tipo de imagen que produce firmware/build.sh: es el mismo compilador guiado por la misma lista de comandos.

La prueba de que esto funciona, con los números que justificaron construirlo, está en proofs/compile/REPORT.md. Este documento explica cómo lo hace el producto.

La forma general

web/src/compile/
  asm-check.ts   the AVR operand checks avr-as makes and LLVM's assembler does not
  asm-help.ts    plain-English help for an assembler or linker message
  bundles.ts     which toolchain and which runtime each board family needs
  cache.ts       the 74 MB download, and the Cache API entry that avoids it
  client.ts      the page's half: one worker, and the rule for "does this need building?"
  diagnostics.ts clang's stderr -> { file, line, col, severity, message }
  disasm.ts      AVR and Thumb disassembly for the debugger, in llvm-objdump's spelling
  hash.ts        a cheap content hash for the two cache keys
  protocol.ts    the messages between the page and the worker
  toolchain.ts   the command list, and one wasm instantiation per tool run
  wasi.ts        a WASI preview 1 host with an in-memory filesystem
  worker.ts      the Web Worker that runs all of the above
web/src/ui/build-panel.ts   the steps, the diagnostics and the one success line
web/scripts/bundle-runtime.mjs   firmware/ -> web/public/firmware/runtime/<family>.json

Todo excepto el panel Compilación corre en el worker, así que una primera compilación de cuatro segundos nunca bloquea un cuadro del lienzo.

Lo que tiene que llegar al navegador

Dos cosas, de dos lugares.

The toolchain is one clang.wasm (clang, ld.lld and llvm-objcopy in a single LLVM driver that dispatches on argv[0]) plus a bundle.json whose /usr/include/... entries are clang's own resource headers, pruned to the ten a freestanding build opens. Both come from the Cloudflare R2 bucket mokxi-toolchain, served by the Worker at /toolchain/<version>/<file>. In development deploy/fetch-toolchain.sh puts the same files under web/public/toolchain/<version>/ (gitignored) and Vite serves the same paths, so the client code is identical either way.

The runtime is our own firmware: the sources under firmware/src, the headers, crt0.S and the linker script, together with the exact flags firmware/build.sh compiles them with. It also carries firmware/lib, the shared header-only drivers (mokxi_i2c.h, mokxi_ssd1306.h, mokxi_max7219.h, and the rest): one copy, mounted at /firmware/lib for every family with -I/firmware/lib on the command line, exactly where firmware/build.sh and firmware/uno/build.sh already point their own -I at the same directory. A sketch that includes one of these headers (every OLED, SPI display, WS2812, tone or joystick example) compiles on any board because of this, not despite it. web/scripts/bundle-runtime.mjs packs all of it into web/public/firmware/runtime/<family>.json, which is committed. Regenerate it whenever the firmware (including firmware/lib) changes:

node web/scripts/bundle-runtime.mjs          # write the files
node web/scripts/bundle-runtime.mjs --check  # fail if they are out of date

src/compile/bundles.test.ts ejecuta la forma --check, de modo que un cambio en firmware/ que nadie haya trasladado hace fallar la suite de pruebas y no la compilación de un usuario.

Every family's firmware is in the tree now, so the script writes every bundle. It still holds the rule it was written with: a family whose firmware is not there (the script looks for its link.ld) is skipped with a note, not an error, so neither a developer's build nor CI fails while the next family is being written. esp32c3 and uno name their sources explicitly, in the order build.sh links them, and so does attiny, whose sources are the Uno's list on a different -mmcu. pico, stm32, bluepill and microbit use discover, which reads the lists off the directory: every .S at the family root with crt0 first, then src/*.c, then src/*.cpp with main.cpp last, everything else alphabetical, which is the order their build.sh links in, so nothing has had to be pinned. Pin explicit lists in the script if a link order ever has to be something else.

The ESP32, ESP32-S3 and ESP8266 bundles are written too. Their flags are the clang translation of their GCC build.sh lists (see "Proven natively" below), and they are what clang-v3 compiles in the browser.

La versión del toolchain se fija por familia de placas

La versión es una propiedad de la familia, no de la app, porque las dos compilaciones no son un solo compilador: clang-rv32-v1 se configuró solo con LLVM_TARGETS_TO_BUILD=RISCV, así que puede compilar para el ESP32-C3 y físicamente no puede compilar para el Uno. clang-v2 es ese mismo script de compilación con LLVM_TARGETS_TO_BUILD=RISCV;AVR;ARM (mismo diseño, mismo bucket, misma forma de URL), y toda familia que compila hoy está fijada a él (DECISIONS.md, 2026-09-14: verificado en los tres backends y subido a R2). Su salida de RISC-V es idéntica byte por byte a la de clang-rv32-v1, así que el ESP32-C3 también pasó a usarlo y todas esas placas comparten una sola descarga. Las familias Xtensa están fijadas a clang-v3 (XTENSA_TOOLCHAIN), publicado el 2026-09-28:

familia program del catálogo target toolchain listo
esp32c3 elf32 riscv32imc riscv32-unknown-elf -march=rv32imc -mabi=ilp32 clang-v2 sí
c6 elf32 riscv32imc esp32c6 riscv32-unknown-elf -march=rv32imc -mabi=ilp32 clang-v2 sí
uno elf32 avr atmega328p avr -mmcu=atmega328p clang-v2 sí
nano elf32 avr atmega328p nano avr -mmcu=atmega328p clang-v2 sí
mega2560 elf32 avr atmega2560 avr -mmcu=atmega2560 clang-v2 sí
leonardo elf32 avr atmega32u4 avr -mmcu=atmega32u4 clang-v2 sí
attiny elf32 avr attiny85 avr -mmcu=attiny85 clang-v2 sí
pico elf32 arm rp2040 thumbv6m-none-eabi -mcpu=cortex-m0plus -mthumb clang-v2 sí
xiao elf32 arm samd21 thumbv6m-none-eabi -mcpu=cortex-m0plus -mthumb clang-v2 sí
stm32 elf32 arm stm32f411 thumbv7em-none-eabi -mcpu=cortex-m4 -mthumb -mfloat-abi=soft -mfpu=none clang-v2 sí
bluepill elf32 arm stm32f103 thumbv7m-none-eabi -mcpu=cortex-m3 -mthumb -mfloat-abi=soft clang-v2 sí
microbit elf32 arm nrf52833 thumbv7em-none-eabi -mcpu=cortex-m4 -mthumb -mfloat-abi=soft -mfpu=none clang-v2 sí
unor4 elf32 arm ra4m1 thumbv7em-none-eabi -mcpu=cortex-m4 -mthumb -mfloat-abi=soft -mfpu=none clang-v2 sí
esp32 elf32 xtensa lx6 esp32 xtensa-esp-elf -mcpu=esp32 -fintegrated-as clang-v3 sí
esp32s3 elf32 xtensa lx7 esp32s3 xtensa-esp-elf -mcpu=esp32s3 -fintegrated-as clang-v3 sí
esp8266 elf32 xtensa lx106 esp8266 xtensa-esp-elf -mcpu=esp8266 -fintegrated-as clang-v3 sí

Las últimas tres filas son la siguiente sección. web/src/compile/bundles.ts es la lista de la que se lee esta tabla, y bundles.test.ts las mantiene sincronizadas.

Las placas Xtensa, con clang-v3

El ESP32 clásico es un Xtensa LX6, el ESP8266 NodeMCU un Xtensa LX106 y el ESP32-S3 un Xtensa LX7. Los tres compilan en el navegador con clang-v3 desde el 2026-09-28 ("Publicado y comprobado" más abajo). Hasta entonces corrían ELFs precompilados y así lo decían. El resto de esta sección explica por qué hizo falta un fork y qué encontró la prueba.

Por qué es un toolchain aparte (comprobado el 2026-09-27):

  1. clang-v2 no tiene backend Xtensa. Se compiló con LLVM_TARGETS_TO_BUILD=RISCV;AVR;ARM (DECISIONS.md, 2026-09-14). El wasm que descarga el navegador físicamente no puede emitir un objeto Xtensa.
  2. El LLVM upstream tiene la mitad de lo necesario, y la mitad equivocada. Clang lleva un frontend Xtensa desde LLVM 20 (Phoronix), y el de LLVM 22 XtensaProcessors.td sabe esp32 y esp8266 (upstream main añade esp32s2 y esp32s3). Pero el ld.lld de upstream no tiene ningún destino Xtensa: no existe lld/ELF/Arch/Xtensa.cpp en main ni en release/22.x, así que nada upstream puede enlazar una imagen de ESP32. El backend upstream también todavía emite pools de literales inline en .text, lo que rompe la l32r alineación bajo -ffunction-sections (llvm/llvm-project#190204, abierta). Xtensa sigue en LLVM_ALL_EXPERIMENTAL_TARGETS upstream.
  3. Espressif's fork has all of it. esp-clang (espressif/llvm-project, última esp-22.1.4_20260825, LLVM 22.1.4, Apache-2.0 with LLVM exception) carries the Xtensa front end with -mcpu=esp32, esp8266, esp32s2 and esp32s3, and an lld/ELF/Arch/Xtensa.cpp that handles R_XTENSA_32, R_XTENSA_SLOT0_OP (L32R, CALL8, branches) and the DIFF/ASM_EXPAND relocations. Xtensa is experimental there too, so it has to go in LLVM_EXPERIMENTAL_TARGETS_TO_BUILD; build-wasm-clang.sh now splits that out of the target list by itself. The fork does not carry the WASI portability commit, so proofs/compile/patches/llvm-wasi-portability.patch (the same commit clang-v2 is built with, from YoWASP) is applied on top. It applies cleanly to esp-22.1.4_20260825 (one hunk at an offset of one line). That commit's WASI close() returns a stale errno and fails clean writes ("IO failure on output stream: No such file or directory"), so build-wasm-clang.sh always applies proofs/compile/patches/llvm-wasi-close-errno.patch after it, on either tree. The clang-v2 served today predates that fix; ERRNO_RESET_HEADER and runtimeFiles in web/src/compile/toolchain.ts work around it until it is rebuilt (docs/clang-v2-rebuild.md has the plan).

Así que esto es un fork que conviene seguir en lugar de una bandera que agregar, pero el fork es el propio de Espressif, se publica cada pocos meses y tiene la misma licencia del LLVM del que proviene clang-v2.

Los ELF precompilados siguen construyéndose con el GCC de Espressif, que deploy/fetch-xtensa.sh coloca en tools/xtensa/: xtensa-esp32-elf-gcc 8.4.0 para el LX6, xtensa-esp32s3-elf-gcc 8.4.0 para el LX7 y xtensa-lx106-elf-gcc 8.4.0 para el LX106. El runtime del S3 reutiliza el crt0.S y el support64.c del ESP32 clásico: para el código que un compilador genera a partir de C, el LX7 es el LX6, y la salida del compilador del S3 para el mismo programa de prueba es byte por byte la del compilador del ESP32. Ese directorio está en el gitignore. GCC es GPL, y nada de lo que aquí compila se enlaza contra libgcc (los runtimes son -nostdlib con su propio support.c, y el support32.c del ESP8266 provee las divisiones de 32 bits para las que el LX106 no tiene instrucción), así que ningún código GPL llega a un ELF publicado.

Comprobado de forma nativa

Antes de que exista ningún wasm, el lado del compilador se comprueba con la compilación nativa para Linux del mismo fork (clang-esp-22.1.4_20260825-x86_64-linux-gnu.tar.xz, 411 MB, sha256 4700ed4e...eb0a1, se descomprime en 2.7 GB e incluye ld.lld):

proofs/compile/xtensa/run-native.sh /some/scratch/dir

Descarga esa versión y luego ejecuta proofs/compile/xtensa/plan.ts --native, que no transcribe ningún comando: toma runtimeSteps y projectPlan de web/src/compile/toolchain.ts y los paquetes de runtime versionados web/public/firmware/runtime/esp32.json, esp32s3.json y esp8266.json, así que lo que se ejecuta es la lista de comandos del navegador, crt0.S dividido en su mitad de preprocesado y su mitad de ensamblado, ld.lld llamado directamente y llvm-objcopy hacia stdout. Resultado del 2026-09-27:

  • every example of every board compiles and links with -Wall -Wextra -Werror: nine for the ESP32 (19 steps each), eleven for the ESP32-S3 (21 steps, rainbow and usbserial included) and nine for the ESP8266 (20 steps), about 1 s each natively;
  • ld.lld resuelve cada reubicación (en los objetos del ESP32: 3,407 R_XTENSA_32 y 430 R_XTENSA_SLOT0_OP);
  • MOKXI_ESP32_ELF_DIR=... cargo test -p esp32 --test runtime --test wifi: 11 + 4 passed; MOKXI_ESP32S3_ELF_DIR=... cargo test -p esp32s3 --test runtime --test wifi: 13 + 4 passed; MOKXI_ESP8266_ELF_DIR=... cargo test -p esp8266 --test runtime --test wifi: 11 + 4 passed. Son las mismas pruebas que los ELF de GCC pasan: el medio período de 500 ms de blink, LEDC y PWM por software a 1 kHz, millis() contra el reloj del kernel, el espaciado de bits del UART0, el ADC, las tramas WS2812 del S3 en su LED RGB (blanco y luego el verde del arcoíris primero en el cable) y sus paquetes USB serie, la conexión WiFi y la página web de la lámpara. Las tres variables de entorno solo apuntan las pruebas existentes a otro directorio; un archivo corrupto ahí las hace entrar en pánico, así que de verdad cargaron lo que se compiló.

Tres cosas que encontró la comprobación, todas resueltas en los paquetes:

  • Se requiere -fintegrated-as. Para Xtensa el controlador de Espressif entrega un archivo .s a un ensamblador GNU externo (xtensa-esp32-elf-clang-as) por defecto, que WASI no puede lanzar. Con -fintegrated-as el propio ensamblador de clang toma crt0.S tal como está escrito. Está en las banderas de destino de la familia, así que la mitad de ensamblado también lo recibe. Espressif lo desactiva a propósito para la entrada de ensamblador (EspBareMetal.cpp: "TODO: Add full support for Xtensa to integrated asm, LLVM-290, LLVM-291"), así que no está completo para todos los archivos escritos a mano; lo está para nuestros dos crt0.S archivos, que es lo que muestran las pruebas del simulador. También es la razón por la que los propios archivos .S y .s no se ofrecen en las placas Xtensa: solo .c, .cpp y .ino se compilan ahí, mientras que todas las demás familias también ensamblan los archivos propios del proyecto (ver Ensamblador más abajo). C y C++ siempre pasan por el ensamblador integrado, en este fork como en upstream.
  • Ningún aviso de multilib en el wasm. La instalación nativa advierte que no tiene multilib de esp8266 (un error con -Werror) porque su multilib.yaml no tiene esa entrada. BareMetal::findMultilibs solo lee un multilib.yaml que exista, y el sistema de archivos del wasm no tiene ninguno, así que solo la ejecución nativa necesita -Wno-missing-multilib, y solo plan.ts --native la pasa.
  • Las opciones -mlongcalls y -mtext-section-literals de GCC se quitan. Clang informa -mlongcalls como argumento sin usar, un error con -Werror. Sin -mtext-section-literals clang emite .literal.<function> secciones, que los tres link.ld archivos ya colocan al inicio de .text, well inside L32R's 256 KB reach.

Tamaño del código, el segmento ejecutable de cada ejemplo contra la imagen GCC publicada (mismas fuentes, ambos con -Os):

placa GCC, todos los ejemplos clang por cada ejemplo
ESP32 29,984 bytes 37,760 bytes +15% (fade) a +37% (wifilamp), +26% en total
ESP32-S3 41,584 bytes 53,920 bytes +18% (fade) a +38% (wifilamp), +30% en total
ESP8266 34,592 bytes 49,104 bytes +33% (button) a +49% (wifilamp), +42% en total

Los datos quedan dentro de unas pocas decenas de bytes en cualquier caso. La imagen más grande de clang es el wifilamp del ESP8266 con 8,944 bytes de código, frente a una IRAM de 32 KB y el límite de 24 KB al que su elfcheck.py sujeta los ejemplos, así que el crecimiento no cuesta nada que un sketch de aquí notaría. No se ha desglosado a dónde van los bytes.

Publicado y verificado

  1. Compilado por .github/workflows/clang-v3.yml, ejecución 36358476287 (intento 3, main en 4578344f): espressif/llvm-project en esp-22.1.4_20260825 con RISCV;AVR;ARM;Xtensa, ambos parches de WASI, luego plan.ts --wasm para las tres placas y las pruebas del simulador sobre lo que compiló el wasm. Artefacto clang-v3, sha256 del zip ef27b7aa…3eafd; clang.wasm pesa 80,735,841 bytes, sha256 7546c54c07c392e231ea450f8e3aaa6680346ffeb08e13d97d970b26d88666e5.
  2. Publicado el 2026-09-28: el artefacto se descomprimió en web/public/toolchain/clang-v3/ y luego deploy/fetch-toolchain.sh --publish clang-v3. https://mokxi.com/toolchain/clang-v3/ sirve clang.wasm, bundle.json y include.tgz con los tipos correctos, las longitudes correctas y el mismo sha256 que el artefacto. El bundle.json no está recortado (16 MB, todos los headers de recursos de clang); solo se usan sus entradas de /usr/include, y recortarlo como se hizo con el de clang-v2 ahorraría la mayor parte de esa descarga.
  3. Verificado en Chromium (headless, contra npm run dev con los archivos publicados en web/public/toolchain/clang-v3/): el editor real abrió un diagrama con su propio sketch, presionó Ejecutar y observó el panel de compilación, el monitor serie y el LED. El sketch del ESP32 se conectó al WiFi simulado (192.168.4.2) e hizo parpadear GPIO 4; el sketch del ESP32-S3 hizo parpadear GPIO 2 e imprimió; el sketch del ESP8266 hizo parpadear D1 e imprimió una división de 32 bits en cada ciclo; el ejemplo Blink del propio ESP8266, editado, compiló y también parpadeó. La primera compilación de una placa tardó de 5 a 7 s incluyendo el runtime, y una posterior unos 1.5 s. El ELF que la página compiló para el Blink del ESP8266 es byte por byte el proof/esp8266/blink.elf del flujo de trabajo.
  4. La verificación del ESP8266 descubrió un bug del motor, corregido en el mismo cambio. El Blink de clang escribe sus pines en el mismo slice en el que se estaciona, así que la red del pin se mueve dentro de un tiempo que el núcleo ya ejecutó, y el componente de la placa adelantó el núcleo estacionado antes del final de ese slice. CCOUNT retrocedió, el contador de ciclos de 64 bits del runtime lo leyó como un desborde de 2^32 ciclos, y cada delay() después del primero regresaba de inmediato: el LED se encendió y se quedó encendido. El Blink de GCC nunca escribe un pin en el slice en el que se estaciona, por eso ningún ejemplo distribuido lo mostró, y las pruebas nativas nunca lo mostraron porque ejecutan el SoC sin circuito. Los componentes de las placas ESP32, ESP32-S3 y ESP8266 ahora nunca ejecutan el núcleo antes de donde terminó su último slice (ran_to en crates/parts/src/parts/esp8266.rs y sus dos hermanos), y blink_keeps_its_half_period_when_a_pin_moves_as_the_core_parks lo cubre (ejecútala con MOKXI_ESP8266_ELF_DIR apuntando a los ELF de clang).
  5. El punto flotante es soft float. -mcpu=esp32 y -mcpu=esp32s3 activan la FPU de precisión simple, que el modelo no tiene, así que al principio una multiplicación o comparación de float, o el isnan(h) || isnan(t) del tutorial del DHT, compilaba a una instrucción de FPU y la placa se detenía. Los bundles ahora pasan -Xclang -target-feature -Xclang -fp (el driver de Xtensa no tiene -mfloat-abi), así que los floats se convierten en llamadas a mokxi_float.c como en cualquier otra placa de soft float y dan resultados correctos. El LX106 del ESP8266 no tiene FPU que apagar y enlaza el mismo mokxi_float.c.

Siguientes pasos

  1. Decidir si todas las familias pasan a clang-v3. Hasta que lo hagan, un usuario que compila para un ESP32 y cualquier otra placa conserva dos toolchains de más de 75 MB en la Cache API: isStaleKey (cache.ts) conserva todas las versiones que una familia nombra (TOOLCHAINS_IN_USE) y descarta la otra solo cuando el disco está lleno. Antes del 2026-10-17 descartaba todas las versiones menos la que estaba en uso, así que cada cambio volvía a descargar 20 MB y fallaba sin conexión. Moverlas todas es una cadena por familia, igual que la migración a clang-v2, pero es LLVM 22.1.4 de un fork y no 22.1.0, así que ejecuta primero crash.test.ts y las pruebas de bibliotecas de fábrica contra él, y no asumas una salida idéntica byte por byte.
  2. Revisa las bibliotecas de serie en las familias Xtensa. firmware/lib está en su ruta de includes como en todas las placas, pero stock-libraries.test.ts no las lista, así que Servo.h, Wire.h y las demás no se prueban ahí.
  3. Recortar bundle.json a los headers que abre una compilación freestanding.

Nunca prometer una compilación en el navegador que no funcione: un botón de compilación que ejecutara en silencio el binario de ayer sería lo peor de este producto.

clang-rv32-v1 sigue siendo el valor de RV32_TOOLCHAIN y ninguna familia lo nombra. Se queda como el camino de regreso: cambiar la cadena toolchain de una familia es todo lo que implica lanzar o revertir una compilación, ya que las URLs, la clave de caché de módulos y la caché de objetos del runtime dependen de ella.

ready tampoco es código muerto. Dos cosas deben cumplirse antes de que una familia pueda llevarlo, y bundles.test.ts verifica la segunda de ellas:

  1. Que la cadena de herramientas tenga el back end, que esté publicada y que un sketch que compiló haya corrido en el simulador.
  2. Que la familia tenga un paquete de runtime, lo cual significa que su directorio de firmware existe y que bundle-runtime.mjs se ha ejecutado.

Que una familia no esté ready no es un error: chooseProgram envía sus placas al ELF precompilado de web/public/firmware/, el panel de compilación y la línea junto al selector de placa explican el porqué, y nada falla. Hoy ninguna familia sigue ese camino; las familias Xtensa lo hicieron hasta que se publicó clang-v3.

La STM32 y la micro:bit son soft float a propósito: DECISIONS.md, 2026-09-14, deja la FPU y el DSP del M4 fuera del alcance hasta que se necesite una placa M4F, así que ningún runtime puede emitir instrucciones VFP ni un ABI de hard float.

Qué pasa cuando presionas Ejecutar

App.buildPrograms le pregunta a chooseProgram (src/compile/client.ts) por cada placa, y recibe una de tres respuestas:

  • elf: ejecutar la imagen que nombra el panel de Firmware y no compilar nada. Un ELF cargado no se compiló a partir de estos archivos; un ejemplo integrado sin modificar ya está compilado. Una familia cuya cadena de herramientas no está publicada también cae aquí.
  • reuse: ejecutar el ELF ya compilado exactamente a partir de estos archivos. La decisión se basa en un hash de cada nombre de archivo y de cada byte que contiene, así que una pulsación de tecla y un deshacer te devuelven a reuse.
  • build: compilar y ejecutar el resultado.

Una compilación que falla detiene la ejecución: el botón se queda en Ejecutar, el ELF anterior se descarta en lugar de usarse en silencio y los diagnósticos permanecen en el panel. El ELF compilado vive en memoria solo durante la sesión. Es un hecho de esta sesión, no parte del documento, así que nunca se guarda, se exporta ni se comparte.

La lista de comandos

Los mismos catorce comandos que ejecuta firmware/build.sh, con dos diferencias que WASI impone (ambas resueltas en la prueba de concepto):

  1. -c crt0.S hace que clang quiera dos trabajos, un preprocesado y un ensamblado, y clang desactiva su cc1 integrado en cuanto hay más de uno, lo cual en WASI da "unable to execute command: WASI does not support spawning subprocesses". Las dos mitades se listan por separado.
  2. El enlace pasa por ld.lld directamente y no por el driver de clang, así que las banderas de enlace del ESP32-C3 pierden sus prefijos -Wl,. firmware/uno/build.sh ya llama a ld.lld por la misma razón.

El sistema de archivos que ven las herramientas:

ruta qué es
/usr/include los headers de recursos de clang, del paquete del toolchain
/firmware para el ESP32-C3, /firmware/<family> para el resto nuestras fuentes del runtime, headers, crt0.S, link.ld
/firmware/lib los drivers compartidos de solo header, la misma ruta para cada familia
/project los archivos de la placa, con sus propios nombres, para que #include "pins.h" funcione
/build objetos, el sketch envuelto, el ELF

Ensamblador

Los archivos .S y .s propios de un proyecto también se compilan aquí, ya que arduino-cli compila un .S junto a un sketch, y una placa puede ser solo ensamblador y nada más.

Cuatro piezas, todas en web/src/compile/:

  1. El plan. projectPlan (toolchain.ts) agrega un par de pasos por cada .S: un preprocesado con la ruta de includes, la ruta entre comillas y las definiciones del propio sketch (así #include <avr/io.h> da los nombres de los registros y __ASSEMBLER__ queda definido), y luego un ensamblado de la copia preprocesada. Son dos ejecuciones por la razón que runtimeSteps ya da: -c foo.S hace que clang quiera dos trabajos, y clang desactiva su cc1 integrado en cuanto hay más de uno, lo que en WASI da "unable to execute command: WASI does not support spawning subprocesses". Un .s se ensambla directamente, sin paso de preprocesado. Los marcadores # <line> "<file>" del preprocesador se conservan, así que un diagnóstico y una línea de DWARF corresponden a la línea de la propia pestaña y no a la línea de la copia preprocesada, que es lo que permite al depurador poner un punto de interrupción en una línea .S. El paso de ensamblado pasa solo las banderas que el ensamblador mismo lee, más -g -gdwarf-4.
  2. Las verificaciones de operandos. asm-check.ts lee cada archivo .S y .s en ensamblador AVR del proyecto antes de que se ejecute cualquier herramienta, y reporta con el formato propio de clang file:line:col: error:, de modo que parseDiagnostics y el panel Compilación no necesitan saber nada nuevo. Hace las verificaciones que hace avr-as y que el ensamblador AVR de LLVM no hace de forma silenciosa: ldi r16, 300 (se conserva como 0x2C), sbi PORTB, 1 (una dirección de datos donde va una dirección de E/S), add r16, 5 (se lee como add r16, r5), out PORTB, r16 sin __SFR_OFFSET 0 (una advertencia: llega a un registro distinto), in y out más allá de 63, sbiw y adiw más allá de 63, y un bit más allá de 7. Un operando se evalúa solo cuando se puede resolver: números, los .equ, .set y #define del propio archivo, y los nombres de registros y bits del header de la placa leídos del paquete en tiempo de ejecución, a través de _SFR_IO_ADDR(), lo8(), hi8() y los operadores de C. Todo lo demás se deja al ensamblador y al enlazador, que aciertan en esos casos. Un error detiene la compilación antes de que se inicie una herramienta (plan.checkFailed).
  3. El enlace, cuando no hay sketch. isAssemblyProject (bundles.ts) es un proyecto cuyos archivos son solo de ensamblador; assemblyLinkInputs dice qué enlaza además de sus propios objetos. En una placa AVR eso es el objeto crt0.S del runtime y nada más, que es lo que gcrt1.o de avr-libc es para avr-gcc main.S: la tabla de vectores con cada __vector_<n> como reti débil, r1 en cero, la pila en RAMEND, .data copiado, .bss en cero, y una llamada al main del proyecto. Un proyecto cuyo archivo define su propia sección .vectors o etiqueta __vectors (definesVectors) no recibe nada, y tampoco lo recibe ninguna placa ARM, donde el archivo es la tabla de vectores. Sin núcleo de Arduino en ningún caso: sin setup(), sin el tic de millis(), sin Serial.
  4. El desensamblador. disasm.ts es nuestro, porque el LLVM del navegador trae clang, ld.lld y llvm-objcopy y no llvm-objdump. Lee los segmentos ejecutables del ELF que la app ya conserva, así que la lista de Desensamblado de la pestaña Depurar y su botón Step no requieren ida y vuelta. El decodificador AVR cubre todo el conjunto de instrucciones; el decodificador Thumb cubre todas las codificaciones de 16 bits, BL, y las formas Thumb-2 de 32 bits que un compilador o un curso escriben la mayoría de las veces, y muestra cualquier otra cosa como .inst.w 0x… en lugar de una suposición equivocada. El texto es el de llvm-objdump, y disasm.test.ts lo mantiene así: cada instrucción de compilaciones reales (los cuatro proyectos iniciales de ensamblador, y un sketch con matemáticas de punto flotante, Serial y pines) para el Uno, el Mega, el Pico y la Black Pill tiene que leerse exactamente como lo lee el llvm-objdump de la máquina.

Qué placas ofrecen un proyecto de ensamblador sin núcleo está en src/asm/boards.ts: el Uno, el Nano, el Pro Mini, el Pico y el STM32F411. Cualquier otra placa que compila sigue aceptando pestañas .S junto a un sketch, excepto las placas Xtensa (ver arriba). asm.test.ts compila y ejecuta todo eso en el simulador.

Una herramienta que cae en una trampa

clang y lld ambos recorren una ruta de abort en algunos errores fatales (un #include faltante, sobre todo) que imprime el diagnóstico en stderr y luego llega a unreachable en lugar de llamar a exit. Dentro de WASI eso aparece como un WebAssembly.RuntimeError real, no como un proc_exit, y de otro modo escaparía como un rechazo no capturado sin ningún diagnóstico adjunto: un fallo, no un error de compilación.

Toolchain.run (src/compile/toolchain.ts) captura exactamente eso: una trampa que ocurre después de que la herramienta ya escribió algo en stderr regresa como un paso fallido normal, con result.trapped activado y result.code distinto de cero, y todo lo escrito antes de la trampa sigue en result.err. runSteps (src/compile/worker.ts) entonces lo trata como cualquier otra salida distinta de cero: lo que parseDiagnostics encuentre es lo que muestra el panel de compilación, con clic como cualquier otro diagnóstico, y solo recurre a "el compilador falló (<tool> en <step>)" cuando la trampa no dejó nada que decir. Cada ejecución de una herramienta ya recibe su propia WebAssembly.Instance nueva a partir del único Module compilado (toolchainFor compila el módulo una sola vez; Toolchain.run lo instancia en cada llamada), así que una trampa en una ejecución no deja nada para la siguiente. No hay instancia que envenenar y nada aquí vuelve a instanciar el módulo por sí mismo.

Las pestañas .ino se unen y se envuelven como lo hace el Arduino IDE (src/compile/prototypes.ts): #include "arduino.h", luego la pestaña principal y las demás pestañas .ino en orden alfabético, cada una detrás de #line 1 "<tab>.ino", con un prototipo para cada función que definen las pestañas, escrito justo antes de la primera función, cada uno detrás de un #line que apunta a su definición, y un #line después del bloque. Así, un sketch que llama a una función definida más abajo de loop() compila, y el compilador sigue reportando un problema en sketch.ino:12:3 para que el panel de compilación pueda llevar el editor allí. Las plantillas, los miembros de clase, cualquier cosa dentro de un namespace, una función que el sketch declara por sí mismo y una función cuya firma nombra algo declarado más abajo no reciben prototipo; una función dentro de bloques #if recibe su prototipo dentro de una copia de las mismas condiciones; los argumentos predeterminados se mueven al prototipo y se borran, columna por columna, de la definición. Los .c se compilan como C11, los .cpp/.cc/.ino como C++17; cualquier otra cosa se escribe en /project para los includes y no se compila.

Los archivos del usuario se compilan con las banderas de advertencia del runtime menos -Werror (userWarnings en bundles.ts): las advertencias de -Wall -Wextra se reportan en el panel de compilación, y un objeto en caché conserva sus advertencias para que se muestren de nuevo en la siguiente ejecución, pero una advertencia no detiene la compilación, como en el Arduino IDE. El runtime en sí, y projectPlan(..., { strict: true }) (la prueba de Xtensa, las pruebas de bibliotecas estándar y de módulos de comunicación), mantienen -Werror, que es lo que mantiene el código y los ejemplos propios de Mokxi sin advertencias.

Qué se guarda en caché, y dónde

qué es dónde clave se pierde cuando
bytes de clang.wasm Cache API, mokxi-toolchain-v1 /toolchain/<version>/clang.wasm ninguna familia usa ya la versión, el disco está lleno, el almacenamiento se borra
los archivos objeto del runtime Cache API, el mismo almacén /toolchain/<version>/runtime/<family>-<bundle hash>.objects cambia la versión, cambia el firmware, se borra el almacenamiento
el WebAssembly.Module compilado el worker, en memoria versión del toolchain se cierra la página
los archivos objeto del runtime el worker, en memoria versión del toolchain + familia se cierra la página
el archivo objeto de cada código fuente del proyecto el worker, en memoria texto fuente + el comando exacto se cierra la página
el ELF compilado la aplicación, en memoria id de placa + firma del archivo se cierra la página

Los objetos del runtime son una docena de archivos de unos pocos kilobytes cada uno, empaquetados en una sola entrada de caché en lugar de una docena (MOKO, una longitud de encabezado, un índice JSON de pares [path, length], y luego los bytes uno tras otro), así que un acierto es un match y un arrayBuffer en lugar de doce de cada uno. La clave lleva un hash del paquete del runtime exactamente como se descargó, cada fuente y header y bandera que contiene, de modo que editar firmware/src/gpio.c y regenerar produce una clave distinta en lugar de un archivo objeto desactualizado. Todo lo que no se puede desempaquetar se borra y se recompila, porque un blob que no podemos leer es peor que ningún blob.

Lo que ya no es alcanzable se elimina al paso: cada entrada de un toolchain más antiguo, y un runtime de una familia cuyas fuentes ya cambiaron. A una familia de la que esta página no dice nada se le deja en paz: un usuario con un runtime de Uno en caché que hoy se dedica a un ESP32-C3 lo conserva.

Cada parte de esto se degrada: sin Cache API, una caché que lanza errores, un put que choca con una cuota: cada caso significa "volver a hacer el trabajo", nunca "sin compilador".

Medido

En Chromium 141 en el contenedor de compilación, contra npm run dev en loopback (que sirve clang.wasm sin comprimir, así que la descarga es el caso pesimista; producción lo sirve desde R2 con Content-Encoding: br):

del clic a la ejecución qué hizo
primera compilación, en frío 6.1 a 7.8 s descarga de 74 MB, WebAssembly.compile, 12 objetos del runtime, sketch, enlazado, strip
segunda visita y siguientes 1.5 a 1.8 s ninguna petición de clang.wasm; el runtime sale de la Cache API en 3 a 9 ms
editar y Ejecutar de nuevo, misma sesión 0.21 s sketch.ino 51 ms, link 10 ms, strip 5 ms
Ejecutar sin editar sin compilación alguna
el ELF 1.5 KB parpadea GPIO 8 a la velocidad que pide el sketch, en el motor real a 1.00x

Cuatro visitas en un mismo perfil de navegador hicieron una sola petición de clang.wasm, y la segunda y todas las posteriores se saltaron el runtime por completo:

visit 1: 7758 ms  Building… -> compiling the esp32c3 runtime… -> compiling your files…
         crt0.S 124+54 ms | gpio.c 826 | time.c 454 | uart.c 195 | interrupt.c 148
         | support.c 429 | format.c 483 | math.c 80 | print.cpp 498 | main.cpp 58
         | sketch.ino 65 | link 39 | strip 11
visit 2: 1754 ms  loading the compiler… -> compiling your files…
         esp32c3 runtime (cached) 9 ms | sketch.ino 676 | link 35 | strip 11
visit 3: 1464 ms  esp32c3 runtime (cached) 3 ms | sketch.ino 550 | link 43 | strip 11
visit 4: 1540 ms  esp32c3 runtime (cached) 6 ms | sketch.ino 514 | link 38 | strip 14

Lo que queda de una visita de regreso son dos cosas, ninguna de ellas el runtime: unos 0.7 s para leer de vuelta 74 MB de la Cache API y hacer compileStreaming, y unos 0.5 s para la primera ejecución de la herramienta en un módulo recién compilado, que es el motor calentando; la segunda edición en la misma sesión son los 51 ms de arriba.

El panel de compilación muestra el porcentaje de descarga, cada paso con su tiempo, y una línea al final: Built esp1.elf, 1.5 KB, 0.21 s.

Lo que el Worker debe servir

/toolchain/<version>/<file> debe venir del bucket de R2 mokxi-toolchain (objetos <version>/<file>), con un Cache-Control largo (la ruta tiene versión, así que los objetos son inmutables) y Content-Encoding: br para el wasm. La respuesta necesita Content-Type: application/wasm y un Content-Length: la barra de progreso del panel lee la longitud, y WebAssembly.compileStreaming rechaza cualquier cosa que no sea application/wasm.

CMSIS y HAL de ST en las placas STM32

La Nucleo-F411RE, la Black Pill y la Blue Pill también compilan código escrito para los headers propios de ST: código de registros que incluye stm32f4xx.h (o stm32f1xx.h, o el antiguo stm32f10x.h) y proyectos de STM32CubeIDE sobre la HAL de STM32Cube. Los archivos de ST se incluyen directamente en firmware/stm32cube/ (consulta su README para ver los commits y licencias de origen) y se empaquetan con web/scripts/bundle-stm32cube.mjs en web/public/firmware/stm32cube/f4.json y f1.json, unos 0.47 y 0.40 MB con Brotli. No están en los paquetes del runtime ni en la primera carga del editor: el worker descarga uno solo cuando un proyecto incluye uno de los headers de ST, o un main.h que no tiene (wantsCube en src/compile/stm32cube.ts), y lo conserva durante la sesión.

cubePlan decide el resto, y projectPlan lo sigue:

  • el paquete se monta en /stm32cube, sus directorios de include van en la ruta, con -DSTM32F411xE o -DSTM32F103xB, -DUSE_HAL_DRIVER cuando se usa la HAL, -DUSE_FULL_LL_DRIVER cuando se usa LL, y -DMOKXI_ST_CMSIS, que hace que el header de placa propio del runtime ceda ante el de ST en un sketch;
  • los módulos HAL que el stm32f?xx_hal_conf.h del proyecto habilita, los archivos LL que incluye y el archivo del sistema se compilan con -w y se enlazan como miembros de biblioteca, así que una primera compilación del HAL compila alrededor de una docena de archivos de ST (de 9 a 15 segundos con el wasm de clang-v2 en las pruebas) y la siguiente reutiliza sus objetos;
  • un proyecto con su propio main() se enlaza en modo bare (bareMetalLinkInputs): el código de arranque y la tabla de vectores del runtime tal cual, cualquier otro objeto del runtime como miembro de biblioteca, y mokxi_cube_bare.c dirigiendo printf() hacia el _write() o __io_putchar() del proyecto. Un sketch conserva el núcleo de Arduino, y mokxi_cube_sketch.c hace que el tick del HAL sea millis();
  • lo que le falte a un proyecto pegado se escribe con los valores predeterminados de CubeIDE para la placa (main.h, la configuración del HAL, el manejador de SysTick, un archivo MSP); el archivo de arranque de ST y los syscalls.c y sysmem.c de CubeIDE se omiten, y cada uno de esos es una nota en el registro de compilación (ProjectPlan.notes);
  • un proyecto que llama a un periférico que el chip simulado no tiene (SPI, I2C, DMA, el RTC y otros) recibe una nota que lo indica; la compilación aún tiene éxito.

Los chips simulados no tienen interfaz de flash, controlador de energía ni región de bit-band, y el HAL escribe los tres en HAL_Init() y en cada SystemClock_Config() de CubeIDE. El creador de paquetes agrega un include al header del dispositivo de ST (mokxi_cube_regs.h: FLASH y PWR se convierten en RAM con la misma disposición) y otro a stm32f?xx_hal.h (mokxi_cube_hal.h: las escrituras de bit-band de las macros del RCC se convierten en escrituras de registros ordinarias); los archivos del proveedor quedan sin cambios. src/compile/stm32cube.test.ts compila y ejecuta cada ejemplo en firmware/stm32cube/examples/, y /learn/stm32-hal-register-code es la página para los usuarios.

Límites

  • C, C++ y ensamblador (.S y .s, ver arriba). No hay MicroPython ni ningún otro lenguaje: el MicroPython de la Pico y el main.py de una Raspberry Pi ejecutan una imagen de firmware en lugar de pasar por este camino.
  • Un proyecto es plano: los nombres de archivo no llevan directorios, así que la ruta de includes tiene un solo directorio de profundidad.
  • Una placa cuyo string program del catálogo no nombre ninguna familia no tiene familia en absoluto, así que familyFor no encuentra nada y ejecuta su ELF precompilado. Una placa cuya familia no está ready hace lo mismo, con la note de la familia mostrada en el panel.
  • Una visita de retorno todavía paga unos 0.7 s para recuperar 74 MB de la Cache API y compilarlos. compileStreaming a partir de una Response en caché es lo que permite al motor reutilizar su propia caché de código, pero nada aquí puede convertir eso en una certeza.
  • En desarrollo el toolchain lo sirve Vite desde web/public/toolchain/; en producción lo sirve el Worker desde R2. worker/assets.ts responde 404 para /toolchain/ a propósito, así que el middleware de desarrollo en web/vite.config.ts debe dejar ese prefijo en paz. Y lo hace; romper eso es la forma en que el compilador termina descargando la página del 404.

Preguntas

¿Dónde ocurre la compilación?

En tu computadora, en la pestaña. No hay servidor de compilación, ni cola, ni minutos de compilación.

¿Qué tan grande es el toolchain?

Unos setenta megabytes. Se descarga en streaming una vez y el navegador lo guarda en caché, así que después de la primera compilación todo es local.