مهام البناء

يشتق elide build المهام من مجموعات المصادر والمُخرَجات في elide.pkl ويشغّلها بترتيب التبعيات. وتُتخطّى المهام التي لم تتغير مدخلاتها أو تُستعاد من ذاكرة التخزين المؤقت.

تشغيل البناء

elide build                   # run the default group
elide build compile-java-main # run one task
elide build compile           # run a group
elide build clean             # the clean target
elide build --inspect         # list tasks and their options without running

يسمّي الوسيط مهمة أو مجموعة مهام؛ والنقطتان في البداية (:compile-java-main) اختياريتان. والهدف الذي لا يطابق شيئًا يُفشل البناء.

المجموعة	الاسم البديل	المهام
`default`	—	ما يشغّله `elide build` دون وسائط.
`dependencies`	`deps`	حل التبعيات وتثبيتها.
`compilation`	`compile`	تصريف المصادر.
`testing`	`test`	الاختبارات؛ ويشغّلها `elide test` أيضًا.

تقبل بعض المهام خيارات يسردها --inspect:

elide build test --select=class:com.example.SomeTest
elide build run --args="a b c"

في مساحة العمل، ضع اسم المشروع بادئةً: core:compile-kotlin-main، أو core:compile، أو core لمهامه الافتراضية. تُحلّ الأهداف دون بادئة في المشروع الحالي، ثم في الجذر. ويجمّع --inspect المهام حسب المشروع، وتذكر أسطر التقدم اسمه ([core] Compiling Kotlin sources).

الخيارات

تُكتب الخيارات بالصيغة --name أو --name=value، في أي موضع بين الأهداف. والوسائط بعد -- تذهب إلى العملية التي تطلقها المهمة.

الخيار	التأثير
`--inspect`، `-i`	سرد المهام وخياراتها دون تشغيلها.
`--no-cache`	تجاهل ذاكرة التخزين المؤقت وحالة البناء المحلية؛ فتعمل كل المهام.
`--offline`	لا تنزيل للتبعيات ولا ذاكرة مؤقتة مشتركة.
`--workers=N`	`N` مهام متزامنة على الأكثر (الافتراضي: عدد المعالجات). الرمز `=` مطلوب.
`--insights=FILE`	تشغيل سكربت Insight في المهام التي تشغّل برامج؛ قابل للتكرار.
`-f NAME[=VALUE]`	خيار بناء يُقرأ عبر `build.flags`؛ راجع خيارات البناء.

تُفحص الخيارات مقابل المهام قبل تشغيل أي شيء. الخيار غير المعروف، أو القيمة المفقودة أو غير المتوقعة، أو الخيار المكرر، يؤدي إلى الفشل:

Unknown option '--worker', did you mean '--workers'?
Option '--workers' requires a value, as '--workers=<value>'

الخيارات العامة (-p و -v و --debug وغيرها) مستثناة. خيارات المهام: التبعيات، الاختبار.

ذاكرة البناء المؤقتة

المستوى المحلي مفعّل دائمًا: ~/.elide/cache/entries-v2، مجلد لكل مفتاح يحتوي على سجل وأرشيف tar للمخرجات. تُفحص عمليات الاستعادة مقابل البصمة المسجّلة. والإدخالات بصيغة أقدم تُعدّ إخفاقًا.

المستوى المشترك ذاكرة مؤقتة عبر HTTP، تُضبط بمتغيرات البيئة:

المتغير	المعنى
`ELIDE_REMOTE_CACHE`	عنوان URL لنقطة النهاية. إن لم يُضبط فلا مستوى مشترك.
`ELIDE_REMOTE_CACHE_TOKEN`	رمز Bearer؛ وله الأسبقية على المصادقة الأساسية.
`ELIDE_REMOTE_CACHE_USERNAME`، `ELIDE_REMOTE_CACHE_PASSWORD`	المصادقة الأساسية؛ وتعمل بيانات المستخدم في عنوان URL أيضًا.
`ELIDE_REMOTE_CACHE_PUSH`	رفع مخرجات هذا البناء (افتراضيًا `true`).
`ELIDE_REMOTE_CACHE_PULL`	تنزيل ما لم يُعثر عليه محليًا (افتراضيًا `true`).
`ELIDE_REMOTE_CACHE_POLICY`	ينقل `eager` (الافتراضي) كل إدخال؛ وينقل `smart` فقط حين يوفّر ذلك الوقت.

يُفحص المستوى المحلي أولًا؛ وتُخزَّن الإصابات البعيدة محليًا.
الإعداد المعتاد: يرفع CI المخرجات؛ ويضبط المطورون ELIDE_REMOTE_CACHE_PUSH=false.
الإدخالات البعيدة غير القابلة للوصول أو البطيئة أو غير المقروءة تُعدّ إخفاقات. وثلاثة أعطال نقل متتالية توقف المستوى لبقية البناء. أخطاء HTTP مثل 404 ليست أعطال نقل؛ وبيانات الاعتماد المرفوضة تُظهر تحذيرًا واحدًا.
يفشل البناء عند عنوان URL ليس http/https، أو كلمة مرور دون اسم مستخدم، أو قيمة PUSH/PULL ليست منطقية (boolean)، أو بيانات اعتماد عبر http غير مشفّر إلى مضيف غير محلي (loopback).
تقدّم الذاكرة المؤقتة مخرجات قابلة للتنفيذ: استخدم https، واشترط المصادقة للكتابة، وقيّد من يمكنه الكتابة.
يوقف --offline المستوى المشترك لتشغيل واحد؛ ويوقف --no-cache التخزين المؤقت.

الملف `.eliderc` والسياسة `smart`

مع smart، لا يُنزَّل الإدخال إلا إذا كان ذلك أرخص من إعادة البناء، ولا يُرفع إلا إذا كانت كلفة الرفع أقل من العمل الذي يوفّره. تأتي الكلفة من .eliderc (بصيغة java.util.Properties): ~/.eliderc، ثم <project>/.eliderc فوقه. يصف الملف الجهاز، فلا تُدرجه في المستودع.

# ~/.eliderc
network.downlink = 200mbps
network.uplink = 20mbps
network.latency = 250ms
network.stability = good        # good | fair | poor
machine.compute = fast          # slow | normal | fast, or a multiplier such as 1.5

cache.remote.policy = smart     # smart | eager (default)
cache.remote.upload-budget = 2.0
cache.remote.min-build = 500ms  # work cheaper than this is never published

الوحدتان Mb/s و mbps بالميغابت؛ و MB/s بالميغابايت. القيم غير المقروءة تُظهر تحذيرًا وتُستخدم القيمة الافتراضية. يتجاوز ELIDE_REMOTE_CACHE_POLICY القيمة cache.remote.policy. ومع eager لا أثر للملف.

حالة البناء

الملف	الدور
`.dev/elide.lock.v2.bin`	بصمات محمولة لكل مهمة، قابلة للمشاركة بين الأجهزة. ليس ملف قفل للتبعيات.
`.dev/elide.build.bin`	بصمات لكل مهمة خاصة بالجهاز المحلي.
`.dev/elide.filehash.bin`	ملخصات الملفات مفهرسة بالحجم والأوقات و inode والوضع، كي لا تُعاد قراءة الملفات التي لم تتغير.

ملفات ثنائية؛ لا تعدّلها.
لا يوجد ملف قفل للتبعيات يشمل كل المنظومات؛ ويكتب npm الملف aube-lock.yaml.
في مساحة العمل، تُخزَّن حالة كل الأعضاء في .dev/ الخاص بالجذر؛ وتبقى المخرجات في .dev/ الخاص بكل مشروع.
يتجاهل --no-cache ملف الحالة المحلي، لكنه يظل يقرأ الملف المشترك.
يعيد elide install استخدام نتيجة الحل ما دامت قائمة التبعيات لم تتغير؛ ويعيد --fresh تنزيل كل تبعية، مع تحديث ذاكرة التخزين المؤقت العامة.
تُكتب وسائط كل مُصرّف بجوار مخرجاته في <tool>.args، وسيط في كل سطر.

قياس وقت البناء

تطبع كل مهمة مدتها. لمزيد من التفاصيل:

elide build -v                                                # everything, at debug
ELIDE_LOG=dev.elide.tooling.build.telemetry=debug elide build # only the timings

[debug] dev.elide.tooling.build.telemetry stage graph took 590us
[debug] dev.elide.tooling.build.telemetry op compile-kotlin-main · up-to-date (up-to-date) took 420us
[debug] dev.elide.tooling.build.telemetry task compile-kotlin-main (skipped: up-to-date) took 12.6ms

المقاطع إما مرحلة (الإعداد، المخطط، التنفيذ، حفظ الحالة)، أو مهمة، أو عملية على مهمة (prepare، fingerprint، up-to-date، execute، وعمليات البحث والتخزين في الذاكرة المؤقتة). ولا يُفصَّل العمل داخل execute.

يكتب ELIDE_BUILD_TELEMETRY عند انتهاء البناء ملف تتبّع Chrome محليًا؛ ولا يُرفع أي شيء:

ELIDE_BUILD_TELEMETRY=1 elide build             # .dev/telemetry/build-<stamp>.trace.json
ELIDE_BUILD_TELEMETRY=profile.json elide build  # a file you name
ELIDE_BUILD_TELEMETRY=/tmp/traces elide build   # a directory you name

افتحه في Perfetto أو chrome://tracing أو speedscope، أو:

jq -r '.traceEvents[] | select(.ph=="X") | "\(.dur/1000 | floor)ms \(.cat) \(.name)"' \
  .dev/telemetry/build-*.trace.json | sort -rn | head