Bir kartın dosyaları, sayfanın içinde WebAssembly olarak çalışan gerçek bir clang ve gerçek bir lld tarafından derlenir. Derleme sunucusu yoktur, hiçbir şey yüklenmez ve çıkan ELF, firmware/build.sh'in ürettiği görüntüyle aynı türdendir: aynı derleyici, aynı komut listesiyle çalışır.
Bunun işe yaradığının kanıtı ve bunu yapmayı haklı çıkaran sayılar proofs/compile/REPORT.md dosyasındadır. Bu belge ürünün bunu nasıl yaptığını anlatır.
Yapının biçimi
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
Derleme paneli dışındaki her şey worker'da çalışır, böylece dört saniyelik ilk derleme tuvalin tek karesini bile bloke etmez.
Tarayıcıya ulaşması gerekenler
İki şey, iki farklı yerden.
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, --check biçimini çalıştırır, yani firmware/ klasöründe kimsenin aktarmadığı bir değişiklik, bir kullanıcının derlemesi yerine test takımını başarısız kılar.
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.
Araç zinciri sürümü kart ailesine göre sabitlenir
Sürüm ailenin bir özelliğidir, uygulamanın değil, çünkü iki derleme tek bir derleyici değildir: clang-rv32-v1 yalnızca LLVM_TARGETS_TO_BUILD=RISCV ile yapılandırılmıştı, yani ESP32-C3 için derleyebilir ama Uno için fiziksel olarak derleyemez. clang-v2 ise aynı derleme betiğinin LLVM_TARGETS_TO_BUILD=RISCV;AVR;ARM halidir (aynı düzen, aynı kova, aynı URL biçimi) ve bugün derlenen her aile ona sabitlenmiştir (DECISIONS.md, 2026-09-14: üç arka uçta da doğrulandı ve R2'ye yüklendi). RISC-V çıktısı clang-rv32-v1 çıktısıyla bayt bayt aynıdır, yani ESP32-C3 de ona geçti ve bu kartların hepsi tek bir indirmeyi paylaşır. Xtensa aileleri clang-v3 sürümüne sabitlenmiştir (XTENSA_TOOLCHAIN), 2026-09-28'de yayımlandı:
| aile | katalog program |
hedef | araç zinciri | hazır |
|---|---|---|---|---|
esp32c3 |
elf32 riscv32imc |
riscv32-unknown-elf -march=rv32imc -mabi=ilp32 |
clang-v2 |
evet |
c6 |
elf32 riscv32imc esp32c6 |
riscv32-unknown-elf -march=rv32imc -mabi=ilp32 |
clang-v2 |
evet |
uno |
elf32 avr atmega328p |
avr -mmcu=atmega328p |
clang-v2 |
evet |
nano |
elf32 avr atmega328p nano |
avr -mmcu=atmega328p |
clang-v2 |
evet |
mega2560 |
elf32 avr atmega2560 |
avr -mmcu=atmega2560 |
clang-v2 |
evet |
leonardo |
elf32 avr atmega32u4 |
avr -mmcu=atmega32u4 |
clang-v2 |
evet |
attiny |
elf32 avr attiny85 |
avr -mmcu=attiny85 |
clang-v2 |
evet |
pico |
elf32 arm rp2040 |
thumbv6m-none-eabi -mcpu=cortex-m0plus -mthumb |
clang-v2 |
evet |
xiao |
elf32 arm samd21 |
thumbv6m-none-eabi -mcpu=cortex-m0plus -mthumb |
clang-v2 |
evet |
stm32 |
elf32 arm stm32f411 |
thumbv7em-none-eabi -mcpu=cortex-m4 -mthumb -mfloat-abi=soft -mfpu=none |
clang-v2 |
evet |
bluepill |
elf32 arm stm32f103 |
thumbv7m-none-eabi -mcpu=cortex-m3 -mthumb -mfloat-abi=soft |
clang-v2 |
evet |
microbit |
elf32 arm nrf52833 |
thumbv7em-none-eabi -mcpu=cortex-m4 -mthumb -mfloat-abi=soft -mfpu=none |
clang-v2 |
evet |
unor4 |
elf32 arm ra4m1 |
thumbv7em-none-eabi -mcpu=cortex-m4 -mthumb -mfloat-abi=soft -mfpu=none |
clang-v2 |
evet |
esp32 |
elf32 xtensa lx6 esp32 |
xtensa-esp-elf -mcpu=esp32 -fintegrated-as |
clang-v3 |
evet |
esp32s3 |
elf32 xtensa lx7 esp32s3 |
xtensa-esp-elf -mcpu=esp32s3 -fintegrated-as |
clang-v3 |
evet |
esp8266 |
elf32 xtensa lx106 esp8266 |
xtensa-esp-elf -mcpu=esp8266 -fintegrated-as |
clang-v3 |
evet |
Son üç satır bir sonraki bölümdür. web/src/compile/bundles.ts, bu tablonun okunduğu listedir ve bundles.test.ts bunları eşit tutar.
Xtensa kartları, clang-v3 üzerinde
Klasik ESP32 bir Xtensa LX6, ESP8266 NodeMCU bir Xtensa LX106 ve ESP32-S3 bir Xtensa LX7'dir. Üçü de 2026-09-28'den beri tarayıcıda clang-v3 ile derlenir (aşağıdaki "Yayımlandı ve kontrol edildi" bölümü). O tarihe kadar önceden derlenmiş ELF'ler çalıştırıyorlardı ve bunu söylüyorlardı. Bu bölümün geri kalanı bunun neden bir çatal gerektirdiği ve kanıtın neler bulduğudur.
Neden ayrı bir araç zinciri (27.09.2026'da kontrol edildi):
clang-v2, Xtensa arka ucuna sahip değil. Şununla derlendi:LLVM_TARGETS_TO_BUILD=RISCV;AVR;ARM(DECISIONS.md, 2026-09-14). Tarayıcının indirdiği wasm fiziksel olarak bir Xtensa nesnesi üretemez.- Yukarı akım LLVM gerekenin yarısına sahip, ve yanlış yarısına. Clang, LLVM 20'den beri bir Xtensa ön ucunu içinde taşır (Phoronix), ve LLVM 22'ninki
XtensaProcessors.tdbiliresp32veesp8266(yukarı akımmainekleresp32s2veesp32s3). Ama yukarı akımld.lld'da hiç Xtensa hedefi yok: hiçbir yerde yoklld/ELF/Arch/Xtensa.cppüzerindemainveya üzerinderelease/22.x, yani yukarı akımdan hiçbir şey bir ESP32 imajı bağlayamaz. Yukarı akım arka ucu ayrıca satır içi değişmez havuzları hâlâ şu konumda üretir:.text, bu şu hizada bozulmalara yol açarl32rhizası şu altında:-ffunction-sections(llvm/llvm-project#190204, açık). Xtensa hâlâ şurada deneyseldir:LLVM_ALL_EXPERIMENTAL_TARGETSyukarı akım. - Espressif's fork has all of it.
esp-clang(espressif/llvm-project, en yeniesp-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).
Yani bu eklenecek bir bayraktan çok izlenecek bir fork, ama fork Espressif'in kendi fork'u, birkaç ayda bir yayımlanıyor ve LLVM clang-v2'nin geldiği yerle aynı lisansa sahip.
Hazır ELF'ler hâlâ Espressif'in GCC'si ile derlenir; deploy/fetch-xtensa.sh bunu tools/xtensa/ dizinine koyar: LX6 için xtensa-esp32-elf-gcc 8.4.0, LX7 için xtensa-esp32s3-elf-gcc 8.4.0 ve LX106 için xtensa-lx106-elf-gcc 8.4.0. S3'ün çalışma zamanı, klasik ESP32'nin crt0.S ve support64.c dosyalarını yeniden kullanır: derleyicinin C'den ürettiği kod açısından LX7, LX6 ile aynıdır ve S3 derleyicisinin aynı test programı için ürettiği çıktı, ESP32 derleyicisinin çıktısıyla bayt bayt aynıdır. O dizin git tarafından yok sayılır. GCC GPL lisanslıdır ve burada derlediği hiçbir şey libgcc'e bağlanmaz (çalışma zamanları kendi support.c dosyalarıyla -nostdlib kullanır ve ESP8266'nın support32.c dosyası, LX106'nın komutu bulunmayan 32 bit bölmeleri sağlar), yani GPL kodu dağıtılan bir ELF'e ulaşmaz.
Yerel olarak kanıtlandı
Herhangi bir wasm var olmadan önce, derleyici tarafı aynı fork'un yerel Linux derlemesiyle kanıtlandı (clang-esp-22.1.4_20260825-x86_64-linux-gnu.tar.xz, 411 MB, sha256 4700ed4e...eb0a1, içinde ld.lld bulunan 2.7 GB'a açılıyor):
proofs/compile/xtensa/run-native.sh /some/scratch/dir
Bu yayımı indirir, ardından proofs/compile/xtensa/plan.ts --native dosyasını çalıştırır; bu betik hiçbir komutu elle yazmaz: runtimeSteps ve projectPlan değerlerini web/src/compile/toolchain.ts dosyasından ve depoya eklenmiş çalışma zamanı paketleri web/public/firmware/runtime/esp32.json, esp32s3.json ve esp8266.json dosyalarından alır; yani çalışan şey tarayıcının komut listesidir: crt0.S, ön işleme ve derleme yarımlarına bölünür, ld.lld doğrudan çağrılır, llvm-objcopy stdout'a yazar. 2026-09-27'deki sonuç:
- 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.lldher yer değiştirmeyi çözüyor (ESP32 nesnelerinde: 3.407 adetR_XTENSA_32ve 430 adetR_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. Bunlar GCC ELF'lerinin geçtiği aynı testlerdir: blink'in 500 ms'lik yarım periyodu, 1 kHz'de LEDC ve yazılımsal PWM, çekirdek saatine karşımillis(), UART0 bit aralığı, ADC, S3'ün RGB LED'indeki WS2812 kareleri (önce beyaz, sonra kablodaki ilk renk olarak gökkuşağı yeşili) ve USB seri paketleri, WiFi bağlantısı ve lambanın web sayfası. Üç ortam değişkeni yalnızca mevcut testleri başka bir dizine yönlendirir; oradaki bozuk bir dosya testlerin paniklemesine neden olur, yani gerçekten derlenen şeyi yüklediler.
Kanıtın bulduğu üç şey, hepsi paketlerde çözüldü:
-fintegrated-asgereklidir. Xtensa için Espressif sürücüsü varsayılan olarak bir.sdosyasını harici bir GNU derleyicisine (xtensa-esp32-elf-clang-as) verir; WASI bunu başlatamaz. Şununla:-fintegrated-asclang'ın kendi derleyicisi crt0.S dosyasını yazıldığı gibi alır. Bu, ailenin hedef bayraklarındadır, dolayısıyla derleme yarımı da onu alır. Espressif bunu girdi olarak assembly dosyalarında bilerek kapatır (EspBareMetal.cpp: "TODO: Add full support for Xtensa to integrated asm, LLVM-290, LLVM-291"), bu yüzden elle yazılmış her dosya için eksiksiz değildir; bizim ikicrt0.Sdosyamız için eksiksizdir ve simülatör testlerinin gösterdiği şey de budur. Ayrıca bir projenin kendi.Sve.sdosyalarının Xtensa kartlarında sunulmamasının nedeni de budur: orada yalnızca.c,.cppve.inoderlenir; buna karşılık diğer her aile projenin kendi dosyalarını da derler (aşağıda Assembly bölümüne bakın). C ve C++ bu fork'ta da upstream'deki gibi her zaman tümleşik derleyiciden geçer.- Wasm içinde multilib uyarısı yok. Yerel kurulum, esp8266 multilib'i olmadığı konusunda uyarır (
-Werroraltında hata sayılır), çünkümultilib.yamldosyasında böyle bir girdi yoktur.BareMetal::findMultilibsyalnızca var olan birmultilib.yamldosyasını okur ve wasm dosya sisteminde böyle bir dosya yoktur, dolayısıyla yalnızca yerel çalıştırmanın-Wno-missing-multilibbayrağına ihtiyacı vardır ve bu bayrağı yalnızcaplan.ts --nativegeçirir. - GCC'nin
-mlongcallsve-mtext-section-literalsbayrakları kalkar. Clang bunları-mlongcallskullanılmayan argüman olarak bildirir, bu da şu bayrak altında-Werrorhatadır. Olmadan clang-mtext-section-literalsbölümleri üretir; üç.literal.<function>dosyası da bunları zaten şunun başınalink.ldkoyar, yani.text, well insideL32R's 256 KB reach.
Kod boyutu, her örneğin çalıştırılabilir segmenti, gönderilen GCC imajıyla karşılaştırılıyor (aynı kaynaklar, ikisi de -Os):
| kart | GCC, tüm örnekler | clang | örnek başına |
|---|---|---|---|
| ESP32 | 29.984 bayt | 37.760 bayt | +%15 (fade) ile +%37 (wifilamp) arası, toplamda +%26 |
| ESP32-S3 | 41.584 bayt | 53.920 bayt | +%18 (fade) ile +%38 (wifilamp) arası, toplamda +%30 |
| ESP8266 | 34.592 bayt | 49.104 bayt | +%33 (button) ile +%49 (wifilamp) arası, toplamda +%42 |
Veri her iki yönde birkaç düzine bayt içinde. En büyük clang imajı, ESP8266'nın wifilamp'ı: 8.944 bayt kod, 32 KB IRAM ve elfcheck.py dosyasının örnekleri tuttuğu 24 KB sınırına karşı, yani büyüme buradaki bir kodun fark edeceği bir şeye mal olmuyor. Baytların nereye gittiği ayrıştırılmadı.
Yayımlandı ve doğrulandı
- Derlemeyi yapan:
.github/workflows/clang-v3.yml, çalıştırma 36358476287 (deneme 3,maindalında4578344f):espressif/llvm-project,esp-22.1.4_20260825sürümü,RISCV;AVR;ARM;Xtensahedefleriyle, her iki WASI yamasıyla, ardından üç kartın hepsi içinplan.ts --wasmve simülatörün testleri wasm ile derlenenler üzerinde çalıştırıldı. Artefaktclang-v3, zip'in sha256 değerief27b7aa…3eafd;clang.wasm80.735.841 bayt, sha2567546c54c07c392e231ea450f8e3aaa6680346ffeb08e13d97d970b26d88666e5. - Yayınlandı 2026-09-28: artefakt
web/public/toolchain/clang-v3/dizinine açıldı, ardındandeploy/fetch-toolchain.sh --publish clang-v3çalıştırıldı.https://mokxi.com/toolchain/clang-v3/adresiclang.wasm,bundle.jsonveinclude.tgzdosyalarını doğru türlerle, doğru uzunluklarla ve artefaktla aynı sha256 değerleriyle sunuyor.bundle.jsonbudanmamış (16 MB, tüm clang kaynak başlıkları); yalnızca/usr/includegirdileri kullanılıyor ve clang-v2'ninki gibi budanması bu indirmenin büyük kısmını kurtarırdı. - Chromium'da kontrol edildi (headless, yayınlanmış dosyalar
web/public/toolchain/clang-v3/içindeykennpm run dev'e karşı): gerçek düzenleyici kendi koduyla bir diyagram açtı, Çalıştır'a bastı ve derleme panelini, seri monitörü ve LED'i izledi. ESP32 kodu simüle edilmiş WiFi ağına katıldı (192.168.4.2) ve GPIO 4'ü yakıp söndürdü; ESP32-S3 kodu GPIO 2'yi yakıp söndürdü ve yazdı; ESP8266 kodu D1'i yakıp söndürdü ve her döngüde bir 32 bit bölme yazdı; ESP8266'nın kendi Blink örneği de düzenlendi, derlendi ve yandı söndü. Bir kartın ilk derlemesi çalışma zamanı dahil 5 ila 7 saniye sürdü, sonraki derleme yaklaşık 1,5 saniye. Sayfanın ESP8266'nın Blink'i için derlediği ELF, workflow'unproof/esp8266/blink.elfdosyasıyla bayt bayt aynı. - ESP8266 kontrolü bir motor hatası buldu, aynı değişiklikte düzeltildi. clang Blink, pinlerine, park ettiği dilim içinde yazıyor; dolayısıyla pinin ağı, çekirdeğin zaten çalıştırdığı zamanın içinde hareket ediyor ve kart parçası, park etmiş çekirdeği o dilimin sonundan önce ileri itiyordu.
CCOUNTgeriye gidiyordu, çalışma zamanının 64 bit çevrim sayacı bunu 2^32 çevrimlik bir sarmalama olarak okuyordu ve ilkdelay()'den sonraki her biri anında dönüyordu: LED yandı ve yanık kaldı. GCC'nin Blink'i park ettiği dilimde asla pin yazmıyor, bu yüzden yayınlanmış hiçbir örnek bunu göstermedi; yerel testler de göstermedi çünkü devresiz olarak SoC'yi çalıştırıyorlar. ESP32, ESP32-S3 ve ESP8266 kart parçaları artık çekirdeği, son diliminin bittiği yerden daha erken çalıştırmıyor (ran_to,crates/parts/src/parts/esp8266.rsve iki kardeşinde) veblink_keeps_its_half_period_when_a_pin_moves_as_the_core_parksbunu koruyor (clang ELF'lerini gösterecek şekildeMOKXI_ESP8266_ELF_DIRile çalıştır). - Kayan nokta, soft float'tır.
-mcpu=esp32ve-mcpu=esp32s3modelde bulunmayan tek duyarlıklı FPU'yu açar, bu yüzden başta birfloatçarpımı, karşılaştırması ya da DHT dersindekiisnan(h) || isnan(t)ifadesi bir FPU komutuna derleniyor ve kart duruyordu. Paketler artık-Xclang -target-feature -Xclang -fpgeçiriyor (Xtensa sürücüsünde-mfloat-abiyok), böylece float'lar her diğer soft-float kartta olduğu gibimokxi_float.ciçine çağrılara dönüşüyor ve doğru sonuçları veriyor. ESP8266'nın LX106'sında kapatılacak bir FPU yoktur ve aynımokxi_float.cdosyasını bağlar.
Sonraki adımlar
- Her ailenin clang-v3'e geçip geçmeyeceğine karar ver. Geçene kadar, bir ESP32 için ve başka bir kart için derleme yapan bir kullanıcı, Cache API'de 75 MB'ı aşan iki araç zinciri tutuyor:
isStaleKey(cache.ts), bir ailenin adlandırdığı her sürümü tutuyor (TOOLCHAINS_IN_USE) ve diğerini yalnızca disk doluyken düşürüyor. 2026-10-17'den önce kullanımdaki sürüm dışındaki her sürümü düşürüyordu, bu yüzden her geçiş 20 MB'ı yeniden indiriyordu ve çevrimdışında başarısız oluyordu. Hepsini taşımak, clang-v2'ye taşımada olduğu gibi aile başına bir dizi, ama bu 22.1.0 değil bir fork'tan gelen LLVM 22.1.4, o yüzden önce ona karşıcrash.test.tsve hazır kütüphane testlerini çalıştır ve bayt özdeş çıktı varsayma. - Hazır kütüphaneleri Xtensa ailelerinde kontrol et.
firmware/libdiğer tüm kartlarda olduğu gibi onların include yolunda, amastock-libraries.test.tsonları listelemiyor, yaniServo.h,Wire.hve diğerleri orada test edilmemiş. bundle.jsondosyasını budayın freestanding bir derlemenin açtığı başlıklara.
Çalışmayan bir tarayıcı içi derlemeyi asla iddia etme: sessizce dünün ikili dosyasını çalıştıran bir derleme düğmesi, bu üründeki en kötü şey olurdu.
clang-rv32-v1 hâlâ RV32_TOOLCHAIN değeridir ve hiçbir aile onu adlandırmıyor. Geri dönüş yolu olarak kalıyor: URL'ler, modül önbellek anahtarı ve çalışma zamanı nesne önbelleği ona bağlı olduğundan, bir ailenin toolchain dizisini değiştirmek, bir derlemeyi yayınlamanın ya da geri almanın tamamıdır.
ready de ölü kod değil. Bir ailenin onu taşıyabilmesi için iki şeyin doğru olması gerekiyor ve bundles.test.ts ikincisini kontrol ediyor:
- Araç zincirinde arka uç var, yayınlanmış ve onunla derlenen bir kod simülatörde çalışmış.
- Ailenin bir çalışma zamanı paketi var, yani firmware dizini mevcut ve
bundle-runtime.mjsçalıştırılmış.
ready olmayan bir aile hata değildir: chooseProgram, kartlarını web/public/firmware/ içindeki önceden derlenmiş ELF'ye gönderir, derleme paneli ve kart seçicinin yanındaki satır nedenini söyler ve hiçbir şey başarısız olmaz. Bugün bu yolu kullanan aile yok; Xtensa aileleri clang-v3 yayınlanana kadar kullanıyordu.
STM32 ve micro:bit kasıtlı olarak soft float: DECISIONS.md, 2026-09-14, bir M4F kartı istenene kadar FPU'yu ve M4 DSP'yi kapsam dışı bırakıyor, dolayısıyla hiçbir çalışma zamanı VFP komutları ya da hard-float ABI yaymamalı.
Çalıştır'a bastığında ne olur
App.buildPrograms, chooseProgram'a (src/compile/client.ts) her kart için sorar ve üç cevaptan birini alır:
elf: Firmware panelinin adlandırdığı imajı çalıştır ve hiçbir şey derleme. Yüklenmiş bir ELF bu dosyalardan derlenmemiştir; dokunulmamış bir hazır örnek zaten derlidir. Araç zinciri yayınlanmamış bir aile de buraya düşer.reuse: tam olarak bu dosyalardan derlenmiş ELF'i çalıştır. Karar, her dosya adının ve içindeki her baytın bir özetidir, yani bir tuş vuruşu ve bir geri alma seni yinereuse.build: derle ve sonucu çalıştır.
Başarısız olan bir derleme çalıştırmayı durdurur: düğme Çalıştır üzerinde kalır, önceki ELF sessizce kullanılmak yerine düşürülür ve tanılar panelde kalır. Derlenen ELF yalnızca oturum süresince bellekte yaşar. Bu oturum hakkında bir gerçektir, belgenin parçası değildir, bu yüzden asla kaydedilmez, dışa aktarılmaz veya paylaşılmaz.
Komut listesi
firmware/build.sh dosyasının çalıştırdığı aynı on dört komut, WASI'nin zorladığı iki farkla (ikisi de kanıtta çözüldü):
-c crt0.S, clang'ın iki iş istemesine yol açıyor, bir ön işlem ve bir derleme, ve clang birden fazla iş olduğu anda tümleşik cc1'ini kapatıyor, bu da WASI üzerinde "unable to execute command: WASI does not support spawning subprocesses" hatası veriyor. İki yarı ayrı ayrı listeleniyor.- Bağlantı, clang sürücüsü üzerinden değil doğrudan
ld.lldüzerinden geçer, bu yüzden ESP32-C3 bağlantı bayrakları-Wl,öneklerini kaybeder.firmware/uno/build.shaynı nedenden ötürü zatenld.lldçağırır.
Araçların gördüğü dosya sistemi:
| yol | ne |
|---|---|
/usr/include |
clang'ın kaynak başlık dosyaları, araç zinciri paketinden |
ESP32-C3 için /firmware, geri kalanlar için /firmware/<family> |
çalışma zamanı kaynaklarımız, başlık dosyaları, crt0.S, link.ld |
/firmware/lib |
yalnızca başlık dosyalarından oluşan paylaşılan sürücüler, her aile için aynı yol |
/project |
kartın dosyaları, kendi adları altında, böylece #include "pins.h" çalışır |
/build |
nesne dosyaları, sarmalanmış kod, ELF |
Assembly
Bir projenin kendi .S ve .s dosyaları da burada derlenir, çünkü arduino-cli bir kodun yanında bir .S derler ve bir kart yalnızca assembly'den oluşabilir.
Dört parça, hepsi web/src/compile/ içinde:
- Plan.
projectPlan(toolchain.ts) her.Sdosyası için bir adım çifti ekler: kodun kendi include yolu, tırnak yolu ve tanımlarıyla bir ön işlem (böylece#include <avr/io.h>kayıt adlarını verir ve__ASSEMBLER__ayarlanır), ardından ön işlenmiş kopyanın bir derlemesi. İki çalıştırma olmasının nedeniniruntimeStepszaten açıklıyor:-c foo.Sclang'in iki iş istemesine neden olur ve clang, birden fazla iş olduğunda entegre cc1'ini kapatır; bu da WASI üzerinde "unable to execute command: WASI does not support spawning subprocesses" hatası verir. Bir.sdosyası, ön işlem adımı olmadan doğrudan derlenir. Ön işlemcinin# <line> "<file>"işaretleri taşınır, böylece bir tanılama ve bir DWARF satırı, ön işlenmiş kopyanın satırı değil sekmenin kendi satırı olur; hata ayıklayıcının bir.Ssatırında kesme noktası koyabilmesini sağlayan da budur. Derleme adımı yalnızca derleyicinin kendisinin okuduğu bayrakları, artı-g -gdwarf-4geçirir. - İşlenen denetimleri.
asm-check.ts, herhangi bir araç çalışmadan önce projenin tüm AVR.Sve.sdosyalarını okur ve clang'ın kendifile:line:col: error:biçiminde bildirir, böyleceparseDiagnosticsve Derleme panelinin yeni bir şey bilmesi gerekmez.avr-as'ın yaptığı ama LLVM'in AVR birleştiricisinin sessizce yapmadığı denetimleri yapar:ldi r16, 300(0x2C olarak tutulur),sbi PORTB, 1(bir I/O adresinin gerektiği yerde bir veri adresi),add r16, 5(add r16, r5olarak okunur),__SFR_OFFSET 0olmadanout PORTB, r16(bir uyarı: farklı bir kayda ulaşır), 63'ü geçeninveout, 63'ü geçensbiwveadiw, ve 7'yi geçen bir bit. Bir işlenen yalnızca çözülebiliyorsa yargılanır: sayılar, dosyanın kendi.equ,.setve#definetanımları, ve çalışma zamanı paketinden okunan kart başlığının kayıt ve bit adları,_SFR_IO_ADDR(),lo8(),hi8()ve C işleçleri üzerinden. Gerisi birleştiriciye ve bağlayıcıya bırakılır, onlar da bu konularda doğruyu söyler. Bir hata, bir araç başlamadan derlemeyi durdurur (plan.checkFailed). - Kod olmadan bağlama.
isAssemblyProject(bundles.ts), dosyaları yalnızca assembly olan projedir;assemblyLinkInputs, kendi nesnelerinin yanı sıra neyin bağlanacağını söyler. Bir AVR kartında bu, çalışma zamanınıncrt0.Snesnesidir ve başka hiçbir şey değildir; bu da avr-libc'ingcrt1.odosyasınınavr-gcc main.Skarşısındaki rolüdür: her__vector_<n>'in zayıf birretiolduğu vektör tablosu,r1temizlenmiş, yığın RAMEND'de,.datakopyalanmış,.bsstemizlenmiş ve projeninmainişlevine bir çağrı. Dosyası kendi.vectorsbölümünü ya da__vectorsetiketini tanımlayan bir proje (definesVectors) hiçbir şey almaz; dosyanın kendisinin vektör tablosu olduğu her ARM kartı da almaz. İki durumda da Arduino çekirdeği yoktur:setup()yok,millis()tikleri yok,Serialyok. - Sökücü.
disasm.tsbizim yazdığımızdır, çünkü tarayıcının LLVM'i clang,ld.lldvellvm-objcopytaşır amallvm-objdumptaşımaz. Uygulamanın zaten tuttuğu ELF'in çalıştırılabilir bölümlerini okur, böylece Hata ayıklama sekmesinin Disassembly listesi ve Step instruction düğmesi bir gidiş dönüş gerektirmez. AVR çözücüsü tüm komut setini kapsar; Thumb çözücüsü tüm 16-bit kodlamaları,BLve bir derleyicinin ya da bir dersin en çok yazdığı 32-bit Thumb-2 biçimlerini kapsar, kalan her şeyi yanlış bir tahmin yerine.inst.w 0x…olarak gösterir. Metinllvm-objdump'ınkidir vedisasm.test.tsonu orada tutar: Uno, Mega, Pico ve Black Pill için gerçek derlemelerin (dört assembly başlangıç projesi ve kayan nokta matematiği,Serialve pinler içeren bir kod) her komutu, makinenin kendillvm-objdump'ının okuduğu gibi tam olarak okunmak zorundadır.
Çekirdeksiz bir assembly projesi sunan kartlar src/asm/boards.ts dosyasındadır: Uno, Nano, Pro Mini, Pico ve STM32F411. Derlenen diğer her kart, Xtensa kartlar dışında (yukarıya bakın), bir kodun yanında .S sekmeleri alabilir. asm.test.ts bunların tümünü simülatörde derleyip çalıştırır.
Tuzak atan bir araç
clang ve lld, bazı ölümcül hatalarda (başlıca eksik bir #include) bir abort yoluna girer: tanılamayı stderr'e yazdırır ve exit çağırmak yerine unreachable'e takılır. WASI içinde bu, gerçek bir WebAssembly.RuntimeError olarak ortaya çıkar, bir proc_exit olarak değil ve başka türlü yakalanmamış bir red olarak, ona bağlı hiçbir tanılama olmadan kaçardı: bir derleme hatası değil, bir çökme.
Toolchain.run (src/compile/toolchain.ts) tam olarak bunu yakalar: araç stderr'e zaten bir şey yazdıktan sonra gelen bir tuzak, sıradan bir başarısız adım olarak döner, result.trapped ayarlanmış ve result.code sıfır değil, tuzaktan önce yazılan her şey hâlâ result.err içinde. runSteps (src/compile/worker.ts) bunu sonra sıradan bir sıfır olmayan çıkış gibi ele alır: parseDiagnostics'ın bulduğu neyse derleme paneli onu gösterir, her diğer tanılama gibi tıklanabilir, ve yalnızca tuzak söyleyecek bir şey taşımadığında "derleyici çöktü (<tool>, <step> adımında)" ifadesine geri düşer. Her araç çalıştırması, derlenmiş tek Module'den kendi temiz WebAssembly.Instance'ını zaten alır (toolchainFor modülü bir kez derler; Toolchain.run her çağrıda onu örnekler), bu yüzden bir çalıştırmadaki tuzak sonraki çalıştırma için geride bırakacak bir şey bulamaz. Zehirleyecek bir örnek yoktur ve buradaki hiçbir şey modülü kendisi yeniden örneklemez.
.ino sekmeleri Arduino IDE'nin yaptığı gibi birleştirilip sarılır (src/compile/prototypes.ts): önce #include "arduino.h", sonra ana sekme ve diğer .ino sekmeleri alfabetik olarak, her birinin önünde #line 1 "<tab>.ino", ve sekmelerin tanımladığı her fonksiyon için, ilk fonksiyonun hemen önüne yazılan bir prototip, her birinin önünde tanımını işaret eden bir #line, bloğun sonunda ise bir #line. Böylece loop()'un altında tanımlanan bir fonksiyonu çağıran bir kod derlenir ve derleyici yine de sorunu sketch.ino:12:3 olarak bildirir, böylece derleme paneli düzenleyiciyi oraya götürebilir. Şablonlar, sınıf üyeleri, bir isim alanındaki her şey, kodun kendisinin bildirdiği bir fonksiyon ve imzasında daha aşağıda bildirilen bir şeyi adlandıran bir fonksiyon prototip almaz; #if blokları içindeki bir fonksiyon, prototipini aynı koşulların bir kopyası içinde alır; varsayılan argümanlar prototipe taşınır ve tanımdan, kolon kolon, silinir. .c C11 olarak, .cpp/.cc/.ino C++17 olarak derlenir; başka her şey include'lar için /project içine yazılır ve derlenmez.
Kullanıcının dosyaları, çalışma zamanının uyarı bayrakları eksi -Werror ile derlenir (userWarnings, bundles.ts içinde): -Wall -Wextra uyarıları derleme panelinde bildirilir ve önbelleğe alınan bir nesne dosyası uyarılarını korur, böylece sonraki Çalıştır'da tekrar gösterilirler; ancak Arduino IDE'deki gibi bir uyarı derlemeyi durdurmaz. Çalışma zamanının kendisi ve projectPlan(..., { strict: true }) (Xtensa kanıtı, hazır kütüphane ve iletişim modülü testleri) -Werror'u korur; Mokxi'nin kendi kodunu ve örneklerini uyarısız temiz tutan da budur.
Neyin önbelleğe alındığı ve nerede
| ne | nerede | anahtar | ne zaman kaybolur |
|---|---|---|---|
clang.wasm baytları |
Cache API, mokxi-toolchain-v1 |
/toolchain/<version>/clang.wasm |
hiçbir aile o sürümü artık kullanmıyor, disk dolu, depolama temizleniyor |
| çalışma zamanının nesne dosyaları | Cache API, aynı depo | /toolchain/<version>/runtime/<family>-<bundle hash>.objects |
sürüm değişiyor, firmware değişiyor, depolama temizleniyor |
derlenmiş WebAssembly.Module |
worker, bellekte | toolchain sürümü | sayfa kapanıyor |
| çalışma zamanının nesne dosyaları | worker, bellekte | toolchain sürümü + aile | sayfa kapanıyor |
| her proje kaynağının nesne dosyası | worker, bellekte | kaynak metin + tam komut | sayfa kapanıyor |
| derlenmiş ELF | uygulama, bellekte | kart kimliği + dosya imzası | sayfa kapanıyor |
Çalışma zamanı nesneleri, her biri birkaç kilobaytlık bir düzine dosyadır ve bir düzine girdi yerine tek bir önbellek girdisine paketlenir (MOKO, bir başlık uzunluğu, [path, length] çiftlerinden oluşan bir JSON indeksi, sonra baytlar uç uca), böylece bir isabet, her birinden on iki yerine tek bir match ve tek bir arrayBuffer demektir. Anahtar, çalışma zamanı paketinin tam getirildiği haliyle bir karmasını taşır; içindeki her kaynak, başlık dosyası ve bayrak, bu yüzden firmware/src/gpio.c dosyasını düzenleyip yeniden üretmek, bayat bir nesne dosyası yerine farklı bir anahtar üretir. Açılamayan her şey silinir ve yeniden derlenir, çünkü okuyamadığımız bir blob, hiç blob olmamasından daha kötüdür.
Artık erişilemeyen her şey yol geçerken gider: eski bir toolchain'in her girdisi ve kaynakları ilerlemiş bir ailenin çalışma zamanı. Bu sayfanın hiçbir şey söylemediği bir aile olduğu gibi bırakılır: önbelleğe alınmış bir Uno çalışma zamanı olan ve bugününü ESP32-C3 üzerinde geçiren bir kullanıcı onu korur.
Bunun her parçası kademeli olarak bozulur: Cache API yokluğu, hata fırlatan bir önbellek, kotaya çarpan bir put: her biri "işi yeniden yap" demektir, asla "derleyici yok" değil.
Ölçülen değerler
Derleme konteynerinde Chromium 141 ile, geri döngü üzerindeki npm run dev'e karşı (clang.wasm'ı sıkıştırılmamış sunar, yani indirme kötümser durumdur; üretimde R2'den Content-Encoding: br ile sunulur):
| tıklamadan çalışmaya | ne yaptığı | |
|---|---|---|
| ilk derleme, soğuk | 6.1 ile 7.8 s | 74 MB indirme, WebAssembly.compile, 12 çalışma zamanı nesnesi, kod, bağlama, strip |
| ikinci ve sonraki ziyaretler | 1.5 ile 1.8 s | clang.wasm isteği yok; çalışma zamanı Cache API'den 3 ile 9 ms'de çıkar |
| düzenle ve aynı oturumda yeniden Çalıştır | 0.21 s | sketch.ino 51 ms, link 10 ms, strip 5 ms |
| düzenlemeden Çalıştır | hiç derleme yok | |
| ELF | 1.5 KB | GPIO 8'i kodun istediği hızda yakıp söndürür, gerçek motorda 1.00x |
Tek bir tarayıcı profilinde dört ziyaret, clang.wasm için tek bir istek yaptı ve ikinci ve sonraki her ziyaret çalışma zamanını tamamen atladı:
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
Bir geri dönüş ziyaretinden geriye iki şey kalır, hiçbiri çalışma zamanı değildir: 74 MB'ı Cache API'den geri okumak ve compileStreaming ile derlemek için yaklaşık 0.7 s ve yeni derlenmiş bir modüldeki ilk tool çalıştırması için yaklaşık 0.5 s; bu da motorun ısınmasıdır. Aynı oturumdaki ikinci düzenleme yukarıdaki 51 ms'dir.
Derleme paneli indirme yüzdesini, her adımı zamanlamasıyla ve sonda tek bir satırı gösterir: Built esp1.elf, 1.5 KB, 0.21 s.
Worker'ın sunması gerekenler
/toolchain/<version>/<file>, mokxi-toolchain R2 kovasından gelmelidir (nesneler <version>/<file>), uzun bir Cache-Control ile (yol sürümlüdür, yani nesneler değişmezdir) ve wasm için Content-Encoding: br ile. Yanıtın Content-Type: application/wasm ve bir Content-Length taşıması gerekir: panelin ilerleme çubuğu uzunluğu okur ve WebAssembly.compileStreaming, application/wasm olmayan her şeyi reddeder.
STM32 kartlarında ST'nin CMSIS'i ve HAL'ı
Nucleo-F411RE, Black Pill ve Blue Pill ayrıca ST'nin kendi başlık dosyaları için yazılan kodları da derler: stm32f4xx.h (veya stm32f1xx.h, ya da eski stm32f10x.h) içeren register kodu ve STM32Cube HAL üzerindeki STM32CubeIDE projeleri. ST'nin dosyaları firmware/stm32cube/ klasöründe tutulur (yukarı akış commit'leri ve lisanslar için oradaki README dosyasına bak) ve web/scripts/bundle-stm32cube.mjs tarafından web/public/firmware/stm32cube/f4.json ve f1.json dosyalarına paketlenir; Brotli ile sıkıştırılmış boyutları yaklaşık 0.47 ve 0.40 MB'dir. Bunlar runtime paketlerinde bulunmaz ve düzenleyicinin ilk yüklemesinde gelmez: worker, yalnızca bir proje ST'nin başlık dosyalarından birini ya da elinde olmayan bir main.h içerdiğinde bir tanesini indirir (src/compile/stm32cube.ts içindeki wantsCube) ve sayfa süresince bellekte tutar.
cubePlan gerisini kararlaştırır ve projectPlan onu izler:
- paket
/stm32cubeyoluna bağlanır, include dizinleri yola eklenir,-DSTM32F411xEya da-DSTM32F103xBile, HAL kullanıldığında-DUSE_HAL_DRIVER, LL kullanıldığında-DUSE_FULL_LL_DRIVERve-DMOKXI_ST_CMSIS, bu da çalışma zamanının kendi kart başlığının bir kod içinde ST'ninkine boyun eğmesini sağlar; - projenin
stm32f?xx_hal_conf.hdosyasının etkinleştirdiği HAL modülleri, içerdiği LL dosyaları ve sistem dosyası-wile derlenir ve kütüphane üyeleri olarak bağlanır; böylece ilk HAL derlemesi ST'nin yaklaşık bir düzine dosyasını derler (testlerde clang-v2'nin wasm'ında 9 ila 15 saniye) ve sonraki derleme onların nesnelerini yeniden kullanır; - kendi
main()fonksiyonuna sahip bir proje çıplak bağlanır (bareMetalLinkInputs): çalışma zamanının başlangıç kodu ve vektör tablosu olduğu gibi, diğer her çalışma zamanı nesnesi bir kütüphane üyesi olarak, vemokxi_cube_bare.cprintf()fonksiyonunu projenin_write()veya__io_putchar()fonksiyonuna yönlendirir. Bir kod Arduino çekirdeğini korur vemokxi_cube_sketch.cHAL'in tikinimillis()yapar; - yapıştırılan bir projede eksik olan her şey kart için CubeIDE'nin varsayılanlarıyla yazılır (
main.h, HAL yapılandırması, SysTick işleyicisi, bir MSP dosyası), ST'nin başlangıç dosyası ile CubeIDE'ninsyscalls.cvesysmem.cdosyaları dışarıda bırakılır ve bunların her biri derleme günlüğünde bir not olur (ProjectPlan.notes); - simüle edilen çipte bulunmayan bir çevre birimini (SPI, I2C, DMA, RTC ve diğerleri) çağıran bir proje bunu belirten bir not alır; derleme yine de başarılı olur.
Simüle edilen çiplerde flash arayüzü, güç denetleyicisi veya bit-band bölgesi yoktur ve HAL bu üçüne de HAL_Init() içinde ve her CubeIDE SystemClock_Config() içinde yazar. Paket oluşturucu ST'nin aygıt başlığına bir include ekler (mokxi_cube_regs.h: FLASH ve PWR aynı düzende RAM olur) ve stm32f?xx_hal.h dosyasına bir tane daha (mokxi_cube_hal.h: RCC makrolarının bit-band yazımları sıradan yazmaç yazımlarına dönüşür); satıcıdan gelen dosyalar değişmez. src/compile/stm32cube.test.ts dosyası firmware/stm32cube/examples/ içindeki her örneği derler ve çalıştırır, kullanıcılar için sayfa ise /learn/stm32-hal-register-code adresidir.
Sınırlar
- C, C++ ve assembly (
.Sve.s, yukarıya bakın). MicroPython yok ve başka bir dil de yok: Pico'nun MicroPython'u ve bir Raspberry Pi'ninmain.pydosyası bu yoldan geçmek yerine bir firmware imajı çalıştırır. - Bir proje düzdür: dosya adlarında dizin yoktur, dolayısıyla include yolu tek dizin derinliğindedir.
- Kataloğundaki
programdizgesi bir aile adı içermeyen kartın hiç ailesi yoktur, bu yüzdenfamilyForhiçbir şey bulamaz ve kart önceden derlenmiş ELF'ini çalıştırır. Ailesireadyolmayan kart da aynı şeyi yapar; panelde aileninnotedeğeri gösterilir. - Yeniden bir ziyarette de 74 MB'ı Cache API'den geri almak ve derlemek yaklaşık 0,7 saniye sürer. Önbelleğe alınmış bir
ResponseüzerindencompileStreaming, motorun kendi kod önbelleğini yeniden kullanmasını sağlayan şeydir; ama buradaki hiçbir şey bunu kesin kılamaz. - Geliştirme sırasında araç zincirini Vite
web/public/toolchain/dizininden sunar; üretimde Worker onu R2'den sunar.worker/assets.tsdosyası/toolchain/için bilerek 404 yanıtı verir, dolayısıylaweb/vite.config.tsiçindeki geliştirme arakatmanı o öneki olduğu gibi bırakmak zorundadır. Bırakır ve bunu bozmak, derleyicinin sonunda 404 sayfasını indirmesine yol açar.