# مهام البناء

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

## تشغيل البناء

```bash
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
elide build jvm-test --help   # one task's options and what they mean
elide build --no-cache        # ignore cached results and build state
elide build --offline         # no network: no dependency fetches, no shared cache
elide build --workers=4       # run at most four tasks at once
```

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

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

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

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

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

يمكن للمشروع إضافة مجموعاته ومهامه الخاصة، بما فيها مهام تعمل قبل المهام المدمجة؛ راجع
[امتدادات البناء](/docs/toolchain/build-extensions).

## الخيارات

تُكتب الخيارات بالصيغة `--name` أو `--name=value`، في أي موضع بين الأهداف. والوسائط بعد `--` تذهب إلى العملية التي
تطلقها المهمة.
يعرض `--inspect` خيارات جميع المهام؛ ويصف `elide build <task> --help` خيارات مهمة واحدة.

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

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

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

الخيارات العامة (`-p` و `-v` و `--debug` وغيرها) مستثناة. خيارات المهام:
[التبعيات](/docs/toolchain/dependencies#maven-options)، [الاختبار](/docs/toolchain/testing#options).

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

المستوى **المحلي** مفعّل دائمًا: `~/.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` فوقه.
يصف الملف الجهاز، فلا تُدرجه في المستودع.

```properties
# ~/.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`، وسيط في كل سطر.

راجع [دليل ⁦.dev⁩](/docs/toolchain/development-directory) للملفات المولدة ومسارات مساحات العمل والتنظيف.

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

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

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

```text
[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](https://perfetto.dev/docs/visualization/large-traces)
محليًا؛ ولا يُرفع أي شيء:

```bash
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](https://ui.perfetto.dev) أو `chrome://tracing` أو [speedscope](https://speedscope.app)، أو:

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

### ملاحظات الاستعادة وربط الجلسات

قد تعيد الخوادم التي تدعم إيصالات استعادة Elide الرأس `x-elide-recall-receipt` عندما يطلب تنزيل الأرشيف
`x-elide-recall: 1`. بعد الاستخراج والتحقق، يبلّغ العميل النتيجة إلى `outcomes` تحت نقطة نهاية الذاكرة المؤقتة
المهيأة. تنزيل البايتات وحده لا يُعد استعادة ناجحة؛ ولا تكرر الإصابات المحلية اللاحقة الملاحظة.
يجري الإبلاغ بأفضل جهد ولا يقرر نجاح البناء.

يوفر `ELIDE_STUDIO_SESSION_ID` بيانات وصفية محدودة لربط الطلبات إلى ذاكرة البناء المؤقتة المهيأة ومصدر
Maven Pkgst عبر HTTPS. ليس بيانات اعتماد ولا يغيّر مفاتيح الإجراءات. لا تتبع طلبات الذاكرة المؤقتة المصادَق
عليها أو المرتبطة بجلسة إعادة التوجيه، لمنع تسرب البيانات الوصفية إلى مصدر آخر.

تتضمن التقارير مدة المهمة الأصلية كتقدير محدود، ليقارن الخادم تكلفة إعادة البناء المحتملة بتكلفة الاستعادة
المقاسة. هذا التقدير ليس قياسًا للفوترة ولا دليلًا على الوقت الموفر.
