Başvuru

Tarayıcıda kod derlemek

Hiçbir yerde derleme sunucusu olmadan bir kodun firmware'e nasıl dönüştüğü.

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):

  1. 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.
  2. 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.td bilir esp32 ve esp8266 (yukarı akım main ekler esp32s2 ve esp32s3). Ama yukarı akım ld.lld'da hiç Xtensa hedefi yok: hiçbir yerde yok lld/ELF/Arch/Xtensa.cpp üzerinde main veya üzerinde release/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çar l32r hizası şu altında: -ffunction-sections (llvm/llvm-project#190204, açık). Xtensa hâlâ şurada deneyseldir: LLVM_ALL_EXPERIMENTAL_TARGETS yukarı akım.
  3. Espressif's fork has all of it. esp-clang (espressif/llvm-project, en yeni 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).

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, rainbow and usbserial included) and nine for the ESP8266 (20 steps), about 1 s each natively;
  • ld.lld her yer değiştirmeyi çözüyor (ESP32 nesnelerinde: 3.407 adet R_XTENSA_32 ve 430 adet 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. 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-as gereklidir. Xtensa için Espressif sürücüsü varsayılan olarak bir .s dosyasını harici bir GNU derleyicisine (xtensa-esp32-elf-clang-as) verir; WASI bunu başlatamaz. Şununla: -fintegrated-as clang'ı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 iki crt0.S dosyamız için eksiksizdir ve simülatör testlerinin gösterdiği şey de budur. Ayrıca bir projenin kendi .S ve .s dosyalarının Xtensa kartlarında sunulmamasının nedeni de budur: orada yalnızca .c, .cpp ve .ino derlenir; 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 (-Werror altında hata sayılır), çünkü multilib.yaml dosyasında böyle bir girdi yoktur. BareMetal::findMultilibs yalnızca var olan bir multilib.yaml dosyasını okur ve wasm dosya sisteminde böyle bir dosya yoktur, dolayısıyla yalnızca yerel çalıştırmanın -Wno-missing-multilib bayrağına ihtiyacı vardır ve bu bayrağı yalnızca plan.ts --native geçirir.
  • GCC'nin -mlongcalls ve -mtext-section-literals bayrakları kalkar. Clang bunları -mlongcalls kullanılmayan argüman olarak bildirir, bu da şu bayrak altında -Werrorhatadır. Olmadan clang -mtext-section-literals bölümleri üretir; üç .literal.<function> dosyası da bunları zaten şunun başına link.ld koyar, yani .text, well inside L32R'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ı

  1. Derlemeyi yapan: .github/workflows/clang-v3.yml, çalıştırma 36358476287 (deneme 3, main dalında 4578344f): espressif/llvm-project, esp-22.1.4_20260825 sürümü, RISCV;AVR;ARM;Xtensa hedefleriyle, her iki WASI yamasıyla, ardından üç kartın hepsi için plan.ts --wasm ve simülatörün testleri wasm ile derlenenler üzerinde çalıştırıldı. Artefakt clang-v3, zip'in sha256 değeri ef27b7aa…3eafd; clang.wasm 80.735.841 bayt, sha256 7546c54c07c392e231ea450f8e3aaa6680346ffeb08e13d97d970b26d88666e5.
  2. Yayınlandı 2026-09-28: artefakt web/public/toolchain/clang-v3/ dizinine açıldı, ardından deploy/fetch-toolchain.sh --publish clang-v3 çalıştırıldı. https://mokxi.com/toolchain/clang-v3/ adresi clang.wasm, bundle.json ve include.tgz dosyalarını doğru türlerle, doğru uzunluklarla ve artefaktla aynı sha256 değerleriyle sunuyor. bundle.json budanmamış (16 MB, tüm clang kaynak başlıkları); yalnızca /usr/include girdileri kullanılıyor ve clang-v2'ninki gibi budanması bu indirmenin büyük kısmını kurtarırdı.
  3. Chromium'da kontrol edildi (headless, yayınlanmış dosyalar web/public/toolchain/clang-v3/ içindeyken npm 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'un proof/esp8266/blink.elf dosyasıyla bayt bayt aynı.
  4. 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. CCOUNT geriye gidiyordu, çalışma zamanının 64 bit çevrim sayacı bunu 2^32 çevrimlik bir sarmalama olarak okuyordu ve ilk delay()'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.rs ve iki kardeşinde) ve blink_keeps_its_half_period_when_a_pin_moves_as_the_core_parks bunu koruyor (clang ELF'lerini gösterecek şekilde MOKXI_ESP8266_ELF_DIR ile çalıştır).
  5. Kayan nokta, soft float'tır. -mcpu=esp32 ve -mcpu=esp32s3 modelde bulunmayan tek duyarlıklı FPU'yu açar, bu yüzden başta bir float çarpımı, karşılaştırması ya da DHT dersindeki isnan(h) || isnan(t) ifadesi bir FPU komutuna derleniyor ve kart duruyordu. Paketler artık -Xclang -target-feature -Xclang -fp geçiriyor (Xtensa sürücüsünde -mfloat-abi yok), böylece float'lar her diğer soft-float kartta olduğu gibi mokxi_float.c iç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.c dosyasını bağlar.

Sonraki adımlar

  1. 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.ts ve hazır kütüphane testlerini çalıştır ve bayt özdeş çıktı varsayma.
  2. Hazır kütüphaneleri Xtensa ailelerinde kontrol et. firmware/lib diğer tüm kartlarda olduğu gibi onların include yolunda, ama stock-libraries.test.ts onları listelemiyor, yani Servo.h, Wire.h ve diğerleri orada test edilmemiş.
  3. bundle.json dosyası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:

  1. Araç zincirinde arka uç var, yayınlanmış ve onunla derlenen bir kod simülatörde çalışmış.
  2. 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 yine reuse.
  • 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ü):

  1. -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.
  2. 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.sh aynı nedenden ötürü zaten ld.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:

  1. Plan. projectPlan (toolchain.ts) her .S dosyası 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 nedenini runtimeSteps zaten açıklıyor: -c foo.S clang'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 .s dosyası, ö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 .S satırında kesme noktası koyabilmesini sağlayan da budur. Derleme adımı yalnızca derleyicinin kendisinin okuduğu bayrakları, artı -g -gdwarf-4 geçirir.
  2. İşlenen denetimleri. asm-check.ts, herhangi bir araç çalışmadan önce projenin tüm AVR .S ve .s dosyalarını okur ve clang'ın kendi file:line:col: error: biçiminde bildirir, böylece parseDiagnostics ve 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, r5 olarak okunur), __SFR_OFFSET 0 olmadan out PORTB, r16 (bir uyarı: farklı bir kayda ulaşır), 63'ü geçen in ve out, 63'ü geçen sbiw ve adiw, ve 7'yi geçen bir bit. Bir işlenen yalnızca çözülebiliyorsa yargılanır: sayılar, dosyanın kendi .equ, .set ve #define tanı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).
  3. 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ın crt0.S nesnesidir ve başka hiçbir şey değildir; bu da avr-libc'in gcrt1.o dosyasının avr-gcc main.S karşısındaki rolüdür: her __vector_<n>'in zayıf bir reti olduğu vektör tablosu, r1 temizlenmiş, yığın RAMEND'de, .data kopyalanmış, .bss temizlenmiş ve projenin main işlevine bir çağrı. Dosyası kendi .vectors bölümünü ya da __vectors etiketini 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, Serial yok.
  4. Sökücü. disasm.ts bizim yazdığımızdır, çünkü tarayıcının LLVM'i clang, ld.lld ve llvm-objcopy taşır ama llvm-objdump taşı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ı, BL ve 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. Metin llvm-objdump'ınkidir ve disasm.test.ts onu orada tutar: Uno, Mega, Pico ve Black Pill için gerçek derlemelerin (dört assembly başlangıç projesi ve kayan nokta matematiği, Serial ve pinler içeren bir kod) her komutu, makinenin kendi llvm-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 /stm32cube yoluna bağlanır, include dizinleri yola eklenir, -DSTM32F411xE ya da -DSTM32F103xB ile, HAL kullanıldığında -DUSE_HAL_DRIVER, LL kullanıldığında -DUSE_FULL_LL_DRIVER ve -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.h dosyasının etkinleştirdiği HAL modülleri, içerdiği LL dosyaları ve sistem dosyası -w ile 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, ve mokxi_cube_bare.c printf() fonksiyonunu projenin _write() veya __io_putchar() fonksiyonuna yönlendirir. Bir kod Arduino çekirdeğini korur ve mokxi_cube_sketch.c HAL'in tikini millis() 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'nin syscalls.c ve sysmem.c dosyaları 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 (.S ve .s, yukarıya bakın). MicroPython yok ve başka bir dil de yok: Pico'nun MicroPython'u ve bir Raspberry Pi'nin main.py dosyası 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 program dizgesi bir aile adı içermeyen kartın hiç ailesi yoktur, bu yüzden familyFor hiçbir şey bulamaz ve kart önceden derlenmiş ELF'ini çalıştırır. Ailesi ready olmayan kart da aynı şeyi yapar; panelde ailenin note değ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 üzerinden compileStreaming, 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.ts dosyası /toolchain/ için bilerek 404 yanıtı verir, dolayısıyla web/vite.config.ts iç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.

Sorular

Derleme nerede gerçekleşir?

Senin makinende, sekmede. Derleme sunucusu yok, kuyruk yok, derleme dakikası yok.

Araç zinciri ne kadar büyük?

Yaklaşık yetmiş megabayt. Bir kez akarak indirilir ve tarayıcı önbelleğe alır; böylece ilk derlemeden sonra her şey yereldir.