Referência

Compilando um sketch no navegador

Como um sketch vira firmware sem servidor de compilação em lugar nenhum.

Os arquivos de uma placa são compilados por um clang de verdade e um lld de verdade, rodando como WebAssembly dentro da página. Não há servidor de compilação, nada é enviado, e o ELF que sai é o mesmo tipo de imagem que firmware/build.sh produz: é o mesmo compilador dirigido pela mesma lista de comandos.

A prova de que isso funciona, com os números que justificaram construí-lo, está em proofs/compile/REPORT.md. Este documento explica como o produto faz isso.

A forma geral

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

Tudo, exceto o painel Compilação, roda no worker, então uma primeira compilação de quatro segundos nunca trava um quadro do canvas.

O que precisa chegar ao navegador

Duas coisas, de dois 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 roda a forma --check, então uma mudança em firmware/ que ninguém propagou derruba a suíte de testes, e não o build de um usuário.

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.

A versão da toolchain é fixada por família de placa

A versão é uma propriedade da família, não do app, porque as duas compilações não são um compilador só: o clang-rv32-v1 foi configurado apenas com LLVM_TARGETS_TO_BUILD=RISCV, então ele consegue compilar para o ESP32-C3 e fisicamente não consegue compilar para o Uno. O clang-v2 é esse mesmo script de compilação com LLVM_TARGETS_TO_BUILD=RISCV;AVR;ARM (mesma estrutura, mesmo bucket, mesmo formato de URL), e toda família que compila hoje está fixada nele (DECISIONS.md, 2026-09-14: verificado nos três backends e enviado ao R2). A saída RISC-V dele é byte idêntica à do clang-rv32-v1, então o ESP32-C3 também passou a usá-lo e todas as placas desse tipo compartilham um único download. As famílias Xtensa estão fixadas no clang-v3 (XTENSA_TOOLCHAIN), publicado em 28/09/2026:

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

As três últimas linhas são a próxima seção. web/src/compile/bundles.ts é a lista da qual esta tabela é lida, e bundles.test.ts mantém as duas em sincronia.

As placas Xtensa, no clang-v3

O ESP32 clássico é um Xtensa LX6, o ESP8266 NodeMCU um Xtensa LX106 e o ESP32-S3 um Xtensa LX7. Os três compilam no navegador no clang-v3 desde 28/09/2026 ("Publicado e verificado" abaixo). Até então eles rodavam ELFs pré-compilados e diziam isso. O resto desta seção explica por que foi preciso um fork e o que a verificação encontrou.

Por que é uma toolchain separada (verificado em 27/09/2026):

  1. O clang-v2 não tem back end Xtensa. Ele foi construído com LLVM_TARGETS_TO_BUILD=RISCV;AVR;ARM (DECISIONS.md, 14/09/2026). O wasm que o navegador baixa fisicamente não consegue emitir um objeto Xtensa.
  2. O LLVM upstream tem metade do que é necessário, e a metade errada. O Clang carrega um front end Xtensa desde o LLVM 20 (Phoronix), e o do LLVM 22 XtensaProcessors.td sabe esp32 e esp8266 (upstream main adiciona esp32s2 e esp32s3). Mas o ld.lld upstream não tem nenhum alvo Xtensa: não existe lld/ELF/Arch/Xtensa.cpp no main ou em release/22.x, então nada upstream consegue linkar uma imagem de ESP32. O backend upstream também ainda emite pools de literais inline em .text, o que quebra l32r o alinhamento sob -ffunction-sections (llvm/llvm-project#190204, aberto). O Xtensa ainda está em LLVM_ALL_EXPERIMENTAL_TARGETS upstream.
  3. Espressif's fork has all of it. esp-clang (espressif/llvm-project, mais recente 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).

Então isto é um fork para acompanhar em vez de uma flag para adicionar, mas o fork é da própria Espressif, lançado a cada poucos meses, e sob a mesma licença do LLVM de onde vem o clang-v2.

Os ELFs pré-compilados ainda são compilados pelo GCC da Espressif, que o deploy/fetch-xtensa.sh coloca em tools/xtensa/: xtensa-esp32-elf-gcc 8.4.0 para o LX6, xtensa-esp32s3-elf-gcc 8.4.0 para o LX7 e xtensa-lx106-elf-gcc 8.4.0 para o LX106. O runtime do S3 reutiliza o crt0.S e o support64.c do ESP32 clássico: para o código que um compilador gera a partir de C, o LX7 é o LX6, e a saída do compilador do S3 para o mesmo programa de teste é byte a byte a do compilador do ESP32. Esse diretório está no gitignore. O GCC é GPL, e nada do que ele compila aqui faz link com libgcc (os runtimes são -nostdlib com seu próprio support.c, e o support32.c do ESP8266 fornece as divisões de 32 bits para as quais o LX106 não tem instrução), então nenhum código GPL chega a um ELF distribuído.

Comprovado nativamente

Antes de qualquer wasm existir, o lado do compilador é comprovado com a compilação nativa para Linux do mesmo fork (clang-esp-22.1.4_20260825-x86_64-linux-gnu.tar.xz, 411 MB, sha256 4700ed4e...eb0a1, descompacta para 2,7 GB com ld.lld dentro):

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

Ele busca esse release e roda proofs/compile/xtensa/plan.ts --native, que não transcreve nenhum comando: ele pega runtimeSteps e projectPlan de web/src/compile/toolchain.ts e os bundles de runtime versionados web/public/firmware/runtime/esp32.json, esp32s3.json e esp8266.json, então o que roda é a lista de comandos do navegador, com o crt0.S dividido nas etapas de pré-processamento e montagem, ld.lld chamado diretamente e llvm-objcopy com saída para stdout. Resultado em 27/09/2026:

  • 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 resolve toda realocação (nos objetos do ESP32: 3.407 R_XTENSA_32 e 430 R_XTENSA_SLOT0_OP);
  • MOKXI_ESP32_ELF_DIR=... cargo test -p esp32 --test runtime --test wifi: 11 + 4 passaram; MOKXI_ESP32S3_ELF_DIR=... cargo test -p esp32s3 --test runtime --test wifi: 13 + 4 passaram; MOKXI_ESP8266_ELF_DIR=... cargo test -p esp8266 --test runtime --test wifi: 11 + 4 passaram. São os mesmos testes que os ELFs do GCC passam: meio período de 500 ms do blink, LEDC e PWM por software a 1 kHz, millis() contra o relógio do kernel, espaçamento de bits da UART0, o ADC, os quadros WS2812 do S3 no seu LED RGB (branco, depois o verde do arco-íris primeiro no fio) e seus pacotes USB seriais, conexão WiFi e a página web da lâmpada. As três variáveis de ambiente apenas apontam os testes existentes para outro diretório; um arquivo corrompido ali os faz entrar em pânico, então eles realmente carregaram o que foi compilado.

Três coisas que a comprovação encontrou, todas tratadas nos bundles:

  • -fintegrated-as é obrigatório. Para Xtensa, o driver da Espressif entrega um .s de arquivo para um montador GNU externo (xtensa-esp32-elf-clang-as) por padrão, que o WASI não consegue executar. Com -fintegrated-as o próprio montador do clang pega o crt0.S como escrito. Está nas flags de alvo da família, então a metade de montagem também recebe. A Espressif o desativa de propósito para entrada em assembly (EspBareMetal.cpp: "TODO: Add full support for Xtensa to integrated asm, LLVM-290, LLVM-291"), então não está completo para todo arquivo escrito à mão; está para os nossos dois arquivos crt0.S , que é o que os testes do simulador mostram. É também por isso que os próprios arquivos .S e .s de um projeto não são oferecidos nas placas Xtensa: apenas .c, .cpp e .ino são compilados ali, enquanto toda outra família também monta os próprios arquivos do projeto (veja Assembly abaixo). C e C++ sempre passam pelo montador integrado, neste fork como no upstream.
  • Nenhum aviso de multilib no wasm. A instalação nativa avisa que não tem multilib esp8266 (um erro sob -Werror) porque seu multilib.yaml não tem essa entrada. BareMetal::findMultilibs só lê um multilib.yaml que existe, e o sistema de arquivos do wasm não tem nenhum, então só a execução nativa precisa de -Wno-missing-multilib, e só plan.ts --native a passa.
  • O -mlongcalls e o -mtext-section-literals do GCC vão embora. O Clang relata -mlongcalls como argumento não usado, um erro sob -Werror. Sem -mtext-section-literals o clang emite .literal.<function> seções, que os três arquivos link.ld já colocam no início de .text, well inside L32R's 256 KB reach.

Tamanho do código, o segmento executável de todo exemplo contra a imagem GCC enviada (mesmas fontes, ambos -Os):

placa GCC, todos os exemplos clang por exemplo
ESP32 29.984 bytes 37.760 bytes +15% (fade) a +37% (wifilamp), +26% no total
ESP32-S3 41.584 bytes 53.920 bytes +18% (fade) a +38% (wifilamp), +30% no total
ESP8266 34.592 bytes 49.104 bytes +33% (button) a +49% (wifilamp), +42% no total

Os dados ficam dentro de algumas dezenas de bytes para qualquer lado. A maior imagem clang é a do wifilamp do ESP8266, com 8.944 bytes de código, contra uma IRAM de 32 KB e o limite de 24 KB que seu elfcheck.py impõe aos exemplos, então o crescimento não custa nada que um sketch aqui notaria. Para onde os bytes vão não foi detalhado.

Publicado e verificado

  1. Compilado por .github/workflows/clang-v3.yml, execução 36358476287 (tentativa 3, main em 4578344f): espressif/llvm-project em esp-22.1.4_20260825 com RISCV;AVR;ARM;Xtensa, ambos os patches WASI, depois plan.ts --wasm para as três placas e os testes do simulador sobre o que o wasm compilou. Artefato clang-v3, sha256 do zip ef27b7aa…3eafd; clang.wasm tem 80.735.841 bytes, sha256 7546c54c07c392e231ea450f8e3aaa6680346ffeb08e13d97d970b26d88666e5.
  2. Publicado em 28/09/2026: o artefato descompactado em web/public/toolchain/clang-v3/, depois deploy/fetch-toolchain.sh --publish clang-v3. https://mokxi.com/toolchain/clang-v3/ serve clang.wasm, bundle.json e include.tgz com os tipos certos, os tamanhos certos e o mesmo sha256 do artefato. O bundle.json está sem poda (16 MB, todos os headers de recurso do clang); só suas entradas /usr/include são usadas, e podá-lo como foi feito com o do clang-v2 economizaria a maior parte desse download.
  3. Verificado no Chromium (headless, contra npm run dev com os arquivos publicados em web/public/toolchain/clang-v3/): o editor real abriu um diagrama com seu próprio sketch, apertou Rodar e acompanhou o painel Compilação, o monitor serial e o LED. O sketch do ESP32 entrou no WiFi simulado (192.168.4.2) e piscou o GPIO 4; o sketch do ESP32-S3 piscou o GPIO 2 e imprimiu; o sketch do ESP8266 piscou o D1 e imprimiu uma divisão de 32 bits a cada loop; o próprio exemplo Blink do ESP8266, editado, compilou e piscou também. A primeira compilação de uma placa levou de 5 a 7 s incluindo o runtime, uma posterior cerca de 1,5 s. O ELF que a página compilou para o Blink do ESP8266 é byte a byte o proof/esp8266/blink.elf do workflow.
  4. A verificação do ESP8266 encontrou um bug no motor, corrigido na mesma mudança. O Blink do clang escreve seus pinos na mesma fatia em que estaciona, então o nó do pino se move dentro de um tempo que o núcleo já executou, e o componente da placa adiantou o núcleo estacionado antes do fim dessa fatia. O CCOUNT andou para trás, a contagem de 64 bits de ciclos do runtime leu isso como um overflow de 2^32 ciclos, e toda delay() depois da primeira retornava imediatamente: o LED acendia e ficava aceso. O Blink do GCC nunca escreve um pino na fatia em que estaciona, por isso nenhum exemplo enviado o mostrou, e os testes nativos nunca o mostraram porque executam o SoC sem circuito. Os componentes de placa do ESP32, ESP32-S3 e ESP8266 agora nunca executam o núcleo antes do ponto onde sua última fatia terminou (ran_to em crates/parts/src/parts/esp8266.rs e seus dois irmãos), e blink_keeps_its_half_period_when_a_pin_moves_as_the_core_parks o garante (rode com MOKXI_ESP8266_ELF_DIR apontando para os ELFs do clang).
  5. Ponto flutuante é soft float. -mcpu=esp32 e -mcpu=esp32s3 ativam a FPU de precisão simples, que o modelo não tem, então a princípio uma multiplicação de float, uma comparação ou o isnan(h) || isnan(t) do tutorial do DHT era compilado para uma instrução da FPU e a placa parava. Os bundles agora passam -Xclang -target-feature -Xclang -fp (o driver Xtensa não tem -mfloat-abi), então os floats viram chamadas para mokxi_float.c como em qualquer outra placa soft float e dão as respostas certas. O LX106 do ESP8266 não tem FPU para desligar e linka o mesmo mokxi_float.c.

Próximos passos

  1. Decidir se toda família migra para clang-v3. Até lá, um usuário que compila para um ESP32 e qualquer outra placa mantém dois toolchains de mais de 75 MB no Cache API: isStaleKey (cache.ts) mantém toda versão que uma família nomeia (TOOLCHAINS_IN_USE) e descarta a outra só quando o disco enche. Antes de 2026-10-17 ele descartava toda versão menos a em uso, então cada troca baixava 20 MB de novo e falhava offline. Migrar todas é uma string por família, como foi a migração para clang-v2, mas é LLVM 22.1.4 de um fork em vez de 22.1.0, então rode crash.test.ts e os testes de bibliotecas incluídas contra ele antes, e não presuma saída byte idêntica.
  2. Verificar as bibliotecas incluídas nas famílias Xtensa. firmware/lib está no include path delas como em toda placa, mas stock-libraries.test.ts não as lista, então Servo.h, Wire.h e o resto não são testados lá.
  3. Podar o bundle.json para os cabeçalhos que uma compilação freestanding abre.

Nunca prometer uma compilação no navegador que não funciona: um botão de compilar que rodasse silenciosamente o binário de ontem seria a pior coisa deste produto.

clang-rv32-v1 ainda é o valor de RV32_TOOLCHAIN e nenhuma família o nomeia. Ele fica como caminho de volta: alterar a string toolchain de uma família é tudo o que há para lançar ou reverter uma versão, já que as URLs, a chave do cache de módulos e o cache de objetos em runtime derivam dela.

ready também não é código morto. Duas coisas precisam ser verdade antes que uma família possa carregá-lo, e bundles.test.ts verifica a segunda delas:

  1. O toolchain tem o back end, está publicado, e um sketch que ele compilou rodou no simulador.
  2. A família tem um bundle de runtime, o que significa que seu diretório de firmware existe e bundle-runtime.mjs foi executado.

Uma família que não está ready não é um erro: chooseProgram envia suas placas para o ELF pré-compilado de web/public/firmware/, o painel Compilação e a linha ao lado do seletor de placas dizem o porquê, e nada falha. Hoje nenhuma família segue esse caminho; as famílias Xtensa seguiam até o clang-v3 ser publicado.

O STM32 e o micro:bit são soft float de propósito: DECISIONS.md, 2026-09-14, deixa a FPU e o DSP do M4 fora do escopo até que uma placa M4F seja desejada, então nenhum dos runtimes pode emitir instruções VFP ou uma ABI hard float.

O que acontece quando você aperta Rodar

App.buildPrograms pergunta a chooseProgram (src/compile/client.ts) sobre cada placa e recebe uma de três respostas:

  • elf: rodar a imagem que o painel Firmware nomeia e não compilar nada. Um ELF enviado não foi compilado a partir destes arquivos; um exemplo incluído intocado já está compilado. Uma família cujo toolchain não está publicado também cai aqui.
  • reuse: rodar o ELF já compilado exatamente a partir destes arquivos. A decisão é um hash de todo nome de arquivo e de cada byte nele, então um toque de tecla e um desfazer deixam você de volta em reuse.
  • build: compilar e rodar o resultado.

Uma compilação que falha interrompe a execução: o botão fica em Rodar, o ELF anterior é descartado em vez de usado às escondidas, e os diagnósticos ficam no painel. O ELF compilado vive na memória só para a sessão. É um fato sobre esta sessão, não parte do documento, então nunca é salvo, exportado ou compartilhado.

A lista de comandos

Os mesmos quatorze comandos que firmware/build.sh executa, com duas diferenças que o WASI impõe (ambas resolvidas na prova de conceito):

  1. -c crt0.S faz o clang querer dois trabalhos, um preprocessamento e uma montagem, e o clang desliga seu cc1 integrado assim que há mais de um, o que no WASI vira "unable to execute command: WASI does not support spawning subprocesses". As duas metades são listadas separadamente.
  2. O link vai direto pelo ld.lld em vez do driver do clang, então as flags de link do ESP32-C3 perdem os prefixos -Wl,. firmware/uno/build.sh já chama ld.lld pelo mesmo motivo.

O sistema de arquivos que as ferramentas veem:

caminho o quê
/usr/include cabeçalhos de recursos do clang, do bundle do toolchain
/firmware para o ESP32-C3, /firmware/<family> para o resto nossos fontes de runtime, cabeçalhos, crt0.S, link.ld
/firmware/lib os drivers compartilhados só de cabeçalho, mesmo caminho para toda família
/project os arquivos da placa, com seus próprios nomes, então #include "pins.h" funciona
/build objetos, o sketch encapsulado, o ELF

Assembly

Arquivos .S e .s do próprio projeto também são compilados aqui, assim como o arduino-cli compila um .S ao lado de um sketch, e uma placa pode ser só assembly e nada mais.

Quatro peças, todas em web/src/compile/:

  1. O plano. projectPlan (toolchain.ts) adiciona um par de passos para cada .S: um preprocessamento com o include path, o quote path e as defines do próprio sketch (então #include <avr/io.h> dá os nomes dos registradores e __ASSEMBLER__ é definido), depois uma montagem da cópia preprocessada. São duas execuções pelo motivo que runtimeSteps já dá: -c foo.S faz o clang querer dois trabalhos, e o clang desliga seu cc1 integrado assim que há mais de um, o que no WASI vira "unable to execute command: WASI does not support spawning subprocesses". Um .s é montado diretamente, sem passo de preprocessamento. Os marcadores # <line> "<file>" do preprocessador são preservados, então um diagnóstico e uma linha de DWARF ficam na linha da própria aba em vez da linha da cópia preprocessada, e é isso que permite ao depurador parar em uma linha de .S. O passo de montagem passa só as flags que o próprio assembler lê, mais -g -gdwarf-4.
  2. As verificações de operandos. asm-check.ts lê todo arquivo .S e .s de AVR do projeto antes de qualquer ferramenta rodar, e reporta no formato próprio do clang, arquivo:linha:coluna: error:, de modo que parseDiagnostics e o painel de compilação não precisam saber de nada novo. Ele faz as verificações que o avr-as faz e que o assembler AVR do LLVM silenciosamente não faz: ldi r16, 300 (mantido como 0x2C), sbi PORTB, 1 (um endereço de dados onde vai um endereço de E/S), add r16, 5 (lido como add r16, r5), out PORTB, r16 sem __SFR_OFFSET 0 (um aviso: ele alcança um registrador diferente), in e out acima de 63, sbiw e adiw acima de 63, e um bit acima de 7. Um operando só é avaliado quando pode ser deduzido: números, os próprios .equ, .set e #defines do arquivo, e os nomes de registradores e bits do cabeçalho da placa lidos do pacote de runtime, através de _SFR_IO_ADDR(), lo8(), hi8() e dos operadores de C. Qualquer outra coisa fica para o assembler e o linker, que estão certos sobre essas. Um erro interrompe a compilação antes de uma ferramenta começar (plan.checkFailed).
  3. O link, quando não há sketch. isAssemblyProject (bundles.ts) é um projeto cujos arquivos são apenas assembly; assemblyLinkInputs define o que ele linka além de seus próprios objetos. Em uma placa AVR, isso é o objeto crt0.S do runtime e nada mais, que é o que o gcrt1.o da avr-libc é para o avr-gcc main.S: a tabela de vetores com cada __vector_<n> como um reti weak, r1 zerado, a pilha em RAMEND, .data copiado, .bss zerado e uma chamada ao main do projeto. Um projeto cujo arquivo define sua própria seção .vectors ou o rótulo __vectors (definesVectors) não recebe nada, e o mesmo vale para toda placa ARM, onde o arquivo é a tabela de vetores. Nenhum core do Arduino em nenhum dos casos: sem setup(), sem o tick de millis(), sem Serial.
  4. O desassemblador. disasm.ts é nosso, porque o LLVM do navegador carrega clang, ld.lld e llvm-objcopy e nenhum llvm-objdump. Ele lê os segmentos executáveis do ELF que o app já guarda, então a lista Desmontagem da aba Depurar e o botão de Passo de instrução não precisam de nenhuma ida e volta. O decodificador AVR cobre todo o conjunto de instruções; o decodificador Thumb cobre todas as codificações de 16 bits, o BL, e as formas Thumb-2 de 32 bits que um compilador ou um curso escrevem na maior parte, e mostra qualquer outra coisa como .inst.w 0x… em vez de um palpite errado. O texto é o do llvm-objdump, e disasm.test.ts o mantém lá: cada instrução de compilações reais (os quatro projetos iniciais de assembly, e um sketch com matemática de ponto flutuante, Serial e pinos) para o Uno, o Mega, o Pico e o Black Pill tem que ler exatamente como o llvm-objdump da máquina lê.

Quais placas oferecem um projeto de assembly sem core está em src/asm/boards.ts: o Uno, o Nano, o Pro Mini, o Pico e o STM32F411. Toda outra placa que compila ainda aceita abas .S junto de um sketch, exceto as placas Xtensa (veja acima). asm.test.ts compila e roda tudo isso no simulador.

Uma ferramenta que trava

clang e lld entram num caminho de abort em alguns erros fatais (um #include ausente, principalmente) que imprime o diagnóstico no stderr e então atinge unreachable em vez de chamar exit. Dentro do WASI isso aparece como um WebAssembly.RuntimeError de verdade, não um proc_exit, e de outra forma escaparia como uma rejeição não tratada sem diagnóstico nenhum anexado: uma queda, não um erro de compilação.

Toolchain.run (src/compile/toolchain.ts) captura exatamente isso: uma trava depois que a ferramenta já escreveu algo no stderr volta como um passo comum que falhou, result.trapped definido e result.code diferente de zero, com tudo o que foi escrito antes da trava ainda em result.err. runSteps (src/compile/worker.ts) então trata isso como qualquer outra saída diferente de zero: o que parseDiagnostics encontrou é o que o painel Compilação mostra, clicável como qualquer outro diagnóstico, e só cai para "o compilador travou (<tool> em <step>)" quando a trava não carregava nada a dizer. Cada execução de ferramenta já recebe sua própria WebAssembly.Instance nova a partir do único Module compilado (toolchainFor compila o módulo uma vez; Toolchain.run o instancia a cada chamada), então uma trava numa execução não deixa nada para a próxima. Não há instância para contaminar e nada aqui reinstancia o módulo por conta própria.

As abas .ino são unidas e embrulhadas do jeito que o Arduino IDE faz (src/compile/prototypes.ts): #include "arduino.h", depois a aba principal e as outras abas .ino em ordem alfabética, cada uma atrás de #line 1 "<tab>.ino", com um protótipo para cada função que as abas definem escrito logo antes da primeira função, cada um atrás de um #line apontando para sua definição, e um #line depois do bloco. Assim um sketch que chama uma função definida abaixo de loop() compila, e o compilador ainda relata um problema em sketch.ino:12:3 para o painel Compilação poder levar o editor até lá. Templates, membros de classe, qualquer coisa num namespace, uma função que o próprio sketch declara e uma função cuja assinatura menciona algo declarado mais abaixo não ganham protótipo; uma função dentro de blocos #if ganha seu protótipo dentro de uma cópia das mesmas condições; argumentos padrão vão para o protótipo e são apagados, coluna por coluna, da definição. .c compila como C11, .cpp/.cc/.ino como C++17; qualquer outra coisa é escrita em /project para os includes e não é compilada.

Os arquivos do usuário são compilados com as flags de aviso do runtime menos o -Werror (userWarnings em bundles.ts): avisos de -Wall -Wextra são relatados no painel Compilação, e um objeto em cache guarda seus avisos para serem mostrados de novo no próximo Rodar, mas um aviso não interrompe a compilação, como no Arduino IDE. O próprio runtime, e projectPlan(..., { strict: true }) (a prova Xtensa, os testes de bibliotecas originais e de módulos de comunicação), mantêm o -Werror, que é o que mantém o código e os exemplos do próprio Mokxi limpos de avisos.

O que é guardado em cache, e onde

o quê onde chave perdido quando
bytes de clang.wasm Cache API, mokxi-toolchain-v1 /toolchain/<version>/clang.wasm nenhuma família usa mais a versão, o disco está cheio, o armazenamento é limpo
os arquivos objeto do runtime Cache API, mesmo armazenamento /toolchain/<version>/runtime/<family>-<bundle hash>.objects a versão muda, o firmware muda, o armazenamento é limpo
o WebAssembly.Module compilado o worker, em memória versão do toolchain a página fecha
os arquivos objeto do runtime o worker, em memória versão do toolchain + família a página fecha
o arquivo objeto de cada código-fonte do projeto o worker, em memória texto do código-fonte + o comando exato a página fecha
o ELF compilado o app, em memória id da placa + assinatura do arquivo a página fecha

Os objetos de runtime são uma dúzia de arquivos de alguns kilobytes cada, empacotados em uma única entrada de cache em vez de uma dúzia (MOKO, um comprimento de cabeçalho, um índice JSON de pares [path, length], e depois os bytes um após o outro), então um acerto é um match e um arrayBuffer em vez de doze de cada. A chave carrega um hash do pacote de runtime exatamente como ele foi baixado, cada fonte, cabeçalho e flag nele, de modo que editar firmware/src/gpio.c e regenerar produz uma chave diferente em vez de um arquivo de objeto desatualizado. Qualquer coisa que não possa ser desempacotada é apagada e reconstruída, porque um blob que não conseguimos ler é pior que nenhum blob.

O que não é mais alcançável vai sendo descartado: toda entrada de um toolchain mais antigo, e um runtime de uma família cujas fontes avançaram. Uma família sobre a qual esta página não diz nada é deixada em paz: um usuário com um runtime de Uno em cache que passa o dia de hoje num ESP32-C3 o mantém.

Toda parte disso degrada graciosamente: sem Cache API, um cache que lança erro, um put que bate na cota: cada um significa "refazer o trabalho", nunca "sem compilador".

Medido

No Chromium 141 no contêiner de compilação, contra npm run dev em loopback (que serve o clang.wasm sem compressão, então o download é o caso pessimista; a produção o serve do R2 com Content-Encoding: br):

clique até rodar o que ele fez
primeira compilação, fria 6,1 a 7,8 s download de 74 MB, WebAssembly.compile, 12 objetos de runtime, sketch, link, strip
segunda visita e seguintes 1,5 a 1,8 s nenhuma requisição de clang.wasm; runtime vindo da Cache API em 3 a 9 ms
editar e Rodar de novo, na mesma sessão 0.21 s sketch.ino 51 ms, link 10 ms, strip 5 ms
Rodar sem edição nenhuma compilação
o ELF 1,5 KB pisca o GPIO 8 na taxa que o sketch pede, no motor real a 1,00x

Quatro visitas num mesmo perfil de navegador fizeram uma requisição de clang.wasm, e a segunda e todas as seguintes pularam o runtime inteiramente:

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

O que sobra de uma visita de retorno são duas coisas, nenhuma delas o runtime: cerca de 0,7 s para ler os 74 MB de volta da Cache API e fazer compileStreaming, e cerca de 0,5 s para a primeira execução de ferramenta num módulo recém-compilado, que é o motor aquecendo; a segunda edição na mesma sessão são os 51 ms acima.

O painel Compilação mostra a porcentagem do download, cada passo com seu tempo, e uma linha no final: Built esp1.elf, 1.5 KB, 0.21 s.

O que o Worker precisa servir

/toolchain/<version>/<file> precisa vir do bucket R2 mokxi-toolchain (objetos <version>/<file>), com um Cache-Control longo (o caminho tem versão, então os objetos são imutáveis) e Content-Encoding: br para o wasm. A resposta precisa de Content-Type: application/wasm e um Content-Length: a barra de progresso do painel lê o comprimento, e WebAssembly.compileStreaming recusa qualquer coisa que não seja application/wasm.

O CMSIS e a HAL da ST nas placas STM32

A Nucleo-F411RE, a Black Pill e a Blue Pill também compilam código escrito para os cabeçalhos da própria ST: código de registradores que inclui stm32f4xx.h (ou stm32f1xx.h, ou o antigo stm32f10x.h) e projetos do STM32CubeIDE na HAL do STM32Cube. Os arquivos da ST são incluídos em firmware/stm32cube/ (veja o README dele para os commits e licenças originais) e empacotados por web/scripts/bundle-stm32cube.mjs em web/public/firmware/stm32cube/f4.json e f1.json, cerca de 0,47 e 0,40 MB com Brotli. Eles não estão nos pacotes do runtime nem no primeiro carregamento do editor: o worker busca um deles só quando um projeto inclui um dos cabeçalhos da ST, ou um main.h que ele não tem (wantsCube em src/compile/stm32cube.ts), e o mantém para a página.

cubePlan decide o resto, e projectPlan o segue:

  • o pacote é montado em /stm32cube, seus diretórios de include entram no caminho, com -DSTM32F411xE ou -DSTM32F103xB, -DUSE_HAL_DRIVER quando a HAL é usada, -DUSE_FULL_LL_DRIVER quando a LL é, e -DMOKXI_ST_CMSIS, que faz o cabeçalho de placa do próprio runtime deferir ao da ST num sketch;
  • os módulos da HAL que o stm32f?xx_hal_conf.h do projeto habilita, os arquivos LL que ele inclui e o arquivo de sistema são compilados com -w e ligados como membros de biblioteca, então uma primeira compilação com HAL compila cerca de uma dúzia de arquivos da ST (9 a 15 segundos no wasm do clang-v2 nos testes) e a próxima reutiliza seus objetos;
  • um projeto com seu próprio main() é ligado bare (bareMetalLinkInputs): o código de inicialização e a tabela de vetores do runtime como estão, todo outro objeto de runtime como membro de biblioteca, e mokxi_cube_bare.c roteando printf() pelo _write() ou __io_putchar() do projeto. Um sketch mantém o core do Arduino, e mokxi_cube_sketch.c faz o tick da HAL virar millis();
  • o que faltar num projeto colado é escrito com os padrões do CubeIDE para a placa (main.h, a configuração da HAL, o handler do SysTick, um arquivo MSP), o arquivo de inicialização da ST e o syscalls.c e sysmem.c do CubeIDE ficam de fora, e cada um desses é uma nota no log de compilação (ProjectPlan.notes);
  • um projeto que chama um periférico que o chip simulado não tem (SPI, I2C, DMA, o RTC e outros) recebe uma nota dizendo isso; a compilação ainda assim funciona.

Os chips simulados não têm interface de flash, controlador de energia nem região bit-band, e a HAL escreve os três em HAL_Init() e em todo SystemClock_Config() do CubeIDE. O construtor do pacote adiciona um include ao cabeçalho de dispositivo da ST (mokxi_cube_regs.h: FLASH e PWR viram RAM com o mesmo layout) e um ao stm32f?xx_hal.h (mokxi_cube_hal.h: as escritas bit-band das macros do RCC viram escritas comuns de registrador); os arquivos incorporados ficam inalterados. src/compile/stm32cube.test.ts compila e roda todo exemplo em firmware/stm32cube/examples/, e /learn/stm32-hal-register-code é a página para os usuários.

Limites

  • C, C++ e assembly (.S e .s, veja acima). Sem MicroPython e sem outra linguagem: o MicroPython do Pico e um main.py de Raspberry Pi rodam uma imagem de firmware em vez de passar por este caminho.
  • Um projeto é plano: os nomes de arquivo não carregam diretórios, então o caminho de include tem um diretório de profundidade.
  • Uma placa cuja string program do catálogo não nomeia família nenhuma não tem família nenhuma, então familyFor não encontra nada e ela roda seu ELF pré-compilado. Uma placa cuja família não está ready faz o mesmo, com a note da família mostrada no painel.
  • Uma visita de retorno ainda paga cerca de 0,7 s para tirar os 74 MB de volta da Cache API e compilá-los. compileStreaming a partir de uma Response em cache é o que permite ao motor reutilizar seu próprio cache de código, mas nada aqui pode tornar isso uma certeza.
  • Em desenvolvimento o toolchain é servido pelo Vite a partir de web/public/toolchain/; em produção o Worker o serve do R2. worker/assets.ts responde 404 para /toolchain/ de propósito, então o middleware de dev em web/vite.config.ts precisa deixar esse prefixo em paz. Ele deixa, e quebrar isso é como o compilador acaba baixando a página 404.

Perguntas

Onde a compilação acontece?

Na sua máquina, na aba. Não há servidor de compilação, nem fila, nem minutos de compilação.

Qual o tamanho do toolchain?

Cerca de setenta megabytes. Ele é baixado em streaming uma vez e o navegador o guarda em cache, então depois da primeira compilação tudo é local.