المرجع

ترجمة الكود في المتصفح

كيف يتحول الكود إلى برنامج ثابت من دون خادم بناء في أي مكان.

تُترجم ملفات اللوحة بواسطة clang حقيقي وlld حقيقي، يعملان كـ WebAssembly داخل الصفحة. لا يوجد خادم بناء، ولا يُرفع أي شيء، وملف ELF الناتج هو من نفس نوع الصورة التي ينتجها firmware/build.sh: هو نفس المترجم يعمل بنفس قائمة الأوامر.

الدليل على أن هذا يعمل، مع الأرقام التي بررت بناءه، موجود في proofs/compile/REPORT.md. هذا المستند يشرح كيف ينفّذه المنتج.

هيكل الطريقة

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

كل شيء عدا لوحة البناء يعمل في الـ worker، لذا فإن بناء أول يستغرق أربع ثوانٍ لا يحجب أي إطار من مساحة العمل أبدًا.

ما يجب أن يصل إلى المتصفح

شيئان، من مكانين.

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، لذا فإن أي تغيير في firmware/ لم ينقله أحد سيفشل في مجموعة الاختبارات بدلًا من أن يفشل بناء مستخدم.

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.

إصدار سلسلة الأدوات مثبّت لكل عائلة لوحات

الإصدار خاصية للعائلة لا للتطبيق، لأن البناءين ليسا مترجمًا واحدًا: جرى إعداد clang-rv32-v1 باستخدام LLVM_TARGETS_TO_BUILD=RISCV وحده، فهو يستطيع الترجمة من أجل ESP32-C3 ولا يستطيع ماديًا الترجمة من أجل Uno. أما clang-v2 فهو سكربت البناء نفسه مع LLVM_TARGETS_TO_BUILD=RISCV;AVR;ARM (نفس التخطيط، ونفس الحاوية، ونفس شكل الرابط)، وكل عائلة تُترجم اليوم مثبّتة عليه (DECISIONS.md بتاريخ 2026-09-14: تم التحقق على الواجهات الخلفية الثلاث ورفعه إلى R2). مخرجاته لـ RISC-V مطابقة بايتًا ببايت لمخرجات clang-rv32-v1، لذا انتقل ESP32-C3 إليه أيضًا وتتشارك كل لوحة من هذا النوع تنزيلًا واحدًا. أما عائلات Xtensa فمثبتة على clang-v3 (XTENSA_TOOLCHAIN)، ونُشرت بتاريخ 2026-09-28:

العائلة برنامج catalog الهدف سلسلة الأدوات جاهز
esp32c3 elf32 riscv32imc riscv32-unknown-elf -march=rv32imc -mabi=ilp32 clang-v2 نعم
c6 elf32 riscv32imc esp32c6 riscv32-unknown-elf -march=rv32imc -mabi=ilp32 clang-v2 نعم
uno elf32 avr atmega328p avr -mmcu=atmega328p clang-v2 نعم
nano elf32 avr atmega328p nano avr -mmcu=atmega328p clang-v2 نعم
mega2560 elf32 avr atmega2560 avr -mmcu=atmega2560 clang-v2 نعم
leonardo elf32 avr atmega32u4 avr -mmcu=atmega32u4 clang-v2 نعم
attiny elf32 avr attiny85 avr -mmcu=attiny85 clang-v2 نعم
pico elf32 arm rp2040 thumbv6m-none-eabi -mcpu=cortex-m0plus -mthumb clang-v2 نعم
xiao elf32 arm samd21 thumbv6m-none-eabi -mcpu=cortex-m0plus -mthumb clang-v2 نعم
stm32 elf32 arm stm32f411 thumbv7em-none-eabi -mcpu=cortex-m4 -mthumb -mfloat-abi=soft -mfpu=none clang-v2 نعم
bluepill elf32 arm stm32f103 thumbv7m-none-eabi -mcpu=cortex-m3 -mthumb -mfloat-abi=soft clang-v2 نعم
microbit elf32 arm nrf52833 thumbv7em-none-eabi -mcpu=cortex-m4 -mthumb -mfloat-abi=soft -mfpu=none clang-v2 نعم
unor4 elf32 arm ra4m1 thumbv7em-none-eabi -mcpu=cortex-m4 -mthumb -mfloat-abi=soft -mfpu=none clang-v2 نعم
esp32 elf32 xtensa lx6 esp32 xtensa-esp-elf -mcpu=esp32 -fintegrated-as clang-v3 نعم
esp32s3 elf32 xtensa lx7 esp32s3 xtensa-esp-elf -mcpu=esp32s3 -fintegrated-as clang-v3 نعم
esp8266 elf32 xtensa lx106 esp8266 xtensa-esp-elf -mcpu=esp8266 -fintegrated-as clang-v3 نعم

الصفوف الثلاثة الأخيرة هي القسم التالي. web/src/compile/bundles.ts هو القائمة التي تُقرأ منها هذه الجدولة، وbundles.test.ts يبقيهما متوافقتين.

لوحات Xtensa، على clang-v3

ESP32 الكلاسيكي معالج Xtensa LX6، وESP8266 NodeMCU معالج Xtensa LX106، وESP32-S3 معالج Xtensa LX7. الثلاثة تُترجم في المتصفح على clang-v3 منذ 2026-09-28 («منشور ومفحوص» أدناه). قبل ذلك كانت تعمل بملفات ELF مبنية مسبقًا وتصرّح بذلك. بقية هذا القسم تشرح لماذا احتاج الأمر إلى نسخة معدّلة، وما وجده الإثبات.

لماذا هي سلسلة أدوات منفصلة (فُحصت بتاريخ 2026-09-27):

  1. لا يملك clang-v2 واجهة خلفية لـ Xtensa. بُني باستخدام LLVM_TARGETS_TO_BUILD=RISCV;AVR;ARM (DECISIONS.md بتاريخ 2026-09-14). ملف wasm الذي ينزّله المتصفح عاجز فعليًا عن إنتاج ملف Xtensa.
  2. يملك LLVM الرسمي نصف ما يلزم، وهو النصف الخطأ. يحمل Clang واجهة أمامية لـ Xtensa منذ LLVM 20 (Phoronix)، وإصدارات LLVM 22 من XtensaProcessors.td يعرف esp32 و esp8266 (من المصدر الرئيسي main يضيف esp32s2 و esp32s3). لكن الإصدار الأصلي ld.lld لا يدعم Xtensa إطلاقًا: لا يوجد lld/ELF/Arch/Xtensa.cpp على main أو على release/22.x، لذا لا يمكن لأي شيء في الإصدار الأصلي ربط صورة ESP32. كما أن الواجهة الخلفية في الإصدار الأصلي لا تزال تُصدر مجمعات القيم الحرفية داخل .text، وهو ما يكسر l32r المحاذاة تحت -ffunction-sections (llvm/llvm-project#190204، مفتوحة). لا يزال Xtensa في LLVM_ALL_EXPERIMENTAL_TARGETS الإصدار الأصلي.
  3. Espressif's fork has all of it. esp-clang (espressif/llvm-project، أحدث 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).

إذًا هذا fork لتتبّعه لا راية (flag) لإضافتها، لكن الفورك هو فورك Espressif نفسها، ويُنشر كل بضعة أشهر، تحت الترخيص نفسه الذي يأتي منه LLVM الذي يأتي منه clang-v2.

ملفات ELF الجاهزة لا تزال مبنية بواسطة ‏GCC الخاص بـ Espressif، الذي يضعه deploy/fetch-xtensa.sh في tools/xtensa/: xtensa-esp32-elf-gcc 8.4.0 للمعالج LX6، وxtensa-esp32s3-elf-gcc 8.4.0 للمعالج LX7 وxtensa-lx106-elf-gcc 8.4.0 للمعالج LX106. بيئة تشغيل S3 تعيد استخدام crt0.S وsupport64.c الخاصة بـ ESP32 الكلاسيكي: بالنسبة للكود الذي يُصدره المترجم من لغة C، يعد LX7 هو نفسه LX6، ومخرجات مترجم S3 لنفس برنامج الاختبار مطابقة بايت ببايت لمخرجات مترجم ESP32. هذا الدليل مستثنى في git. ترخيص GCC هو GPL، ولا شيء مما يبنيه هنا يرتبط بـ libgcc (فبيئات التشغيل تستخدم -nostdlib مع ملف support.c الخاص بها، وملف support32.c الخاص بـ ESP8266 يوفّر عمليات القسمة على 32 بت التي لا يوجد تعليمة لها في LX106)، لذا لا يصل أي كود مرخّص بـ GPL إلى ملف ELF موزَّع.

إثباته محليًا (natively)

قبل أن يوجد أي wasm، يُثبَت جانب المترجم بالنسخة المحلية لنظام Linux من الفورك نفسه (clang-esp-22.1.4_20260825-x86_64-linux-gnu.tar.xz، حجمها 411 MB، وبصمة sha256 4700ed4e...eb0a1، وتفكّ إلى 2.7 GB ويوجد فيها ld.lld):

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

ينزّل ذلك الإصدار ثم يشغّل proofs/compile/xtensa/plan.ts --native، وهو لا ينسخ أي أوامر يدويًا: بل يأخذ runtimeSteps وprojectPlan من web/src/compile/toolchain.ts وحِزم وقت التشغيل المودعة web/public/firmware/runtime/esp32.json وesp32s3.json وesp8266.json، فما يُشغَّل هو قائمة أوامر المتصفح نفسها، مع فصل crt0.S إلى نصفَيه (المعالجة المسبقة والتجزئة/التجميع assemble)، ونداء ld.lld مباشرة، وllvm-objcopy إلى stdout. النتيجة بتاريخ 2026-09-27:

  • every example of every board compiles and links with -Wall -Wextra -Werror: nine for the ESP32 (19 steps each), eleven for the ESP32-S3 (21 steps, rainbow and usbserial included) and nine for the ESP8266 (20 steps), about 1 s each natively;
  • ld.lld يحلّ كل إعادة تموضع (relocation) (في كائنات ESP32: 3,407 من R_XTENSA_32 و430 من R_XTENSA_SLOT0_OP)؛
  • MOKXI_ESP32_ELF_DIR=... cargo test -p esp32 --test runtime --test wifi: 11 + 4 passed؛ وMOKXI_ESP32S3_ELF_DIR=... cargo test -p esp32s3 --test runtime --test wifi: 13 + 4 passed؛ وMOKXI_ESP8266_ELF_DIR=... cargo test -p esp8266 --test runtime --test wifi: 11 + 4 passed. وهي نفس الاختبارات التي تنجح بها ملفات ELF الخاصة بـ GCC: نصف دورة الوميض البالغ 500 ms، وLEDC وPWM البرمجي عند 1 kHz، وmillis() مقابل ساعة النواة، وتباعد بتّات UART0، وال ADC، وإطارات WS2812 على S3 عند LED الملون الخاص به (أبيض ثم قوس قزح بأخضر أولًا على السلك)، وحِزم USB التسلسلية الخاصة به، واتصال WiFi وصفحة المصباح على الويب. المتغيرات البيئية الثلاثة لا تفعل شيئًا سوى توجيه الاختبارات القائمة إلى مجلد آخر؛ وملف تالف هناك يجعلها تفشل (panic)، فهي فعلًا حمّلت ما بُني.

ثلاثة أشياء كشفها الإثبات، وكلها عولجت في الحِزم:

  • -fintegrated-as مطلوب. بالنسبة إلى Xtensa، يسلّم برنامج Espressif التعريفي (driver) ملفًا .s إلى مجمّع GNU خارجي (xtensa-esp32-elf-clang-as) افتراضيًا، وهو ما لا يستطيع WASI تشغيله. مع -fintegrated-as يأخذ مجمّع clang الخاص ملف crt0.S كما هو مكتوب. وهو من رايات (flags) عائلة الهدف نفسها، لذا يحصل نصف التجميع (assemble) عليه أيضًا. تُطفئه Espressif عن قصد لمدخلات التجميع (EspBareMetal.cpp: "TODO: Add full support for Xtensa to integrated asm, LLVM-290, LLVM-291")، فهو ليس مكتملًا لكل ملف مكتوب يدويًا؛ لكنه كذلك لكلا ملفَّي crt0.S الخاصين بنا، وهذا ما تُظهره اختبارات المحاكي. وهو أيضًا سبب عدم عرض ملفات .S و .s الخاصة بالمشروع على لوحات Xtensa: فقط .c, .cpp و .ino تُترجَم هناك، بينما كل عائلة أخرى تجمّع ملفات المشروع نفسها أيضًا (انظر لغة التجميع أدناه). أما C وC++ فيمرّان دائمًا بالمجمّع المدمج، في هذا الفورك كما في الأصل.
  • لا تحذير multilib في الـ wasm. التنصيبة المحلية تحذّر من عدم وجود multilib لل esp8266 (وهو خطأ مع -Werror) لأن multilib.yaml الخاص بها لا يحتوي على هذا المدخل. وBareMetal::findMultilibs لا يقرأ إلا multilib.yaml موجودًا، ونظام ملفات الـ wasm لا يحتوي على أيٍّ منها، لذا فقط التشغيل المحلي يحتاج -Wno-missing-multilib، وفقط plan.ts --native يمرّره.
  • رايتا -mlongcalls و-mtext-section-literals الخاصتان بـ GCC تُحذفان. يبلّغ clang عن -mlongcalls بأنه وسيطة غير مستخدمة، وهو خطأ مع -Werror. من دون -mtext-section-literals يصدر clang أقسام (sections) .literal.<function> ، وقد وضعها ملفات link.ld الثلاثة كلها بالفعل في بداية .text, well inside L32R's 256 KB reach.

حجم الكود، الجزء القابل للتنفيذ من كل مثال مقابل صورة GCC المشحونة (المصادر نفسها، والاثنان مع -Os):

اللوحة GCC، كل الأمثلة clang لكل مثال
ESP32 29,984 بايت 37,760 بايت من ‎+15%‏ (fade) إلى ‎+37%‏ (wifilamp)، و‎+26%‏ إجمالًا
ESP32-S3 41,584 بايت 53,920 بايت من ‎+18%‏ (fade) إلى ‎+38%‏ (wifilamp)، و‎+30%‏ إجمالًا
ESP8266 34,592 بايت 49,104 بايت من ‎+33%‏ (button) إلى ‎+49%‏ (wifilamp)، و‎+42%‏ إجمالًا

البيانات ضمن بضع عشرات من البايتات في الحالتين. أكبر صورة clang هي wifilamp الخاص بـ ESP8266 بواقع 8,944 بايت من الكود، مقابل IRAM سعته 32 KB وحدّ 24 KB الذي يُلزم elfcheck.py الأمثلة به، فالزيادة لا تكلّف شيئًا يلاحظه كودٌ هنا. أما إلى أين تذهب البايتات فلم يُفصَّل.

منشور ومُتحقَّق منه

  1. بُني بواسطة .github/workflows/clang-v3.yml، التشغيل 36358476287 (المحاولة 3، وmain عند 4578344f):‏ espressif/llvm-project عند esp-22.1.4_20260825 مع RISCV;AVR;ARM;Xtensa، وكِلتا رقعتَي WASI، ثم plan.ts --wasm للوحات الثلاث واختبارات المحاكي على ما بناه الـ wasm. المُخرَج (artifact) clang-v3، وبصمة sha256 للـ zip هي ef27b7aa…3eafd؛ وحجم clang.wasm هو 80,735,841 بايت، وبصمة sha256 هي 7546c54c07c392e231ea450f8e3aaa6680346ffeb08e13d97d970b26d88666e5.
  2. نُشر في 2026-09-28: فُكّ ضغط الحزمة في web/public/toolchain/clang-v3/، ثم deploy/fetch-toolchain.sh --publish clang-v3. يقدّم https://mokxi.com/toolchain/clang-v3/ الملفات clang.wasm وbundle.json وinclude.tgz بالأنواع الصحيحة والأطوال الصحيحة وقيم sha256 مطابقة للحزمة الأصلية. ملف bundle.json غير مُقلَّم (16 MB، وكل ترويسة موارد clang فيه)؛ لا تُستخدم سوى مدخلات /usr/include منه، وتقليمه بالطريقة التي قُلِّم بها ملف clang-v2 كان سيوفّر معظم حجم ذلك التنزيل.
  3. جرى الفحص في Chromium (بدون واجهة، مقابل npm run dev مع الملفات المنشورة في web/public/toolchain/clang-v3/): فتح المحرر الحقيقي مخططًا بكوده الخاص، وضغط «تشغيل»، وراقب لوحة البناء والشاشة التسلسلية وLED. انضم كود ESP32 إلى شبكة WiFi المحاكاة (192.168.4.2) وأومض GPIO 4؛ وأومض كود ESP32-S3 الطرف GPIO 2 وطبَع مخرجات؛ وأومض كود ESP8266 الطرف D1 وطبَع قسمة 32-بت في كل دورة؛ وكذلك مثال Blink الخاص بـ ESP8266 نفسه بعد تعديله وبنائه أومض أيضًا. استغرق البناء الأول للوحة من 5 إلى 7 ثوانٍ بما في ذلك بيئة التشغيل، واللاحق نحو 1.5 ثانية. ملف ELF الذي بنته الصفحة لكود Blink على ESP8266 مطابق بايتًا بايتًا لملف proof/esp8266/blink.elf الخاص بسير العمل.
  4. كشف فحص ESP8266 خطأً في المحرك، أُصلح في التغيير نفسه. يكتب كود Blink الخاص بـ clang أطرافه في الشريحة الزمنية نفسها التي يتوقّف فيها، فتتحرك شبكة الطرف داخل وقت سبق للنواة أن شغّلته، وكانت قطعة اللوحة تُزيح النواة المتوقفة قبل نهاية تلك الشريحة. رجع CCOUNT إلى الوراء، فقرأ عدّاد الدورات 64-بت في بيئة التشغيل ذلك كالتفاف 2^32 دورة، وصار كل استدعاء delay() بعد الأول يعود فورًا: أضاء LED وبقي مضيئًا. أما كود Blink الخاص بـ GCC فلا يكتب طرفًا أبدًا في الشريحة التي يتوقّف فيها، ولهذا لم يُظهره أي مثال مُرفَق، ولم تُظهره الاختبارات الأصلية لأنها تشغّل SoC بدون دائرة. لم تعد قطع لوحات ESP32 و ESP32-S3 و ESP8266 تشغّل النواة قبل نقطة نهاية آخر شريحة لها (ran_to في crates/parts/src/parts/esp8266.rs وملفّيه الشقيقين)، والاختبار blink_keeps_its_half_period_when_a_pin_moves_as_the_core_parks يضمن ذلك (شغّله مع توجيه MOKXI_ESP8266_ELF_DIR إلى ملفات ELF الخاصة بـ clang).
  5. الفاصلة العائمة ناعمة (soft float). الخياران -mcpu=esp32 و-mcpu=esp32s3 يشغّلان وحدة FPU أحادية الدقة، وهي غير موجودة في النموذج، لذا ففي البداية كان ضرب float أو مقارنته، أو تعبير isnan(h) || isnan(t) في درس DHT، يُترجم إلى تعليمة FPU فتتوقف اللوحة. تمرر الحزم الآن -Xclang -target-feature -Xclang -fp (لأن برنامج تشغيل Xtensa لا يملك -mfloat-abi)، فتصبح الفواصل العائمة استدعاءات إلى mokxi_float.c كما في كل لوحة soft-float أخرى، وتعطي النتائج الصحيحة. أما LX106 في ESP8266 فلا يملك وحدة FPU لإطفائها أصلًا، ويربط ملف mokxi_float.c نفسه.

الخطوات التالية

  1. تقرير ما إذا كانت كل العائلات تنتقل إلى clang-v3. إلى أن يحدث ذلك، يستخدم المستخدم الذي يبني لـ ESP32 ولأي لوحة أخرى سلسلتَي أدوات حجم كل منهما أكثر من 75 MB في Cache API: يحتفظ isStaleKey (cache.ts) بكل نسخة تذكرها عائلة (TOOLCHAINS_IN_USE) ولا يُسقط الأخرى إلا عند امتلاء القرص. قبل 2026-10-17 كان يُسقط كل نسخة عدا المستخدمة، فكان كل تبديل يعيد تنزيل 20 MB ويفشل دون اتصال. نقلها كلها هو سطر واحد لكل عائلة، كما كان الحال في الانتقال إلى clang-v2، لكنه هنا LLVM 22.1.4 من نسخة مشتقة وليس 22.1.0، لذا شغّل crash.test.ts واختبارات المكتبات المرفقة عليه أولًا، ولا تفترض مخرجات متطابقة بايتًا بايتًا.
  2. فحص المكتبات المرفقة على عائلات Xtensa. المجلد firmware/lib موجود في مسار التضمين كما في كل لوحة، لكن stock-libraries.test.ts لا يذكرها، لذا فإن Servo.h وWire.h وغيرهما غير مختبرة هناك.
  3. تقليم bundle.json إلى الترويسات التي يفتحها بناء freestanding.

لا تدّعِ أبدًا وجود ترجمة في المتصفح لا تعمل: زر بناء يشغّل بصمت ملفًا ثنائيًا من الأمس سيكون أسوأ شيء في هذا المنتج.

clang-rv32-v1 لا يزال قيمة RV32_TOOLCHAIN ولا تذكره أي عائلة. يبقى كطريق للرجوع: تغيير سلسلة toolchain الخاصة بعائلة هو كل ما في نشر بناء أو التراجع عنه، إذ إن العناوين ومفتاح تخزين الوحدات ومخزن كائنات بيئة التشغيل كلها تتعلق به.

ready ليس كودًا ميتًا أيضًا. يجب أن يتحقق أمران قبل أن تحمله عائلة، ويختبر bundles.test.ts الأمر الثاني منهما:

  1. أن سلسلة الأدوات تملك الواجهة الخلفية، وأنها منشورة، وأن كودًا بنته قد شُغّل على المحاكي.
  2. أن العائلة تملك حزمة بيئة تشغيل، أي أن مجلد البرامج الثابتة الخاص بها موجود وأن bundle-runtime.mjs قد شُغّل.

العائلة غير الحاملة لـ ready ليست خطأً: يرسل chooseProgram لوحاتها إلى ملف ELF الجاهز مسبقًا من web/public/firmware/، وتوضّح لوحة البناء والسطر بجانب منتقي اللوحة السبب، ولا شيء يفشل. لا تسلك أي عائلة هذا المسار اليوم؛ وقد سلكته عائلات Xtensa حتى نُشر clang-v3.

اللوحتان STM32 و micro:bit تستخدمان soft float عمدًا: يضع ملف DECISIONS.md بتاريخ 2026-09-14 وحدة FPU ووحدة M4 DSP خارج النطاق حتى الحاجة إلى لوحة M4F، لذا لا يجوز لأي من بيئتي التشغيل أن تولّد تعليمات VFP أو ABI ذا فاصلة عائمة صلبة.

ماذا يحدث عند الضغط على «تشغيل»

يسأل App.buildPrograms الدالة chooseProgram (src/compile/client.ts) عن كل لوحة، فيحصل على واحدة من ثلاث إجابات:

  • elf: شغّل الصورة التي تذكرها لوحة البرامج الثابتة ولا تترجم شيئًا. ملف ELF المرفوع لم يُبنَ من هذه الملفات؛ والمثال المرفق غير المعدَّل مبني أصلًا. والعائلة التي سلسلة أدواتها غير منشورة تقع هنا أيضًا.
  • reuse: شغّل ملف ELF المبني فعلًا من هذه الملفات تحديدًا. القرار مبني على بصمة تجزئة لكل اسم ملف وكل بايت فيه، لذا فكتابة حرف والتراجع عنها يعيدانك إلى reuse.
  • build: ترجم، وشغّل النتيجة.

البناء الفاشل يوقف التشغيل: يبقى الزر على «تشغيل»، ويُهمَل ملف ELF السابق بدلًا من استخدامه بصمت، وتبقى التشخيصات في اللوحة. ملف ELF المبني يبقى في الذاكرة طوال الجلسة فقط. إنه حقيقة عن هذه الجلسة، لا جزء من المستند، لذا لا يُحفظ ولا يُصدَّر ولا يُشارَك أبدًا.

قائمة الأوامر

الأوامر الأربعة عشر نفسها التي يشغّلها firmware/build.sh، مع فارقين تفرضهما WASI (اكتُشفا كلاهما في الإثبات):

  1. -c crt0.S يجعل clang يحتاج إلى مهمتين، معالجة أولية وتجميع، وclang يطفئ وحدته المدمجة cc1 بمجرد وجود أكثر من واحدة، وعلى WASI يكون ذلك "unable to execute command: WASI does not support spawning subprocesses". يُدرَج النصفان كلٌّ على حدة.
  2. يتم الربط عبر ld.lld مباشرةً بدلًا من برنامج clang المشغّل، لذا تفقد رايات ربط ESP32-C3 سوابقها -Wl,. وfirmware/uno/build.sh يستدعي ld.lld مباشرةً للسبب نفسه.

نظام الملفات الذي تراه الأدوات:

المسار ما هو
/usr/include ترويسات موارد clang، من حزمة سلسلة الأدوات
/firmware لـ ESP32-C3، و/firmware/<family> للبقية مصادر بيئة التشغيل الخاصة بنا، والترويسات، وcrt0.S، وlink.ld
/firmware/lib المشغّلات المشتركة المعتمدة على الترويسات فقط، بالمسار نفسه لكل عائلة
/project ملفات اللوحة، بأسمائها نفسها، بحيث يعمل #include "pins.h"
/build الكائنات، والكود الملفوف، وملف ELF

لغة التجميع

ملفات .S و.s الخاصة بالمشروع تُبنى هنا أيضًا، لأن arduino-cli يبني ملف .S بجوار الكود، ولأن اللوحة قد تكون لغة تجميع لا غير.

أربعة أجزاء، كلها في web/src/compile/:

  1. الخطة. يضيف projectPlan (في toolchain.ts) زوج خطوات لكل ملف .S: معالجة أولية بمسار التضمين ومسار علامات الاقتباس والتعريفات الخاصة بالكود نفسه (بحيث يعطي #include <avr/io.h> أسماء السجلات ويُضبط __ASSEMBLER__)، ثم تجميع النسخة المُعالجة مسبقًا. الأمر جولتان للسبب الذي يذكره runtimeSteps أصلًا: -c foo.S يجعل clang يريد مهمتين، وclang يوقف مدمجه cc1 بمجرد وجود أكثر من مهمة، وهذا يعطي على WASI الرسالة "unable to execute command: WASI does not support spawning subprocesses". أما .s فيُجمع مباشرة، بلا خطوة معالجة أولية. علامات # <line> "<file>" الخاصة بالمعالج الأولي تبقى محفوظة، فيكون تشخيص الخطأ وسطر DWARF هو سطر علامة التبويب نفسها لا سطر النسخة المُعالجة، وهذا ما يسمح لمصحح الأخطاء بالتوقف عند سطر .S. تمرر خطوة التجميع الأعلام التي يقرأها المجمّع نفسه فقط، إضافة إلى -g -gdwarf-4.
  2. فحوصات المعاملات. يقرأ asm-check.ts كل ملف .S و.s من نوع AVR في المشروع قبل تشغيل أي أداة، ويعرض الأخطاء بالصيغة التي يستخدمها clang نفسه file:line:col: error: بحيث لا تحتاج parseDiagnostics ولوحة البناء إلى أي جديد. يجري الفحوصات التي يجريها avr-as ويتجاهلها مجمّع LLVM للـ AVR بصمت: ldi r16, 300 (تُحفظ كـ 0x2C)، وsbi PORTB, 1 (عنوان بيانات في موضع عنوان إدخال/إخراج)، وadd r16, 5 (تُقرأ add r16, r5)، وout PORTB, r16 بدون __SFR_OFFSET 0 (تحذير: تصل إلى سجل مختلف)، وin وout بعد 63، وsbiw وadiw بعد 63، والبت بعد 7. لا يُحكم على معامل إلا عندما يمكن حسابه: الأرقام، و.equ و.set و#define الخاصة بالملف نفسه، وأسماء السجلات والبتات في ملف اللوحة الرأسي المقروء من حزمة وقت التشغيل، عبر _SFR_IO_ADDR() وlo8() وhi8() ومعاملات C. أما ما عدا ذلك فيُترك للمجمّع والرابط، وهما على صواب فيه. أي خطأ يوقف البناء قبل بدء أي أداة (plan.checkFailed).
  3. الربط، حين لا يوجد كود. isAssemblyProject (في bundles.ts) هو مشروع لا يحتوي ملفاته إلا لغة تجميع؛ وassemblyLinkInputs يحدد ما يُربط به إلى جانب كائناته الخاصة. على لوحة AVR هذا كائن crt0.S من وقت التشغيل ولا شيء غيره، وهو لـ avr-gcc main.S ما هو gcrt1.o لـ avr-libc: جدول المتجهات مع كل __vector_<n> كـ reti ضعيف، وr1 مُصفّر، والمكدس عند RAMEND، و.data منسوخ، و.bss مُصفّر، ونداء إلى main الخاصة بالمشروع. المشروع الذي يعرّف ملفه قسم .vectors خاصًا به أو تسمية __vectors (definesVectors) لا يحصل على شيء، وكذلك كل لوحة ARM، حيث الملف نفسه هو جدول المتجهات. ولا نواة Arduino في الحالتين: لا setup()، ولا نبضة millis()، ولا Serial.
  4. الفاكّ (disassembler). disasm.ts هو من صنعنا، لأن نسخة LLVM في المتصفح تحمل clang وld.lld وllvm-objcopy ولا تحمل llvm-objdump. يقرأ مقاطع ELF التنفيذية التي يحتفظ بها التطبيق أصلًا، فلا تحتاج قائمة الفك في علامة تصحيح الأخطاء وزر «خطوة تعليمة» إلى أي رحلة ذهاب وإياب. يغطي فاك AVR مجموعة التعليمات كاملة؛ ويغطي فاك Thumb كل الترميزات ذات 16 بت، وBL، وصيغ Thumb-2 ذات 32 بت التي يكتبها مترجم أو مقرر دراسي غالبًا، ويعرض ما عدا ذلك كـ .inst.w 0x… بدلًا من تخمين خاطئ. النص هو نص llvm-objdump، وdisasm.test.ts يُبقيه كذلك: كل تعليمة من بناءات حقيقية (قوالب التجميع الأربعة، وكود فيه حسابات فاصلة عائمة وSerial وأطراف) على Uno وMega وPico وBlack Pill يجب أن تُقرأ تمامًا كما يقرؤها llvm-objdump على الجهاز.

اللوحات التي تتيح مشروع لغة تجميع بلا نواة هي المذكورة في src/asm/boards.ts: Uno وNano وPro Mini وPico وSTM32F411. كل لوحة أخرى قابلة للترجمة تقبل علامات .S بجوار الكود، عدا لوحات Xtensa (انظر أعلاه). يبني asm.test.ts كل ذلك ويشغّله على المحاكي.

أداة تتعثر

يصل clang وlld كلاهما إلى مسار إحباط عند بعض الأخطاء القاتلة (تضمين #include مفقود، أساسًا) يطبع التشخيص إلى stderr ثم يصل إلى unreachable بدلًا من نداء exit. داخل WASI يظهر ذلك كـ WebAssembly.RuntimeError حقيقية، لا proc_exit، ولولا معالجة لانتشر كرفض غير معالج بلا أي تشخيص مرافق: انهيار، لا خطأ بناء.

Toolchain.run (src/compile/toolchain.ts) يعالج هذه الحالة بالضبط: الفخ الذي يحدث بعد أن تكون الأداة قد كتبت شيئًا إلى stderr يعود كخطوة فاشلة عادية، مع ضبط result.trapped وقيمة غير صفرية لـ result.code، ويبقى كل ما كُتب قبل الفخ في result.err. ثم يتعامل runSteps (src/compile/worker.ts) معها كما يتعامل مع أي خروج غير صفري: ما وجده parseDiagnostics هو ما تعرضه لوحة البناء، قابلًا للنقر مثل أي تشخيص آخر، ولا يرجع إلى رسالة "انهار المترجم (<tool> على <step>)" إلا عندما لا يحمل الفخ أي رسالة. كل تشغيلة للأداة تحصل أصلًا على WebAssembly.Instance جديدة من Module الواحد المُترجَم (toolchainFor يترجم الوحدة مرة واحدة؛ وToolchain.run ينشئ نسخة منها عند كل استدعاء)، لذا فالفخ في تشغيلة واحدة لا يترك شيئًا يؤثر على التالية. لا توجد نسخة يمكن أن تُتلَف، ولا شيء هنا يعيد إنشاء الوحدة بنفسه.

تُدمج تبويبات .ino وتُغلَّف بالطريقة نفسها التي يتبعها Arduino IDE (src/compile/prototypes.ts): #include "arduino.h"، ثم التبويب الرئيسي وبقية تبويبات .ino بالترتيب الأبجدي، كل واحد خلف #line 1 "<tab>.ino"، مع نموذج أولي (prototype) لكل دالة تُعرِّفها التبويبات يُكتب قبل الدالة الأولى مباشرة، كل واحد خلف #line يشير إلى تعريفه، و#line بعد الكتلة. وهكذا يبني الكود الذي يستدعي دالة مُعرَّفة أسفل loop()، ويظل المترجم يبلغ عن المشكلة في sketch.ino:12:3 حتى تستطيع لوحة البناء الانتقال بالمحرر إلى هناك. القوالب (templates) وأعضاء الأصناف وأي شيء داخل نطاق أسماء (namespace)، والدالة التي يُعلن الكود نموذجها الأولي بنفسه، والدالة التي يذكر توقيعها شيئًا مُعلنًا في موضع أدنى، كلها لا تحصل على نموذج أولي؛ والدالة داخل كتل #if يحصل نموذجها الأولي داخل نسخة من الشروط نفسها؛ والوسائط الافتراضية تنتقل إلى النموذج الأولي وتُفرَّغ، عمودًا بعمود، من التعريف. ملفات .c تُترجم كـ C11، و.cpp/.cc/.ino كـ C++17؛ وأي شيء آخر يُكتب في /project من أجل التضمينات ولا يُترجم.

تُترجم ملفات المستخدم بأعلام التحذير الخاصة بوقت التشغيل ناقص -Werror (userWarnings في bundles.ts): تُعرض تحذيرات -Wall -Wextra في لوحة البناء، ويحتفظ الملف الهدف المخزَّن مؤقتًا بتحذيراته فتُعرض مجددًا عند «تشغيل» التالي، لكن التحذير لا يوقف البناء، كما في Arduino IDE. أما وقت التشغيل نفسه، وprojectPlan(..., { strict: true }) (برهان Xtensa، واختبارات المكتبات القياسية ووحدات الاتصال)، فتُبقي على -Werror، وهذا ما يجعل كود Mokxi وأمثلته خالية من التحذيرات.

ما يُخزَّن مؤقتًا، وأين

ما هو أين المفتاح يُفقد عند
بايتات clang.wasm Cache API، mokxi-toolchain-v1 /toolchain/<version>/clang.wasm لم تعد أي عائلة تستخدم هذا الإصدار، امتلأ القرص، مُسحت مساحة التخزين
ملفات الأهداف الخاصة بوقت التشغيل Cache API، المخزن نفسه /toolchain/<version>/runtime/<family>-<bundle hash>.objects تغيّر الإصدار، تغيّر البرنامج الثابت، مسح مساحة التخزين
WebAssembly.Module المُترجَم العامل (worker)، في الذاكرة إصدار سلسلة الأدوات إغلاق الصفحة
ملفات الأهداف الخاصة بوقت التشغيل العامل (worker)، في الذاكرة إصدار سلسلة الأدوات + العائلة إغلاق الصفحة
الملف الهدف لكل شيفرة مصدر في المشروع العامل (worker)، في الذاكرة نص المصدر + الأمر بالضبط إغلاق الصفحة
ملف ELF المبني التطبيق، في الذاكرة معرّف اللوحة + بصمة الملف إغلاق الصفحة

ملفات أهداف وقت التشغيل هي نحو اثني عشر ملفًا من بضع كيلوبايتات لكل منها، مُجمَّعة في إدخال ذاكرة تخزين مؤقت واحد بدلًا من اثني عشر (MOKO، ثم طول الترويسة، ثم فهرس JSON من أزواج [path, length]، ثم البايتات متتابعة)، فالإصابة تعني مطابقة match واحدة وarrayBuffer واحدًا بدل اثنتي عشرة من كل منهما. يحمل المفتاح بصمة حزمة وقت التشغيل كما جُلبت تمامًا، كل مصدر وترويسة وعلم فيها، بحيث ينتج عن تعديل firmware/src/gpio.c وإعادة التوليد مفتاح مختلف لا ملف هدف قديم. وأي شيء لا يمكن فك حزمته يُحذف ويُعاد بناؤه، لأن كتلة (blob) لا نستطيع قراءتها أسوأ من لا كتلة.

ما لم يعد قابلًا للوصول يمر في طريق الخروج: كل إدخال لسلسلة أدوات أقدم، ووقت تشغيل لعائلة تقدّمت مصادرها. أما العائلة التي لا تذكرها هذه الصفحة فتُترك وحدها: مستخدم لديه وقت تشغيل Uno مخزَّن مؤقتًا ويقضي يومه على ESP32-C3 يحتفظ به.

كل جزء من هذا يتعامل مع الفشل: لا Cache API، أو ذاكرة تخزين ترفض استثناءً، أو put يصطدم بحصة (quota): كل ذلك يعني «أعد العمل»، ولا يعني أبدًا «لا مترجم».

قياسات

في Chromium 141 على حاوية البناء، مقابل npm run dev على loopback (الذي يقدّم clang.wasm غير مضغوط، فالتنزيل هو الحالة المتشائمة؛ الإنتاج يقدّمه من R2 مع Content-Encoding: br):

من النقر إلى التشغيل ما حدث
أول بناء، بارد 6.1 إلى 7.8 ث تنزيل 74 MB، وWebAssembly.compile، و12 ملف هدف لوقت التشغيل، والكود، والربط، والتقليم
الزيارة الثانية وما بعدها 1.5 إلى 1.8 ث لا طلب لـ clang.wasm؛ وقت التشغيل من Cache API في 3 إلى 9 ms
تعديل ثم «تشغيل» مجددًا، في الجلسة نفسها 0.21 s sketch.ino 51 ms, link 10 ms, strip 5 ms
«تشغيل» بلا تعديل لا ترجمة إطلاقًا
ملف ELF 1.5 KB يومض GPIO 8 بالوتيرة التي يطلبها الكود، على المحرك الحقيقي بسرعة 1.00x

أربع زيارات في ملف تعريف متصفح واحد أنتجت طلبًا واحدًا فقط لـ clang.wasm، والزيارة الثانية وكل ما بعدها تخطّت وقت التشغيل تمامًا:

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

لا يتبقى من الزيارة الثانية سوى أمرين، لا يشمل أي منهما بيئة التشغيل: نحو 0.7 ثانية لقراءة 74 MB من Cache API وترجمتها عبر compileStreaming، ونحو 0.5 ثانية لأول تشغيل للأداة في وحدة مترجمة حديثًا، وهو ما يعني أن المحرك يسخن؛ فالتعديل الثاني في الجلسة نفسها يستغرق 51 ms كما ذكرنا أعلاه.

تُظهر لوحة البناء نسبة التنزيل، وكل خطوة بتوقيتها، وسطرًا واحدًا في النهاية: Built esp1.elf, 1.5 KB, 0.21 s.

ما يجب أن يقدّمه العامل (Worker)

يجب أن يأتي /toolchain/<version>/<file> من دلو R2 المسمى mokxi-toolchain (كائنات <version>/<file>)، مع Cache-Control طويل (المسار مُرقَّم بالإصدار، فالكائنات غير قابلة للتغيير) وContent-Encoding: br للـ wasm. يحتاج الرد إلى Content-Type: application/wasm وContent-Length: شريط تقدم اللوحة يقرأ الطول، وWebAssembly.compileStreaming يرفض أي شيء ليس application/wasm.

مكتبتا CMSIS وHAL من ST على لوحات STM32

لوحات Nucleo-F411RE وBlack Pill وBlue Pill تبني أيضًا الكود المكتوب بترويسات ST الرسمية: كود السجلات الذي يتضمن stm32f4xx.h (أو stm32f1xx.h، أو القديم stm32f10x.h) ومشاريع STM32CubeIDE المبنية على STM32Cube HAL. ملفات ST مضمّنة في firmware/stm32cube/ (راجع ملف README الخاص بها لمعرفة الإصدارات الأصلية والتراخيص) ويحزمها السكربت web/scripts/bundle-stm32cube.mjs في web/public/firmware/stm32cube/f4.json وf1.json، بحجم يقارب 0.47 و0.40 MB مع ضغط Brotli. وهي غير موجودة في حزم بيئة التشغيل ولا عند التحميل الأول للمحرر: يجلب الـ worker واحدة منها فقط عندما يتضمن المشروع إحدى ترويسات ST، أو ملف main.h غير متوفر لديه (wantsCube في src/compile/stm32cube.ts)، ثم يحتفظ بها طول عمر الصفحة.

يقرر cubePlan البقية، ويتبعه projectPlan:

  • تُوصَل الحزمة عند /stm32cube، وتُضاف أدلة التضمين الخاصة بها إلى المسار، مع -DSTM32F411xE أو -DSTM32F103xB، و-DUSE_HAL_DRIVER عند استخدام HAL، و-DUSE_FULL_LL_DRIVER عند استخدام LL، و-DMOKXI_ST_CMSIS، الذي يجعل ترويسة اللوحة الخاصة بوقت التشغيل تؤجل إلى ترويسة ST داخل الكود؛
  • وحدات HAL التي يفعّلها ملف stm32f?xx_hal_conf.h في المشروع، وملفات LL التي يتضمنها والملف النظامي، تُترجم مع الخيار -w وتُربط كأعضاء في مكتبة، لذا فإن أول بناء لـ HAL يترجم نحو اثني عشر ملفًا من ملفات ST (من 9 إلى 15 ثانية على wasm الخاص بـ clang-v2 في الاختبارات)، وأي بناء بعده يعيد استخدام كائناتها؛
  • المشروع الذي يحتوي على دالة main() خاصة به يُربط مباشرةً (bareMetalLinkInputs): كود بدء التشغيل الخاص ببيئة التشغيل وجدول المتجهات كما هما، وكل كائن آخر من بيئة التشغيل يصبح عضوًا في مكتبة، ويتولى mokxi_cube_bare.c توجيه printf() عبر _write() أو __io_putchar() الخاصتين بالمشروع. أما الكود فيحتفظ بنواة Arduino، ويجعل mokxi_cube_sketch.c نبضة HAL هي millis()؛
  • أي شيء ينقصه مشروع ملصوق يُكتب بالقيم الافتراضية من CubeIDE للوحة (main.h، وإعداد HAL، ومعالج SysTick، وملف MSP)، ولا يُضمّن ملف بدء التشغيل من ST ولا syscalls.c وsysmem.c من CubeIDE، وكل واحد منها يظهر كملاحظة في سجل البناء (ProjectPlan.notes)؛
  • المشروع الذي يستدعي طرفية غير موجودة في الشريحة المحاكاة (SPI أو I2C أو DMA أو RTC وغيرها) يحصل على ملاحظة تفيد بذلك؛ لكن البناء ينجح مع ذلك.

الشرائح المحاكاة لا تحتوي على واجهة flash ولا متحكم طاقة ولا منطقة bit-band، وHAL يكتب في الثلاثة جميعًا داخل HAL_Init() وفي كل SystemClock_Config() من CubeIDE. يضيف بانٍ الحزمة تضمينًا واحدًا إلى ترويسة الجهاز من ST (mokxi_cube_regs.h: يصبح FLASH وPWR ذاكرة RAM بنفس التنسيق) وواحدًا إلى stm32f?xx_hal.h (mokxi_cube_hal.h: تصبح كتابات bit-band في وحدات RCC الماكرو كتابات سجل عادية)؛ أما الملفات المضمّنة فتبقى دون تغيير. يبني src/compile/stm32cube.test.ts كل مثال في firmware/stm32cube/examples/ ويشغّله، و/learn/stm32-hal-register-code هي الصفحة المخصصة للمستخدمين.

الحدود

  • C و C++ ولغة التجميع (.S و.s، انظر أعلاه). لا MicroPython ولا أي لغة أخرى: فـ MicroPython الخاص بـ Pico وmain.py الخاص بـ Raspberry Pi يشغّلان صورة برنامج ثابت بدل المرور عبر هذا المسار.
  • المشروع مسطّح: أسماء الملفات لا تتضمن مجلدات، لذا يمتد مسار التضمين بعمق مجلد واحد.
  • اللوحة التي لا يذكر نص program في فهرسها أي عائلة لا تنتمي لأي عائلة أصلًا، فلا يجد familyFor شيئًا وتشغّل هذه اللوحة ملف ELF المُبنى مسبقًا. واللوحة التي عائلتها ليست ready تفعل الشيء نفسه، مع إظهار note العائلة في اللوحة.
  • لا تزال الزيارة التالية تدفع نحو 0.7 ثانية لاسترجاع 74 MB من Cache API وترجمتها. compileStreaming من Response مخزّن مؤقتًا هو ما يسمح للمحرك بإعادة استخدام مخزن الكود الخاص به، لكن لا شيء هنا يضمن ذلك قطعًا.
  • في بيئة التطوير يقدّم Vite سلسلة الأدوات من web/public/toolchain/؛ أما في الإنتاج فيقدّمها الـ Worker من R2. يجيب worker/assets.ts بـ 404 على /toolchain/ عمدًا، لذا يجب على الوسيط في التطوير داخل web/vite.config.ts أن يترك هذه البادئة كما هي. وهو يفعل ذلك، وكسر هذا الأمر هو ما ينتهي بالمترجم إلى تنزيل صفحة الـ 404.

الأسئلة

أين يحدث البناء؟

على جهازك، داخل تبويب المتصفح. لا يوجد خادم بناء، ولا طابور انتظار، ولا دقائق بناء.

ما حجم سلسلة الأدوات؟

نحو سبعين ميغابايت. تنزل مرة واحدة عبر البث ويخزّنها المتصفح مؤقتًا، لذا فبعد أول بناء يصبح كل شيء محليًا.