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):
clang-v2no tiene backend Xtensa. Se compiló conLLVM_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.- 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.tdsabeesp32yesp8266(upstreammainañadeesp32s2yesp32s3). Pero elld.lldde upstream no tiene ningún destino Xtensa: no existelld/ELF/Arch/Xtensa.cppenmainni enrelease/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 lal32ralineación bajo-ffunction-sections(llvm/llvm-project#190204, abierta). Xtensa sigue enLLVM_ALL_EXPERIMENTAL_TARGETSupstream. - Espressif's fork has all of it.
esp-clang(espressif/llvm-project, últimaesp-22.1.4_20260825, LLVM 22.1.4, Apache-2.0 with LLVM exception) carries the Xtensa front end with-mcpu=esp32,esp8266,esp32s2andesp32s3, and anlld/ELF/Arch/Xtensa.cppthat handlesR_XTENSA_32,R_XTENSA_SLOT0_OP(L32R,CALL8, branches) and theDIFF/ASM_EXPANDrelocations. Xtensa is experimental there too, so it has to go inLLVM_EXPERIMENTAL_TARGETS_TO_BUILD;build-wasm-clang.shnow splits that out of the target list by itself. The fork does not carry the WASI portability commit, soproofs/compile/patches/llvm-wasi-portability.patch(the same commit clang-v2 is built with, from YoWASP) is applied on top. It applies cleanly toesp-22.1.4_20260825(one hunk at an offset of one line). That commit's WASIclose()returns a staleerrnoand fails clean writes ("IO failure on output stream: No such file or directory"), sobuild-wasm-clang.shalways appliesproofs/compile/patches/llvm-wasi-close-errno.patchafter it, on either tree. The clang-v2 served today predates that fix;ERRNO_RESET_HEADERandruntimeFilesinweb/src/compile/toolchain.tswork around it until it is rebuilt (docs/clang-v2-rebuild.mdhas 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,rainbowandusbserialincluded) and nine for the ESP8266 (20 steps), about 1 s each natively; ld.lldresuelve cada reubicación (en los objetos del ESP32: 3,407R_XTENSA_32y 430R_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.sa un ensamblador GNU externo (xtensa-esp32-elf-clang-as) por defecto, que WASI no puede lanzar. Con-fintegrated-asel 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 doscrt0.Sarchivos, que es lo que muestran las pruebas del simulador. También es la razón por la que los propios archivos.Sy.sno se ofrecen en las placas Xtensa: solo.c,.cppy.inose 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 sumultilib.yamlno tiene esa entrada.BareMetal::findMultilibssolo lee unmultilib.yamlque exista, y el sistema de archivos del wasm no tiene ninguno, así que solo la ejecución nativa necesita-Wno-missing-multilib, y soloplan.ts --nativela pasa. - Las opciones
-mlongcallsy-mtext-section-literalsde GCC se quitan. Clang informa-mlongcallscomo argumento sin usar, un error con-Werror. Sin-mtext-section-literalsclang emite.literal.<function>secciones, que los treslink.ldarchivos ya colocan al inicio de.text, well insideL32R'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
- Compilado por
.github/workflows/clang-v3.yml, ejecución 36358476287 (intento 3,mainen4578344f):espressif/llvm-projectenesp-22.1.4_20260825conRISCV;AVR;ARM;Xtensa, ambos parches de WASI, luegoplan.ts --wasmpara las tres placas y las pruebas del simulador sobre lo que compiló el wasm. Artefactoclang-v3, sha256 del zipef27b7aa…3eafd;clang.wasmpesa 80,735,841 bytes, sha2567546c54c07c392e231ea450f8e3aaa6680346ffeb08e13d97d970b26d88666e5. - Publicado el 2026-09-28: el artefacto se descomprimió en
web/public/toolchain/clang-v3/y luegodeploy/fetch-toolchain.sh --publish clang-v3.https://mokxi.com/toolchain/clang-v3/sirveclang.wasm,bundle.jsonyinclude.tgzcon los tipos correctos, las longitudes correctas y el mismo sha256 que el artefacto. Elbundle.jsonno 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. - Verificado en Chromium (headless, contra
npm run devcon los archivos publicados enweb/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 elproof/esp8266/blink.elfdel flujo de trabajo. - 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.
CCOUNTretrocedió, el contador de ciclos de 64 bits del runtime lo leyó como un desborde de 2^32 ciclos, y cadadelay()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_toencrates/parts/src/parts/esp8266.rsy sus dos hermanos), yblink_keeps_its_half_period_when_a_pin_moves_as_the_core_parkslo cubre (ejecútala conMOKXI_ESP8266_ELF_DIRapuntando a los ELF de clang). - El punto flotante es soft float.
-mcpu=esp32y-mcpu=esp32s3activan la FPU de precisión simple, que el modelo no tiene, así que al principio una multiplicación o comparación defloat, o elisnan(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 amokxi_float.ccomo en cualquier otra placa de soft float y dan resultados correctos. El LX106 del ESP8266 no tiene FPU que apagar y enlaza el mismomokxi_float.c.
Siguientes pasos
- 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 primerocrash.test.tsy las pruebas de bibliotecas de fábrica contra él, y no asumas una salida idéntica byte por byte. - Revisa las bibliotecas de serie en las familias Xtensa.
firmware/libestá en su ruta de includes como en todas las placas, perostock-libraries.test.tsno las lista, así queServo.h,Wire.hy las demás no se prueban ahí. - Recortar
bundle.jsona 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:
- Que la cadena de herramientas tenga el back end, que esté publicada y que un sketch que compiló haya corrido en el simulador.
- Que la familia tenga un paquete de runtime, lo cual significa que su directorio de firmware existe y que
bundle-runtime.mjsse 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 areuse.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):
-c crt0.Shace 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.- El enlace pasa por
ld.llddirectamente y no por el driver de clang, así que las banderas de enlace del ESP32-C3 pierden sus prefijos-Wl,.firmware/uno/build.shya llama ald.lldpor 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/:
- 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 queruntimeStepsya da:-c foo.Shace 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.sse 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. - Las verificaciones de operandos.
asm-check.tslee cada archivo.Sy.sen ensamblador AVR del proyecto antes de que se ejecute cualquier herramienta, y reporta con el formato propio de clangfile:line:col: error:, de modo queparseDiagnosticsy el panel Compilación no necesitan saber nada nuevo. Hace las verificaciones que haceavr-asy 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 comoadd r16, r5),out PORTB, r16sin__SFR_OFFSET 0(una advertencia: llega a un registro distinto),inyoutmás allá de 63,sbiwyadiwmá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,.sety#definedel 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). - El enlace, cuando no hay sketch.
isAssemblyProject(bundles.ts) es un proyecto cuyos archivos son solo de ensamblador;assemblyLinkInputsdice qué enlaza además de sus propios objetos. En una placa AVR eso es el objetocrt0.Sdel runtime y nada más, que es lo quegcrt1.ode avr-libc es paraavr-gcc main.S: la tabla de vectores con cada__vector_<n>comoretidébil,r1en cero, la pila en RAMEND,.datacopiado,.bssen cero, y una llamada almaindel proyecto. Un proyecto cuyo archivo define su propia sección.vectorso 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: sinsetup(), sin el tic demillis(), sinSerial. - El desensamblador.
disasm.tses nuestro, porque el LLVM del navegador trae clang,ld.lldyllvm-objcopyy nollvm-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 dellvm-objdump, ydisasm.test.tslo mantiene así: cada instrucción de compilaciones reales (los cuatro proyectos iniciales de ensamblador, y un sketch con matemáticas de punto flotante,Serialy pines) para el Uno, el Mega, el Pico y la Black Pill tiene que leerse exactamente como lo lee elllvm-objdumpde 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-DSTM32F411xEo-DSTM32F103xB,-DUSE_HAL_DRIVERcuando se usa la HAL,-DUSE_FULL_LL_DRIVERcuando 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.hdel proyecto habilita, los archivos LL que incluye y el archivo del sistema se compilan con-wy 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, ymokxi_cube_bare.cdirigiendoprintf()hacia el_write()o__io_putchar()del proyecto. Un sketch conserva el núcleo de Arduino, ymokxi_cube_sketch.chace que el tick del HAL seamillis(); - 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 lossyscalls.cysysmem.cde 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 (
.Sy.s, ver arriba). No hay MicroPython ni ningún otro lenguaje: el MicroPython de la Pico y elmain.pyde 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
programdel catálogo no nombre ninguna familia no tiene familia en absoluto, así quefamilyForno encuentra nada y ejecuta su ELF precompilado. Una placa cuya familia no estáreadyhace lo mismo, con lanotede 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.
compileStreaminga partir de unaResponseen 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.tsresponde 404 para/toolchain/a propósito, así que el middleware de desarrollo enweb/vite.config.tsdebe dejar ese prefijo en paz. Y lo hace; romper eso es la forma en que el compilador termina descargando la página del 404.