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):
clang-v2tidak punya back end Xtensa. Ia dibangun denganLLVM_TARGETS_TO_BUILD=RISCV;AVR;ARM(DECISIONS.md, 2026-09-14). Wasm yang diunduh browser secara fisik tidak bisa menghasilkan objek Xtensa.- 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.tdyang tahuesp32danesp8266(upstreammainmenambahkanesp32s2danesp32s3). Tapild.lldupstream tidak punya target Xtensa sama sekali: tidak adalld/ELF/Arch/Xtensa.cppdimainatau direlease/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 merusakl32ralignment di bawah-ffunction-sections(llvm/llvm-project#190204, masih terbuka). Xtensa masih dalam tahapLLVM_ALL_EXPERIMENTAL_TARGETSupstream. - Espressif's fork has all of it.
esp-clang(espressif/llvm-project, terbaruesp-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).
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,rainbowandusbserialincluded) and nine for the ESP8266 (20 steps), about 1 s each natively; ld.lldmenyelesaikan setiap relokasi (pada objek ESP32: 3,407R_XTENSA_32dan 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. 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-asdiperlukan. Untuk Xtensa, driver Espressif menyerahkan sebuah.sfile ke assembler GNU eksternal (xtensa-esp32-elf-clang-as) secara default, yang tidak bisa di-spawn oleh WASI. Dengan-fintegrated-asassembler 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 filecrt0.Skita, ia lengkap, itulah yang ditunjukkan test simulator. Ini juga alasan file.Sdan.smilik proyek sendiri tidak ditawarkan di board Xtensa: hanya.c,.cppdan.inoyang 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) karenamultilib.yaml-nya tidak punya entri itu.BareMetal::findMultilibshanya membacamultilib.yamlyang ada, dan filesystem wasm tidak punya satu pun, jadi hanya run native yang butuh-Wno-missing-multilib, dan hanyaplan.ts --nativeyang memberikannya. - GCC punya
-mlongcallsdan-mtext-section-literalsyang perlu dilepas. Clang melaporkan-mlongcallssebagai argumen tak terpakai, error di bawah-Werror. Tanpa-mtext-section-literalsclang memancarkan.literal.<function>section, yang ketiga filelink.ldsudah menaruhnya di awal.text, well insideL32R'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
- Dibangun oleh
.github/workflows/clang-v3.yml, run 36358476287 (percobaan ke-3,maindi4578344f):espressif/llvm-projectdiesp-22.1.4_20260825denganRISCV;AVR;ARM;Xtensa, kedua patch WASI, laluplan.ts --wasmuntuk ketiga board dan test simulator pada hasil build wasm. Artifactclang-v3, sha256 zip-nyaef27b7aa…3eafd;clang.wasmberukuran 80,735,841 byte, sha2567546c54c07c392e231ea450f8e3aaa6680346ffeb08e13d97d970b26d88666e5. - Dipublikasikan 2026-09-28: artifact di-unzip ke
web/public/toolchain/clang-v3/, laludeploy/fetch-toolchain.sh --publish clang-v3.https://mokxi.com/toolchain/clang-v3/menyajikanclang.wasm,bundle.jsondaninclude.tgzdengan tipe yang benar, panjang yang benar, dan sha256 yang sama dengan artifact.bundle.jsonitu 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. - Dicek di Chromium (headless, terhadap
npm run devdengan file yang dipublikasikan diweb/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 denganproof/esp8266/blink.elfmilik workflow. - 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.
CCOUNTberjalan mundur, penghitung siklus 64-bit runtime membacanya sebagai wrap 2^32 siklus, dan setiapdelay()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_todicrates/parts/src/parts/esp8266.rsdan dua saudaranya), danblink_keeps_its_half_period_when_a_pin_moves_as_the_core_parksmenjaganya (jalankan denganMOKXI_ESP8266_ELF_DIRmenunjuk ke ELF clang). - Floating point menggunakan soft float.
-mcpu=esp32dan-mcpu=esp32s3mengaktifkan FPU presisi tunggal, yang tidak dimiliki oleh model, sehingga awalnya perkalianfloat, perbandingan, atau kodeisnan(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 kemokxi_float.cseperti di board soft float lainnya dan memberikan hasil yang benar. LX106 milik ESP8266 tidak punya FPU untuk dimatikan dan me-linkmokxi_float.cyang sama.
Langkah berikutnya
- 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 jalankancrash.test.tsdan tes library bawaan terhadapnya dulu, dan jangan asumsikan outputnya identik byte per byte. - Periksa library bawaan di family Xtensa.
firmware/libada di include path mereka seperti di setiap board, tapistock-libraries.test.tstidak mencantumkannya, jadiServo.h,Wire.hdan sisanya belum diuji di sana. - Pangkas
bundle.jsonhanya 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:
- Toolchain punya back end, sudah dipublikasikan, dan sketch yang di-buildnya sudah berjalan di simulator.
- Family punya bundle runtime, artinya direktori firmwarenya ada dan
bundle-runtime.mjssudah 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 kereuse.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):
-c crt0.Smembuat 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.- Link dilakukan lewat
ld.lldlangsung, bukan lewat driver clang, jadi flag link ESP32-C3 kehilangan awalan-Wl,-nya.firmware/uno/build.shsudah memanggilld.llddengan 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/:
- 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 diberikanruntimeSteps:-c foo.Smembuat 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.sdirakit 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. - Pemeriksaan operand.
asm-check.tsmembaca setiap file AVR.Sdan.sproyek sebelum alat apa pun berjalan, dan melaporkan dalam formatfile:line:col: error:milik clang sendiri sehinggaparseDiagnosticsdan panel Build tidak perlu tahu hal baru. Pemeriksaan ini melakukan pemeriksaan yang dilakukanavr-asdan 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 sebagaiadd r16, r5),out PORTB, r16tanpa__SFR_OFFSET 0(sebuah peringatan: ini menuju register yang berbeda),indanoutmelewati 63,sbiwdanadiwmelewati 63, dan bit melewati 7. Sebuah operand hanya dinilai bila nilainya bisa dihitung: angka,.equmilik file itu sendiri,.setdan#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). - Link, saat tidak ada sketch.
isAssemblyProject(bundles.ts) adalah proyek yang file-nya hanya berisi assembly;assemblyLinkInputsmenentukan apa yang di-link selain objek miliknya sendiri. Di board AVR itu adalah objekcrt0.Smilik runtime dan tidak ada yang lain, yaitu apa yang menjadigcrt1.omilik avr-libc bagiavr-gcc main.S: tabel vektor dengan setiap__vector_<n>sebagairetilemah,r1dikosongkan, stack di RAMEND,.datadisalin,.bssdikosongkan, dan pemanggilanmainmilik proyek. Proyek yang file-nya mendefinisikan section.vectorsatau label__vectorssendiri (definesVectors) tidak mendapatkannya, begitu juga setiap board ARM, di mana file-nya adalah tabel vektor. Tidak ada Arduino core di kedua kasus: tidak adasetup(), tidak ada tickmillis(), tidak adaSerial. - Disassembler.
disasm.tsbuatan kami, karena LLVM di browser membawa clang,ld.llddanllvm-objcopydan tidak adallvm-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 formatllvm-objdump, dandisasm.test.tsmenjaganya tetap begitu: setiap instruksi dari build nyata (empat starter assembly, dan sebuah sketch dengan matematika floating-point,Serialdan pin) untuk Uno, Mega, Pico dan Black Pill harus terbaca persis sepertillvm-objdumpmesin 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-DSTM32F411xEatau-DSTM32F103xB,-DUSE_HAL_DRIVERsaat HAL dipakai,-DUSE_FULL_LL_DRIVERsaat 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.hproyek, file LL yang diikutkan, dan file sistem dikompilasi dengan-wdan 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, danmokxi_cube_bare.cmeneruskanprintf()lewat_write()atau__io_putchar()proyek. Sebuah sketch tetap memakai Arduino core, danmokxi_cube_sketch.cmenjadikan tick HAL sebagaimillis(); - 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 sertasyscalls.cdansysmem.cmilik 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 (
.Sdan.s, lihat di atas). Tidak ada MicroPython dan tidak ada bahasa lain: MicroPython milik Pico danmain.pymilik 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, jadifamilyFortidak menemukan apa pun dan board menjalankan ELF pra-build miliknya. Board yang family-nya belumreadymelakukan hal yang sama, dengannotemilik family ditampilkan di panel. - Kunjungan berikutnya tetap membayar sekitar 0,7 detik untuk mengambil kembali 74 MB dari Cache API dan mengompilasinya.
compileStreamingdari sebuahResponseyang 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.tssengaja menjawab 404 untuk/toolchain/, jadi middleware dev diweb/vite.config.tsharus membiarkan prefix itu. Ia memang melakukannya, dan merusak hal itu adalah cara compiler bisa saja mengunduh halaman 404.