تُترجم ملفات اللوحة بواسطة 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):
- لا يملك
clang-v2واجهة خلفية لـ Xtensa. بُني باستخدامLLVM_TARGETS_TO_BUILD=RISCV;AVR;ARM(DECISIONS.md بتاريخ 2026-09-14). ملف wasm الذي ينزّله المتصفح عاجز فعليًا عن إنتاج ملف Xtensa. - يملك 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الإصدار الأصلي. - 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,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).
إذًا هذا 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,rainbowandusbserialincluded) 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 insideL32R'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 الأمثلة به، فالزيادة لا تكلّف شيئًا يلاحظه كودٌ هنا. أما إلى أين تذهب البايتات فلم يُفصَّل.
منشور ومُتحقَّق منه
- بُني بواسطة
.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. - نُشر في 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 كان سيوفّر معظم حجم ذلك التنزيل. - جرى الفحص في 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الخاص بسير العمل. - كشف فحص 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). - الفاصلة العائمة ناعمة (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نفسه.
الخطوات التالية
- تقرير ما إذا كانت كل العائلات تنتقل إلى 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واختبارات المكتبات المرفقة عليه أولًا، ولا تفترض مخرجات متطابقة بايتًا بايتًا. - فحص المكتبات المرفقة على عائلات Xtensa. المجلد
firmware/libموجود في مسار التضمين كما في كل لوحة، لكنstock-libraries.test.tsلا يذكرها، لذا فإنServo.hوWire.hوغيرهما غير مختبرة هناك. - تقليم
bundle.jsonإلى الترويسات التي يفتحها بناء freestanding.
لا تدّعِ أبدًا وجود ترجمة في المتصفح لا تعمل: زر بناء يشغّل بصمت ملفًا ثنائيًا من الأمس سيكون أسوأ شيء في هذا المنتج.
clang-rv32-v1 لا يزال قيمة RV32_TOOLCHAIN ولا تذكره أي عائلة. يبقى كطريق للرجوع: تغيير سلسلة toolchain الخاصة بعائلة هو كل ما في نشر بناء أو التراجع عنه، إذ إن العناوين ومفتاح تخزين الوحدات ومخزن كائنات بيئة التشغيل كلها تتعلق به.
ready ليس كودًا ميتًا أيضًا. يجب أن يتحقق أمران قبل أن تحمله عائلة، ويختبر bundles.test.ts الأمر الثاني منهما:
- أن سلسلة الأدوات تملك الواجهة الخلفية، وأنها منشورة، وأن كودًا بنته قد شُغّل على المحاكي.
- أن العائلة تملك حزمة بيئة تشغيل، أي أن مجلد البرامج الثابتة الخاص بها موجود وأن
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 (اكتُشفا كلاهما في الإثبات):
-c crt0.Sيجعل clang يحتاج إلى مهمتين، معالجة أولية وتجميع، وclang يطفئ وحدته المدمجة cc1 بمجرد وجود أكثر من واحدة، وعلى WASI يكون ذلك "unable to execute command: WASI does not support spawning subprocesses". يُدرَج النصفان كلٌّ على حدة.- يتم الربط عبر
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/:
- الخطة. يضيف
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. - فحوصات المعاملات. يقرأ
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). - الربط، حين لا يوجد كود.
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. - الفاكّ (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.