Referensi

Mengompilasi sketch di browser

Bagaimana sebuah sketch menjadi firmware tanpa server build di mana pun.

File sebuah board dikompilasi oleh clang sungguhan dan lld sungguhan, yang berjalan sebagai WebAssembly di dalam halaman. Tidak ada server build, tidak ada yang diunggah, dan ELF yang dihasilkan adalah jenis image yang sama seperti yang dibuat firmware/build.sh: compiler yang sama dijalankan dengan daftar perintah yang sama.

Bukti bahwa ini berfungsi, beserta angka yang menjadi alasan membangunnya, ada di proofs/compile/REPORT.md. Dokumen ini menjelaskan bagaimana produknya melakukannya.

Bentuknya

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

Semuanya kecuali panel Build berjalan di worker, jadi build pertama selama empat detik tidak pernah memblokir satu frame kanvas pun.

Apa yang harus sampai ke browser

Dua hal, dari dua tempat.

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 menjalankan bentuk --check, jadi perubahan pada firmware/ yang tidak dibawa siapa pun akan menggagalkan rangkaian test, bukan build milik pengguna.

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.

Versi toolchain dikunci per family board

Versi adalah properti dari family, bukan dari aplikasinya, karena kedua build itu bukan satu compiler: clang-rv32-v1 dikonfigurasi dengan LLVM_TARGETS_TO_BUILD=RISCV saja, jadi dia bisa mengompilasi untuk ESP32-C3 dan secara fisik tidak bisa mengompilasi untuk Uno. clang-v2 adalah script build yang sama dengan LLVM_TARGETS_TO_BUILD=RISCV;AVR;ARM (layout sama, bucket sama, bentuk URL sama), dan setiap family yang bisa dikompilasi hari ini dipasangkan ke situ (DECISIONS.md, 2026-09-14: diverifikasi di ketiga backend dan diunggah ke R2). Output RISC-V-nya identik byte per byte dengan milik clang-rv32-v1, jadi ESP32-C3 juga pindah ke sana dan setiap board seperti itu berbagi satu unduhan. Family Xtensa dipasangkan ke clang-v3 (XTENSA_TOOLCHAIN), diterbitkan 2026-09-28:

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

Tiga baris terakhir adalah bagian selanjutnya. web/src/compile/bundles.ts adalah daftar yang dibaca tabel ini, dan bundles.test.ts menjaga keduanya tetap sinkron.

Board Xtensa, di clang-v3

ESP32 klasik adalah Xtensa LX6, ESP8266 NodeMCU adalah Xtensa LX106, dan ESP32-S3 adalah Xtensa LX7. Ketiganya dikompilasi di browser dengan clang-v3 sejak 2026-09-28 ("Diterbitkan dan diperiksa" di bawah). Sebelum itu mereka menjalankan ELF prebuilt dan mengatakannya. Bagian selanjutnya menjelaskan mengapa perlu fork, dan apa yang ditemukan pengujiannya.

Mengapa ini toolchain terpisah (diperiksa 2026-09-27):

  1. clang-v2 tidak punya back end Xtensa. Ia dibangun dengan LLVM_TARGETS_TO_BUILD=RISCV;AVR;ARM (DECISIONS.md, 2026-09-14). Wasm yang diunduh browser secara fisik tidak bisa menghasilkan objek Xtensa.
  2. LLVM upstream punya separuh dari yang dibutuhkan, dan separuh yang salah. Clang telah membawa front end Xtensa sejak LLVM 20 (Phoronix), dan LLVM 22 punya XtensaProcessors.td yang tahu esp32 dan esp8266 (upstream main menambahkan esp32s2 dan esp32s3). Tapi ld.lld upstream tidak punya target Xtensa sama sekali: tidak ada lld/ELF/Arch/Xtensa.cpp di main atau di release/22.x, jadi tidak ada apa pun di upstream yang bisa men-link image ESP32. Backend upstream juga masih menghasilkan literal pool secara inline di .text, yang merusak l32r alignment di bawah -ffunction-sections (llvm/llvm-project#190204, masih terbuka). Xtensa masih dalam tahap LLVM_ALL_EXPERIMENTAL_TARGETS upstream.
  3. Espressif's fork has all of it. esp-clang (espressif/llvm-project, terbaru 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).

Jadi ini fork yang harus diikuti, bukan flag yang tinggal ditambahkan, tapi fork ini milik Espressif sendiri, dirilis tiap beberapa bulan, dan dengan lisensi yang sama dengan LLVM asal clang-v2 itu.

ELF prebuilt masih dibangun oleh GCC milik Espressif, yang deploy/fetch-xtensa.sh taruh di tools/xtensa/: xtensa-esp32-elf-gcc 8.4.0 untuk LX6, xtensa-esp32s3-elf-gcc 8.4.0 untuk LX7, dan xtensa-lx106-elf-gcc 8.4.0 untuk LX106. Runtime S3 memakai ulang crt0.S dan support64.c milik ESP32 klasik: untuk kode yang dihasilkan compiler dari C, LX7 adalah LX6, dan output compiler S3 untuk program uji yang sama identik byte per byte dengan output compiler ESP32. Direktori itu di-gitignore. GCC berlisensi GPL, dan tidak ada yang dibangunnya di sini yang di-link ke libgcc (runtime-nya -nostdlib dengan support.c mereka sendiri, dan support32.c milik ESP8266 menyediakan pembagian 32-bit yang tidak punya instruksi di LX106), jadi tidak ada kode GPL yang masuk ke ELF yang dikirim.

Terbukti secara native

Sebelum wasm ada, sisi compiler dibuktikan dengan build Linux native dari fork yang sama (clang-esp-22.1.4_20260825-x86_64-linux-gnu.tar.xz, 411 MB, sha256 4700ed4e...eb0a1, diekstrak menjadi 2.7 GB dan berisi ld.lld):

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

Script ini mengunduh rilis tersebut, lalu menjalankan proofs/compile/xtensa/plan.ts --native, yang tidak menyalin perintah apa pun: ia mengambil runtimeSteps dan projectPlan dari web/src/compile/toolchain.ts serta bundle runtime yang di-commit web/public/firmware/runtime/esp32.json, esp32s3.json, dan esp8266.json, jadi yang dijalankan adalah daftar perintah milik browser, crt0.S dipecah menjadi bagian preprocess dan assemble-nya, ld.lld dipanggil langsung, llvm-objcopy ke stdout. Hasil pada 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 menyelesaikan setiap relokasi (pada objek ESP32: 3,407 R_XTENSA_32 dan 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. Ini adalah test yang sama yang diloloskan oleh ELF GCC: setengah periode 500 ms milik blink, LEDC dan software PWM di 1 kHz, millis() terhadap jam kernel, jarak bit UART0, ADC, frame WS2812 milik S3 pada LED RGB-nya (putih, lalu hijau pelangi pertama di kabel), dan paket serial USB-nya, koneksi WiFi dan halaman web lampu. Tiga variabel lingkungan itu hanya mengarahkan test yang ada ke direktori lain; file rusak di sana membuat mereka panic, jadi mereka benar-benar memuat apa yang dibangun.

Tiga hal yang ditemukan pembuktian ini, semuanya sudah ditangani di bundle:

  • -fintegrated-as diperlukan. Untuk Xtensa, driver Espressif menyerahkan sebuah .s file ke assembler GNU eksternal (xtensa-esp32-elf-clang-as) secara default, yang tidak bisa di-spawn oleh WASI. Dengan -fintegrated-as assembler milik clang sendiri memproses crt0.S apa adanya. Flag ini ada di flag target family tersebut, jadi bagian assemble pun mendapatkannya. Espressif mematikannya untuk input assembly dengan sengaja (EspBareMetal.cpp: "TODO: Add full support for Xtensa to integrated asm, LLVM-290, LLVM-291"), jadi belum lengkap untuk setiap file tulisan tangan; untuk kedua file crt0.S kita, ia lengkap, itulah yang ditunjukkan test simulator. Ini juga alasan file .S dan .s milik proyek sendiri tidak ditawarkan di board Xtensa: hanya .c, .cpp dan .ino yang dikompilasi di sana, sementara setiap family lain mengassemble file milik proyek sendiri juga (lihat Assembly di bawah). C dan C++ selalu lewat integrated assembler, di fork ini maupun di upstream.
  • Tidak ada peringatan multilib di wasm. Instalasi native memperingatkan bahwa ia tidak punya multilib esp8266 (error di bawah -Werror) karena multilib.yaml-nya tidak punya entri itu. BareMetal::findMultilibs hanya membaca multilib.yaml yang ada, dan filesystem wasm tidak punya satu pun, jadi hanya run native yang butuh -Wno-missing-multilib, dan hanya plan.ts --native yang memberikannya.
  • GCC punya -mlongcalls dan -mtext-section-literals yang perlu dilepas. Clang melaporkan -mlongcalls sebagai argumen tak terpakai, error di bawah -Werror. Tanpa -mtext-section-literals clang memancarkan .literal.<function> section, yang ketiga file link.ld sudah menaruhnya di awal .text, well inside L32R's 256 KB reach.

Ukuran kode, segmen executable setiap contoh dibandingkan image GCC yang dikirimkan (source yang sama, keduanya -Os):

board GCC, semua contoh clang per contoh
ESP32 29,984 bytes 37,760 bytes +15% (fade) sampai +37% (wifilamp), +26% keseluruhan
ESP32-S3 41,584 bytes 53,920 bytes +18% (fade) sampai +38% (wifilamp), +30% keseluruhan
ESP8266 34,592 bytes 49,104 bytes +33% (button) sampai +49% (wifilamp), +42% keseluruhan

Data hanya berbeda dalam hitungan puluhan byte ke arah mana pun. Image clang terbesar adalah wifilamp milik ESP8266 dengan 8,944 bytes kode, dibandingkan IRAM 32 KB dan batas 24 KB yang elfcheck.py berlakukan pada contoh, jadi pertumbuhan ini tidak berdampak pada apa pun yang bisa dirasakan sketch di sini. Ke mana byte-byte itu pergi belum diuraikan.

Dipublikasikan dan diperiksa

  1. Dibangun oleh .github/workflows/clang-v3.yml, run 36358476287 (percobaan ke-3, main di 4578344f): espressif/llvm-project di esp-22.1.4_20260825 dengan RISCV;AVR;ARM;Xtensa, kedua patch WASI, lalu plan.ts --wasm untuk ketiga board dan test simulator pada hasil build wasm. Artifact clang-v3, sha256 zip-nya ef27b7aa…3eafd; clang.wasm berukuran 80,735,841 byte, sha256 7546c54c07c392e231ea450f8e3aaa6680346ffeb08e13d97d970b26d88666e5.
  2. Dipublikasikan 2026-09-28: artifact di-unzip ke web/public/toolchain/clang-v3/, lalu deploy/fetch-toolchain.sh --publish clang-v3. https://mokxi.com/toolchain/clang-v3/ menyajikan clang.wasm, bundle.json dan include.tgz dengan tipe yang benar, panjang yang benar, dan sha256 yang sama dengan artifact. bundle.json itu belum di-prune (16 MB, semua header resource clang); hanya entri /usr/include-nya yang dipakai, dan mem-prune-nya seperti bundle.json clang-v2 akan menghemat sebagian besar unduhan itu.
  3. Dicek di Chromium (headless, terhadap npm run dev dengan file yang dipublikasikan di web/public/toolchain/clang-v3/): editor sungguhan membuka diagram dengan sketch-nya sendiri, menekan Jalankan, dan mengamati panel build, serial monitor, dan LED. Sketch ESP32 bergabung ke WiFi simulasi (192.168.4.2) dan mengedipkan GPIO 4; sketch ESP32-S3 mengedipkan GPIO 2 dan mencetak; sketch ESP8266 mengedipkan D1 dan mencetak pembagian 32-bit tiap loop; contoh Blink bawaan ESP8266 sendiri, setelah diedit, ikut ter-build dan berkedip juga. Build pertama sebuah board memakan 5 sampai 7 detik termasuk runtime, build berikutnya sekitar 1,5 detik. ELF yang dibangun halaman untuk Blink ESP8266 sama byte demi byte dengan proof/esp8266/blink.elf milik workflow.
  4. Pengecekan ESP8266 menemukan bug engine, diperbaiki di perubahan yang sama. Blink dari clang menulis pinnya di slice yang sama dengan slice tempat ia parkir, jadi net pin bergerak di dalam waktu yang sudah dijalankan core, dan komponen board menggeser core yang parkir sebelum akhir slice itu. CCOUNT berjalan mundur, penghitung siklus 64-bit runtime membacanya sebagai wrap 2^32 siklus, dan setiap delay() setelah yang pertama langsung kembali: LED menyala dan tetap menyala. Blink dari GCC tidak pernah menulis pin di slice tempatnya parkir, itulah mengapa tidak ada contoh bawaan yang menunjukkannya, dan test native tidak pernah menunjukkannya karena mereka menjalankan SoC tanpa rangkaian. Komponen board ESP32, ESP32-S3, dan ESP8266 kini tidak pernah menjalankan core lebih awal dari akhir slice terakhirnya (ran_to di crates/parts/src/parts/esp8266.rs dan dua saudaranya), dan blink_keeps_its_half_period_when_a_pin_moves_as_the_core_parks menjaganya (jalankan dengan MOKXI_ESP8266_ELF_DIR menunjuk ke ELF clang).
  5. Floating point menggunakan soft float. -mcpu=esp32 dan -mcpu=esp32s3 mengaktifkan FPU presisi tunggal, yang tidak dimiliki oleh model, sehingga awalnya perkalian float, perbandingan, atau kode isnan(h) || isnan(t) dari tutorial DHT dikompilasi menjadi instruksi FPU dan board berhenti. Bundle sekarang meneruskan -Xclang -target-feature -Xclang -fp (driver Xtensa tidak punya -mfloat-abi), jadi float menjadi pemanggilan ke mokxi_float.c seperti di board soft float lainnya dan memberikan hasil yang benar. LX106 milik ESP8266 tidak punya FPU untuk dimatikan dan me-link mokxi_float.c yang sama.

Langkah berikutnya

  1. Putuskan apakah setiap family pindah ke clang-v3. Sampai itu terjadi, pengguna yang build untuk ESP32 dan board lain menyimpan dua toolchain berukuran lebih dari 75 MB di Cache API: isStaleKey (cache.ts) menyimpan setiap versi yang disebut sebuah family (TOOLCHAINS_IN_USE) dan menghapus yang lain hanya saat disk penuh. Sebelum 2026-10-17 fungsi itu menghapus semua versi kecuali yang sedang dipakai, jadi setiap pergantian mengunduh 20 MB lagi dan gagal saat offline. Memindahkan semuanya hanya satu string per family, seperti saat pindah ke clang-v2, tapi ini LLVM 22.1.4 dari fork bukan 22.1.0, jadi jalankan crash.test.ts dan tes library bawaan terhadapnya dulu, dan jangan asumsikan outputnya identik byte per byte.
  2. Periksa library bawaan di family Xtensa. firmware/lib ada di include path mereka seperti di setiap board, tapi stock-libraries.test.ts tidak mencantumkannya, jadi Servo.h, Wire.h dan sisanya belum diuji di sana.
  3. Pangkas bundle.json hanya ke header yang dibuka oleh build freestanding.

Jangan pernah mengklaim compile di browser yang tidak berfungsi: tombol build yang diam-diam menjalankan binary kemarin adalah hal terburuk dalam produk ini.

clang-rv32-v1 masih menjadi nilai RV32_TOOLCHAIN dan tidak ada family yang menyebutnya. Ia tetap ada sebagai jalan kembali: mengubah string toolchain sebuah family adalah seluruh proses meluncurkan atau menarik kembali sebuah build, karena URL, kunci cache modul, dan cache objek runtime semuanya bergantung padanya.

ready juga bukan kode mati. Dua hal harus benar sebelum sebuah family bisa membawanya, dan bundles.test.ts memeriksa yang kedua:

  1. Toolchain punya back end, sudah dipublikasikan, dan sketch yang di-buildnya sudah berjalan di simulator.
  2. Family punya bundle runtime, artinya direktori firmwarenya ada dan bundle-runtime.mjs sudah dijalankan.

Family yang tidak ready bukanlah error: chooseProgram mengirim boardnya ke ELF pra-build dari web/public/firmware/, panel build dan baris di samping pemilih board menjelaskan alasannya, dan tidak ada yang gagal. Hari ini tidak ada family yang mengambil jalur itu; family Xtensa melakukannya sampai clang-v3 dipublikasikan.

STM32 dan micro:bit sengaja soft float: DECISIONS.md, 2026-09-14, menempatkan FPU dan DSP M4 di luar cakupan sampai board M4F diinginkan, jadi tidak ada runtime yang boleh memancarkan instruksi VFP atau ABI hard-float.

Apa yang terjadi saat kamu menekan Jalankan

App.buildPrograms menanyakan setiap board ke chooseProgram (src/compile/client.ts), dan mendapat satu dari tiga jawaban:

  • elf: jalankan image yang disebut panel Firmware dan jangan compile apa pun. ELF yang diunggah tidak dibangun dari file ini; contoh bawaan yang belum disentuh sudah dibangun. Family yang toolchainnya belum dipublikasikan juga masuk ke sini.
  • reuse: jalankan ELF yang sudah dibangun persis dari file ini. Keputusannya berdasarkan hash dari setiap nama file dan setiap byte di dalamnya, jadi satu ketukan tombol dan satu urungkan mengembalikanmu ke reuse.
  • build: compile, lalu jalankan hasilnya.

Build yang gagal menghentikan jalannya: tombol tetap di Jalankan, ELF sebelumnya dibuang alih-alih dipakai diam-diam, dan diagnostiknya tetap di panel. ELF hasil build hanya hidup di memori untuk sesi ini. Ini fakta tentang sesi ini, bukan bagian dari dokumen, jadi tidak pernah disimpan, diekspor, atau dibagikan.

Daftar perintah

Empat belas perintah yang sama yang dijalankan firmware/build.sh, dengan dua perbedaan yang dipaksakan WASI (keduanya sudah dipecahkan dalam proof of concept):

  1. -c crt0.S membuat clang butuh dua pekerjaan, satu preprocess dan satu assemble, dan clang mematikan cc1 terintegrasinya begitu ada lebih dari satu, yang di WASI berarti "unable to execute command: WASI does not support spawning subprocesses". Kedua bagian itu didaftar terpisah.
  2. Link dilakukan lewat ld.lld langsung, bukan lewat driver clang, jadi flag link ESP32-C3 kehilangan awalan -Wl,-nya. firmware/uno/build.sh sudah memanggil ld.lld dengan alasan yang sama.

Filesystem yang dilihat tool:

path apa
/usr/include header resource milik clang, dari bundle toolchain
/firmware untuk ESP32-C3, /firmware/<family> untuk sisanya source runtime kami, header, crt0.S, link.ld
/firmware/lib driver header-only bersama, path yang sama untuk setiap family
/project file milik board, dengan nama mereka sendiri, jadi #include "pins.h" berfungsi
/build objek, sketch yang dibungkus, ELF

Assembly

File .S dan .s milik sebuah proyek juga dibangun di sini, seperti arduino-cli membangun .S di samping sebuah sketch, dan sebuah board bisa berisi assembly saja.

Empat bagian, semuanya di web/src/compile/:

  1. Rencananya. projectPlan (toolchain.ts) menambahkan sepasang langkah untuk setiap .S: satu preprocess dengan include path milik sketch itu sendiri, quote path, dan defines (sehingga #include <avr/io.h> memberikan nama register dan __ASSEMBLER__ disetel), lalu satu assemble dari salinan hasil preprocess. Ini dua run karena alasan yang sudah diberikan runtimeSteps: -c foo.S membuat clang butuh dua pekerjaan, dan clang mematikan cc1 terintegrasinya begitu ada lebih dari satu, yang di WASI berarti "unable to execute command: WASI does not support spawning subprocesses". File .s dirakit langsung, tanpa langkah preprocess. Penanda # <line> "<file>" dari preprocessor ikut terbawa, jadi diagnostik dan baris DWARF memakai baris tab itu sendiri, bukan baris salinan hasil preprocess, dan inilah yang memungkinkan debugger berhenti di baris .S. Langkah assemble hanya meneruskan flag yang dibaca assembler itu sendiri, plus -g -gdwarf-4.
  2. Pemeriksaan operand. asm-check.ts membaca setiap file AVR .S dan .s proyek sebelum alat apa pun berjalan, dan melaporkan dalam format file:line:col: error: milik clang sendiri sehingga parseDiagnostics dan panel Build tidak perlu tahu hal baru. Pemeriksaan ini melakukan pemeriksaan yang dilakukan avr-as dan yang tidak dilakukan secara diam-diam oleh assembler AVR milik LLVM: ldi r16, 300 (disimpan sebagai 0x2C), sbi PORTB, 1 (alamat data pada tempat yang seharusnya alamat I/O), add r16, 5 (dibaca sebagai add r16, r5), out PORTB, r16 tanpa __SFR_OFFSET 0 (sebuah peringatan: ini menuju register yang berbeda), in dan out melewati 63, sbiw dan adiw melewati 63, dan bit melewati 7. Sebuah operand hanya dinilai bila nilainya bisa dihitung: angka, .equ milik file itu sendiri, .set dan #define, serta nama register dan bit dari header board yang dibaca dari runtime bundle, melalui _SFR_IO_ADDR(), lo8(), hi8() dan operator C. Selain itu diserahkan ke assembler dan linker, yang memang benar untuk hal-hal tersebut. Error menghentikan build sebelum alat apa pun mulai berjalan (plan.checkFailed).
  3. Link, saat tidak ada sketch. isAssemblyProject (bundles.ts) adalah proyek yang file-nya hanya berisi assembly; assemblyLinkInputs menentukan apa yang di-link selain objek miliknya sendiri. Di board AVR itu adalah objek crt0.S milik runtime dan tidak ada yang lain, yaitu apa yang menjadi gcrt1.o milik avr-libc bagi avr-gcc main.S: tabel vektor dengan setiap __vector_<n> sebagai reti lemah, r1 dikosongkan, stack di RAMEND, .data disalin, .bss dikosongkan, dan pemanggilan main milik proyek. Proyek yang file-nya mendefinisikan section .vectors atau label __vectors sendiri (definesVectors) tidak mendapatkannya, begitu juga setiap board ARM, di mana file-nya adalah tabel vektor. Tidak ada Arduino core di kedua kasus: tidak ada setup(), tidak ada tick millis(), tidak ada Serial.
  4. Disassembler. disasm.ts buatan kami, karena LLVM di browser membawa clang, ld.lld dan llvm-objcopy dan tidak ada llvm-objdump. Ia membaca segmen executable dari ELF yang sudah disimpan aplikasi, jadi daftar Disassembly pada tab Debug dan tombol Step instruction-nya tidak perlu round trip. Decoder AVR mencakup seluruh set instruksi; decoder Thumb mencakup semua encoding 16-bit, BL, dan bentuk Thumb-2 32-bit yang paling sering ditulis compiler atau kursus, dan menampilkan sisanya sebagai .inst.w 0x… alih-alih menebak keliru. Teksnya mengikuti format llvm-objdump, dan disasm.test.ts menjaganya tetap begitu: setiap instruksi dari build nyata (empat starter assembly, dan sebuah sketch dengan matematika floating-point, Serial dan pin) untuk Uno, Mega, Pico dan Black Pill harus terbaca persis seperti llvm-objdump mesin membacanya.

Board mana saja yang menawarkan proyek assembly tanpa core ada di src/asm/boards.ts: Uno, Nano, Pro Mini, Pico dan STM32F411. Setiap board lain yang bisa dikompilasi tetap menerima tab .S di samping sketch, kecuali board Xtensa (lihat di atas). asm.test.ts membangun dan menjalankan semuanya di simulator.

Tool yang terjebak trap

clang dan lld keduanya menempuh jalur abort pada sebagian error fatal (terutama #include yang hilang) yang mencetak diagnostik ke stderr lalu mengenai unreachable alih-alih memanggil exit. Di dalam WASI itu muncul sebagai WebAssembly.RuntimeError sungguhan, bukan proc_exit, dan tanpa ini akan lolos sebagai rejection tak tertangkap tanpa diagnostik yang menyertainya: crash, bukan error build.

Toolchain.run (src/compile/toolchain.ts) menangkap persis kasus itu: trap setelah tool sudah menulis sesuatu ke stderr kembali sebagai langkah gagal biasa, result.trapped di-set dan result.code tidak nol, dengan semua yang tertulis sebelum trap tetap ada di result.err. runSteps (src/compile/worker.ts) lalu memperlakukannya seperti exit tidak nol lainnya: apa pun yang ditemukan parseDiagnostics itulah yang ditampilkan panel Build, bisa diklik seperti setiap diagnostik lain, dan hanya mundur ke "compiler crash (<tool> pada <step>)" bila trap tidak membawa pesan apa pun. Setiap run tool sudah mendapat WebAssembly.Instance segar dari satu Module yang dikompilasi (toolchainFor mengompilasi modul sekali; Toolchain.run meng-instansiasinya setiap panggilan), jadi trap pada satu run tidak menyisakan apa pun untuk run berikutnya. Tidak ada instance yang bisa teracuni dan tidak ada yang di sini meng-instansiasi ulang modulnya sendiri.

Tab .ino digabungkan dan dibungkus seperti yang dilakukan Arduino IDE (src/compile/prototypes.ts): #include "arduino.h", lalu tab utama dan tab .ino lainnya sesuai urutan alfabet, masing-masing di belakang #line 1 "<tab>.ino", dengan prototype untuk setiap fungsi yang didefinisikan tab-tab itu ditulis tepat sebelum fungsi pertama, masing-masing di belakang #line yang menunjuk ke definisinya, dan sebuah #line setelah blok itu. Jadi sketch yang memanggil fungsi yang didefinisikan di bawah loop() tetap terbangun, dan compiler tetap melaporkan masalah di sketch.ino:12:3 sehingga panel Build bisa melompatkan editor ke sana. Template, anggota class, apa pun yang berada di dalam namespace, fungsi yang dideklarasikan sendiri oleh sketch, dan fungsi yang signature-nya menyebut sesuatu yang dideklarasikan lebih bawah tidak mendapat prototype; fungsi di dalam blok #if mendapat prototype-nya di dalam salinan kondisi yang sama; argumen default pindah ke prototype dan dikosongkan, kolom demi kolom, dari definisinya. .c dikompilasi sebagai C11, .cpp/.cc/.ino sebagai C++17; selain itu ditulis ke /project untuk include dan tidak dikompilasi.

File milik pengguna dikompilasi dengan flag peringatan runtime dikurangi -Werror (userWarnings di bundles.ts): peringatan -Wall -Wextra dilaporkan di panel Build, dan objek yang di-cache menyimpan peringatannya sehingga ditampilkan lagi pada Jalankan berikutnya, tetapi peringatan tidak menghentikan build, sama seperti di Arduino IDE. Runtime itu sendiri, dan projectPlan(..., { strict: true }) (pembuktian Xtensa, tes library bawaan dan modul komunikasi), tetap memakai -Werror, inilah yang menjaga kode dan contoh milik Mokxi sendiri tetap bersih dari peringatan.

Apa yang di-cache, dan di mana

apa di mana key hilang saat
byte clang.wasm Cache API, mokxi-toolchain-v1 /toolchain/<version>/clang.wasm tidak ada family yang memakai versi itu lagi, disk penuh, storage dibersihkan
file objek runtime Cache API, store yang sama /toolchain/<version>/runtime/<family>-<bundle hash>.objects versi berubah, firmware berubah, storage dibersihkan
WebAssembly.Module yang telah dikompilasi worker, di memori versi toolchain halaman ditutup
file objek runtime worker, di memori versi toolchain + family halaman ditutup
file objek dari setiap sumber proyek worker, di memori teks sumber + perintah persisnya halaman ditutup
ELF hasil build aplikasi, di memori id board + signature file halaman ditutup

Objek runtime itu belasan file berukuran beberapa kilobyte masing-masing, dikemas ke satu entri cache alih-alih belasan (MOKO, panjang header, indeks JSON dari pasangan [path, length], lalu byte-nya berurutan), jadi satu hit berarti satu match dan satu arrayBuffer, bukan dua belas kali masing-masing. Key-nya membawa hash bundle runtime persis seperti saat diambil, semua source dan header dan flag di dalamnya, jadi mengedit firmware/src/gpio.c dan regenerasi menghasilkan key yang berbeda, bukan file objek basi. Apa pun yang tidak bisa dibongkar dihapus dan dibangun ulang, karena blob yang tak bisa kita baca lebih buruk daripada tanpa blob.

Yang tidak lagi terjangkau ikut terbuang saat lewat: setiap entri toolchain yang lebih lama, dan runtime untuk keluarga yang source-nya sudah berubah. Keluarga yang tidak disebut halaman ini dibiarkan saja: pengguna dengan runtime Uno di cache yang hari ini sibuk dengan ESP32-C3 tetap menyimpannya.

Setiap bagian dari ini ikut menurun kualitasnya: tanpa Cache API, cache yang melempar error, put yang kena kuota: semuanya berarti "kerjakan ulang pekerjaannya", tidak pernah "tanpa compiler".

Terukur

Di Chromium 141 pada build container, terhadap npm run dev di loopback (yang menyajikan clang.wasm tanpa kompresi, jadi unduhannya adalah kasus terburuk; produksi menyajikannya dari R2 dengan Content-Encoding: br):

klik sampai berjalan apa yang dilakukannya
build pertama, dingin 6,1 sampai 7,8 detik unduhan 74 MB, WebAssembly.compile, 12 objek runtime, sketch, link, strip
kunjungan kedua dan setelahnya 1,5 sampai 1,8 detik tidak ada request clang.wasm; runtime keluar dari Cache API dalam 3 sampai 9 ms
edit dan Jalankan lagi, sesi yang sama 0.21 s sketch.ino 51 ms, link 10 ms, strip 5 ms
Jalankan tanpa edit tidak ada kompilasi sama sekali
ELF-nya 1,5 KB mengedipkan GPIO 8 dengan laju yang diminta sketch, di engine sungguhan pada 1.00x

Empat kunjungan dalam satu profil browser hanya menghasilkan satu permintaan untuk clang.wasm, dan kunjungan kedua serta seterusnya melewati runtime sepenuhnya:

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

Sisa dari kunjungan ulang ada dua, dan keduanya bukan runtime: sekitar 0,7 detik untuk membaca 74 MB dari Cache API dan compileStreaming, dan sekitar 0,5 detik untuk pemakaian tool pertama pada modul yang baru dikompilasi, itu engine yang sedang menghangat; edit kedua dalam sesi yang sama adalah 51 ms di atas.

Panel build menampilkan persentase unduhan, setiap langkah dengan waktunya, dan satu baris di akhir: Built esp1.elf, 1.5 KB, 0.21 s.

Yang harus disajikan Worker

/toolchain/<version>/<file> harus berasal dari bucket R2 mokxi-toolchain (objek <version>/<file>), dengan Cache-Control yang panjang (path-nya berversi, jadi objeknya immutable) dan Content-Encoding: br untuk wasm. Responsnya butuh Content-Type: application/wasm dan Content-Length: progress bar panel membaca panjangnya, dan WebAssembly.compileStreaming menolak apa pun yang bukan application/wasm.

CMSIS dan HAL milik ST pada board STM32

Nucleo-F411RE, Black Pill, dan Blue Pill juga mengompilasi kode yang ditulis untuk header milik ST sendiri: kode register yang menyertakan stm32f4xx.h (atau stm32f1xx.h, atau stm32f10x.h yang lama) serta proyek STM32CubeIDE berbasis STM32Cube HAL. File ST disertakan di firmware/stm32cube/ (lihat README-nya untuk commit dan lisensi upstream) dan dikemas oleh web/scripts/bundle-stm32cube.mjs menjadi web/public/firmware/stm32cube/f4.json dan f1.json, sekitar 0,47 dan 0,40 MB dengan Brotli. Semuanya tidak ada dalam bundle runtime dan tidak dimuat saat pertama kali membuka editor: worker hanya mengambilnya saat sebuah proyek menyertakan salah satu header ST, atau main.h yang belum dimilikinya (wantsCube di src/compile/stm32cube.ts), dan menyimpannya selama halaman terbuka.

cubePlan memutuskan sisanya, dan projectPlan mengikutinya:

  • paket itu dipasang di /stm32cube, direktori include-nya masuk ke path, dengan -DSTM32F411xE atau -DSTM32F103xB, -DUSE_HAL_DRIVER saat HAL dipakai, -DUSE_FULL_LL_DRIVER saat LL dipakai, dan -DMOKXI_ST_CMSIS, yang membuat header board milik runtime sendiri tunduk pada milik ST di sebuah sketch;
  • modul HAL yang diaktifkan oleh stm32f?xx_hal_conf.h proyek, file LL yang diikutkan, dan file sistem dikompilasi dengan -w dan di-link sebagai anggota library, jadi build HAL pertama mengompilasi sekitar selusin file ST (9 sampai 15 detik pada wasm clang-v2 dalam pengujian) dan build berikutnya menggunakan ulang objeknya;
  • proyek dengan main()-nya sendiri di-link bare (bareMetalLinkInputs): kode startup runtime dan vector table apa adanya, setiap objek runtime lainnya jadi anggota library, dan mokxi_cube_bare.c meneruskan printf() lewat _write() atau __io_putchar() proyek. Sebuah sketch tetap memakai Arduino core, dan mokxi_cube_sketch.c menjadikan tick HAL sebagai millis();
  • apa pun yang kurang dari proyek yang ditempelkan ditulis dengan bawaan CubeIDE untuk board tersebut (main.h, konfigurasi HAL, handler SysTick, file MSP), file startup ST serta syscalls.c dan sysmem.c milik CubeIDE dibiarkan di luar, dan masing-masing menjadi catatan di log build (ProjectPlan.notes);
  • proyek yang memanggil peripheral yang tidak dimiliki chip simulasi (SPI, I2C, DMA, RTC, dan lainnya) mendapat catatan yang menjelaskannya; build tetap berhasil.

Chip yang disimulasikan tidak punya antarmuka flash, pengontrol daya, atau region bit-band, sementara HAL menulis ketiganya di HAL_Init() dan di setiap SystemClock_Config() CubeIDE. Pembuat pack menambahkan satu include ke header perangkat ST (mokxi_cube_regs.h: FLASH dan PWR menjadi RAM dengan layout yang sama) dan satu ke stm32f?xx_hal.h (mokxi_cube_hal.h: penulisan bit-band makro RCC menjadi penulisan register biasa); file vendor tidak diubah. src/compile/stm32cube.test.ts membuild dan menjalankan setiap contoh di firmware/stm32cube/examples/, dan /learn/stm32-hal-register-code adalah halamannya untuk pengguna.

Batasan

  • C, C++, dan assembly (.S dan .s, lihat di atas). Tidak ada MicroPython dan tidak ada bahasa lain: MicroPython milik Pico dan main.py milik Raspberry Pi menjalankan image firmware, bukan lewat jalur ini.
  • Proyek bersifat datar: nama file tidak memuat direktori, jadi include path hanya sedalam satu direktori.
  • Board yang string program-nya di katalog tidak menyebut family berarti tidak punya family sama sekali, jadi familyFor tidak menemukan apa pun dan board menjalankan ELF pra-build miliknya. Board yang family-nya belum ready melakukan hal yang sama, dengan note milik family ditampilkan di panel.
  • Kunjungan berikutnya tetap membayar sekitar 0,7 detik untuk mengambil kembali 74 MB dari Cache API dan mengompilasinya. compileStreaming dari sebuah Response yang di-cache adalah yang membuat engine memakai ulang code cache miliknya sendiri, tetapi tidak ada di sini yang bisa membuat itu pasti.
  • Dalam pengembangan, toolchain disajikan oleh Vite dari web/public/toolchain/; dalam produksi, Worker menyajikannya dari R2. worker/assets.ts sengaja menjawab 404 untuk /toolchain/, jadi middleware dev di web/vite.config.ts harus membiarkan prefix itu. Ia memang melakukannya, dan merusak hal itu adalah cara compiler bisa saja mengunduh halaman 404.

Pertanyaan

Di mana build terjadi?

Di mesinmu, di tab itu. Tidak ada server build, tidak ada antrean, dan tidak ada menit build.

Seberapa besar toolchain-nya?

Sekitar tujuh puluh megabyte. Toolchain terunduh sekali dan browser menyimpannya di cache, jadi setelah build pertama semuanya lokal.