# البيئة والخصائص

يحمّل Elide ملفات `.env` كقيم افتراضية لبيئة التطبيق، وملفات `.properties` كقيم افتراضية لخصائص نظام Java. لا يحتاج
التطبيق إلى أي مكتبة dotenv. ويدعم التنسيقان القيم المشفّرة المتوافقة مع dotenvx.

> [!NOTE] متاح في Elide 1.6.2
> يصف هذا الدليل دعم سياق التشغيل في Elide 1.6.2.

## تحميل الإعدادات

أنشئ `.env` في الدليل الذي تستدعي منه ⁦Elide:⁩

```dotenv
APP_NAME=greeter
APP_PORT=8080
APP_MESSAGE="Hello from ${APP_NAME}"
```

أنشئ `app.ts`:

```typescript
console.log(process.env.APP_MESSAGE);
console.log(process.env.APP_PORT);
```

```sh
elide run app.ts
```

```text
Hello from greeter
8080
```

لمتغير البيئة الموروث الأسبقية، حتى لو كانت قيمته فارغة:

```sh
APP_PORT=9090 elide run app.ts
APP_PORT= elide run app.ts
```

يتلقى الاستدعاء الثاني `APP_PORT` فارغًا بدلًا من `8080`. اقرأ متغيرات البيئة عبر
[`process.env`](/docs/env-variables)، أو `os.environ` في Python، أو واجهة البيئة الخاصة بلغتك.
تتلقى العمليات الفرعية البيئة الفعلية أيضًا. عندما تُرشِّح سياسة بيئة المتغيرات الموروثة، لا ترث عمليات Java المُطلقة
ومهام المشروع وعمليات Node الفرعية إلا اللقطة المسموح بها. تُطبَّق إدخالات البيئة الصريحة للمهمة أو لـ JVM بعد ذلك؛
وتحلّ خريطة `env` صريحة لعملية Node فرعية محل الوراثة. لا يمنح تحميل الملفات قدرات إضافية في البيئة المعزولة
ولا يوسّع وصول ملف البيان إلى البيئة؛ وتظل ضوابط `--allow-env` الحالية سارية.

## الاكتشاف التلقائي للملفات

في كل دليل محدد، يقرأ Elide هذه الملفات بالترتيب:

| الإعداد | أولًا | ثانيًا، ويتجاوز الأول |
| --- | --- | --- |
| البيئة | `.env` | `.env.local` |
| خصائص Java | `.properties` | `.properties.local` |

تُتجاهل الملفات التلقائية المفقودة. أما الملفات الموجودة التي تتعذر قراءتها أو تحليلها فتسبب خطأ. التنسيقان منفصلان:
متغير البيئة المسمى `app.mode` لا يضبط خاصية Java `app.mode`.

افتراضيًا، لا يفحص المشغّل إلا دليل الاستدعاء. ولا يغيّر موقع السكربت ذلك الدليل.
تشغيل `elide run services/api/app.ts` لا يحدد `services/api/.env` تلقائيًا.

مع `--project PATH`، يحدد Elide دليل المشروع ذاك، أو الدليل الأب عندما يشير `PATH` إلى ملف البيان الخاص به.
يحمّل أولًا الأدلة المحيطة التي تحتوي على `elide.pkl`، من الأبعد إلى الأقرب، ثم الدليل المحدد. وفي كل دليل، يأتي
الملف المحلي بعد الملف الأساسي. والأدلة اللاحقة تتجاوز السابقة. لا تساهم الأدلة الأسلاف العشوائية ولا الدليل المنزلي
ولا أعضاء مساحة العمل غير المرتبطين في إعدادات المشغّل.

```sh
elide --project services/api run app.ts
```

تستخدم مهام المشروع أيضًا طبقات البيئة المحيطة وطبقة مساحة العمل وطبقة العضو. حدّد المشروع صراحةً عندما يجب أن
تكون إعداداته المحيطة متاحة عند البدء. راجع [إعداد المشروع](/docs/projects).

لا يحدد Elide تلقائيًا `.env.production` أو `.env.test` أو `.properties.production` أو أسماء مشابهة.
ولا تحدد `NODE_ENV` ولا ملفات تعريف التنفيذ المسماة ولا ملفات تعريف dotenvx ملفات الإعداد. اختر هذه الملفات
صراحةً.

## اختيار الملفات صراحةً

يحل `--env-file` محل الاكتشاف التلقائي لملفات dotenv. ويحل `--properties-file` بشكل مستقل محل الاكتشاف التلقائي
لملفات الخصائص. كرّر أيًّا من الخيارين لتكديس الملفات؛ وعند تكرار الأسماء تفوز الوسائط اللاحقة.
المسارات نسبية إلى دليل الاستدعاء، حتى عند تمرير `--project`.

```sh
elide --env-file .env --env-file .env.production run app.ts
elide --properties-file config/base.properties --properties-file config/production.properties run Main.java
elide --env-file config/service.env --properties-file config/service.properties run Main.java
```

الملفات الصريحة إلزامية: الملف المفقود خطأ. اختيار `.env.production` وحده لا يحمّل معه `.env` أو `.env.local`.
أدرج كل ملف تريده.

| الخيار | الأثر |
| --- | --- |
| `--no-env` | يعطّل تحميل dotenv. تبقى متغيرات البيئة الموروثة متاحة. |
| `--no-properties` | يعطّل تحميل ملفات الخصائص. |
| `--no-env --no-properties` | يعطّل نوعي تحميل الملفات كليهما. |

```sh
elide --no-env --no-properties run app.ts
```

الجمع بين `--no-env` و `--env-file`، أو بين `--no-properties` و `--properties-file`، خطأ في الاستخدام.
يمكنك تعطيل تنسيق مع اختيار ملفات للتنسيق الآخر صراحةً.

تحترم عمليات تشغيل ملفات مصدر Java المستقلة أيضًا اختيارات الملفات الصريحة و `--no-env` و `--no-properties`
دون إعادة اكتشاف الملفات التلقائية.

## الأسبقية

أسبقية البيئة، من الأدنى إلى الأعلى:

1. ملفات dotenv المحددة، بترتيب الاكتشاف أو الوسائط.
2. بيئة العملية الموروثة، بما فيها القيم الفارغة.
3. تعيينات البيئة الصريحة لمهمة أو عملية فرعية معينة، ضمن نطاق ذلك التنفيذ.

أسبقية خصائص Java، من الأدنى إلى الأعلى:

1. ملفات الخصائص المحددة، بترتيب الاكتشاف أو الوسائط.
2. تعيينات JVM بـ `-D` التي يمررها المشغِّل عندما يعمل Elide على JVM موجودة.
3. تعيينات الخصائص الصريحة في واجهة سطر أوامر Elide، مثل `--vm app.mode=production`.

القيم الافتراضية للخصائص التي توفرها VM لا تُعد تعيينات من المشغِّل. تتلقى التطبيقات الخصائص قبل تهيئتها.
وتتلقى عمليات تشغيل Java الفرعية القيم الافتراضية لخصائص التطبيق قبل وسائط JVM الصريحة الخاصة بها.
تعمل المهمة ذات خصائص VM المختلفة في VM منفصلة؛ ولا تغيّر خصائصها الحالة العامة لمحرّك البناء.

## صياغة dotenv

تدعم ملفات dotenv التعليقات، والقيم بين علامات الاقتباس، والقيم متعددة الأسطر، والقيم الفارغة، والاستيفاء `${NAME}`.
تحافظ علامات الاقتباس المفردة على المحتوى حرفيًا. وتسمح علامات الاقتباس المزدوجة بالاستيفاء.

```dotenv
# Application defaults
APP_NAME=greeter
APP_MESSAGE="Hello from ${APP_NAME}"
APP_LITERAL='${APP_NAME}'
APP_EMPTY=
APP_MULTILINE="first line
second line"
APP_COMMAND='$(echo hello)'
```

`APP_LITERAL` هي السلسلة الحرفية `${APP_NAME}`. و `APP_COMMAND` هي السلسلة الحرفية `$(echo hello)`؛
لا ينفّذ Elide استبدالات أوامر الصدفة في ملفات الإعداد.

يحدث الاستيفاء أثناء تحليل كل ملف. ويمكنه استخدام المتغيرات الموروثة والتعيينات السابقة في الملف نفسه. ولا يُعاد
تشغيله بعد أن تتجاوز ملفات لاحقة القيم. إذا عرّف `.env` القيمتين `APP_NAME=greeter` و
`APP_MESSAGE="Hello from ${APP_NAME}"`، ثم غيّر `.env.local` القيمة `APP_NAME` إلى `api`، فستبقى الرسالة
`Hello from greeter`. لا تعتمد على الاستيفاء عبر ملفات منفصلة.

## خصائص Java

لتطبيقات Java أو Kotlin، أنشئ `.properties`:

```properties
app.name=greeter
app.message=Hello world
app.empty=
app.multiline=first\
  second
app.unicode=\u263A
app.literal=${APP_NAME}
```

اقرأها باستخدام `System.getProperty("app.name")` في Java أو Kotlin. على سبيل المثال، احفظ `Main.java`:

```java
class Main {
  public static void main(String[] args) {
    System.out.println(System.getProperty("app.message"));
  }
}
```

```sh
elide run Main.java
elide --vm app.message="Hello from the CLI" run Main.java
```

يطبع الاستدعاء الأول `Hello world`؛ ويطبع الثاني `Hello from the CLI`.
قيمة `app.multiline` هي `firstsecond`؛ وقيمة `app.unicode` هي `☺`؛ وتبقى `app.literal` بالقيمة `${APP_NAME}`.

تستخدم الخصائص صياغة ⁦Java:⁩ تعليقات `#` و `!`، والفواصل المهرَّبة، وأسطر الاستمرار، وتهريبات `\uXXXX`.
علامات الاقتباس جزء من القيمة، وليست اقتباس dotenv. لا تستوفي الخصائص تعابير dotenv ولا تنفّذ أوامر. للمحتوى غير
ASCII القابل للنقل، استخدم تهريبات Unicode؛ إذ يفك قارئ الخصائص ترميز البايتات بترميز Windows-1252.

يجب ألا تكون أسماء الخصائص فارغة وألا تحتوي على NUL أو `=`. يمكن أن تحتوي القيم على `=` لكن ليس على NUL.
نطاقات أسماء الخصائص `java.*` و `elide*` و `org.graalvm*` مقيّدة، باستثناء `elide.diag.*`.
لا يتجاوز التشفير هذه القيود. وتتبع إعدادات `polyglot.*` مسار خيارات المحرّك.
استخدم خيارات VM في واجهة سطر الأوامر لإعدادات مثل حجم الذاكرة المكدسة (heap)؛ فملف الخصائص ليس ملف وسائط JVM.

عندما يعمل Elide على JVM بدأت بالفعل، يوفّر تحميل الملفات طبقات بيئة للتطبيقات والعمليات الفرعية. ولا يعيد كتابة
`System.getenv()` في تلك JVM ولا يغيّر إعدادات بدئها بأثر رجعي.

## القيم المشفّرة

يفك Elide تشفير قيم `encrypted:` المتوافقة مع dotenvx في ملفات dotenv وخصائص Java. يمكن أن تظهر القيم النصية
الصريحة والمشفّرة في الملف نفسه، وتتبع قواعد الأسبقية نفسها. القيمة المشفّرة التي تحل محلها قيمة صريحة لاحقة، أو
قيمة بيئة موروثة، لا تحتاج إلى مفتاح فك تشفير.

استخدم أداة تشفير متوافقة لإنشاء النص المشفّر. يتولى Elide فك التشفير عند تحميل الإعدادات؛ ولا يوفّر أمر تشفير.
على سبيل المثال، مع تثبيت ⁦dotenvx:⁩

```sh
dotenvx encrypt -f .env.production
elide --env-file .env.production run app.ts
```

اختر تخزين `.env.keys` المحلي في dotenvx عند السؤال. يحتفظ
[مسار التشفير](https://dotenvx.com/docs/custody/env-keys/) الخاص به بالنص المشفّر في ملف dotenv المحدد ويكتب
المفتاح الخاص في `.env.keys`. بالنسبة إلى `.env.production`، يُسمى المفتاح `DOTENV_PRIVATE_KEY_PRODUCTION`.
لا يزال Elide يتطلب `--env-file .env.production`؛ فلاحقة المفتاح لا تحدد الملف.

### توفير المفاتيح الخاصة

يقبل Elide المتغيرات الموروثة `DOTENV_PRIVATE_KEY` و `DOTENV_PRIVATE_KEY_*` ذات اللاحقة، أو المفاتيح في `.env.keys`
بجوار مصادر الإعداد المحددة. وتتشارك البيئة والخصائص البحث نفسه عن المفاتيح.

1. يفحص Elide `.env.keys` بجوار مصادر dotenv المحددة، ثم بجوار مصادر الخصائص المحددة، بترتيب المصادر.
   يُفحص كل دليل مرة واحدة؛ وتحل التعيينات اللاحقة في ملفات المفاتيح محل السابقة التي تحمل الاسم نفسه.
2. تتجاوز تعيينات `DOTENV_PRIVATE_KEY*` الموروثة الأسماء المطابقة من ملفات المفاتيح.
3. تُجرَّب المفاتيح المتاحة على القيم المشفّرة الفعلية. ولا تقصر لاحقة المفتاح فك التشفير على اسم ملف إعداد
   معين.

لا تُقرأ ملفات المفاتيح إلا عندما تحتاج قيمة مشفّرة فعلية إلى فك التشفير. والتشغيل بقيم صريحة فقط لا يتطلب
`.env.keys`. ولا يبحث العثور على المفاتيح في الأدلة الأسلاف العشوائية ولا في دليلك المنزلي.

في CI، احقن متغير المفتاح الخاص المطابق عبر مخزن أسرار CI، ثم شغّل Elide كالمعتاد:

```sh
# DOTENV_PRIVATE_KEY_PRODUCTION is supplied by the CI environment.
elide --env-file .env.production run app.ts
```

أبقِ `.env.keys` خارج التحكم بالإصدارات، واحتفظ بنسخة احتياطية منه بشكل منفصل، وقيّد الوصول إلى الملف.
راجع الإعدادات قبل حفظها في المستودع: تشفير بعض القيم لا يعني أن كل القيم مشفّرة.
تجنّب طباعة أسرار التطبيق أو تمرير المفاتيح الخاصة حرفيًا في أوامر الصدفة والسجلات.

تُستخدم إدخالات `.env.keys` لفك التشفير فقط؛ ولا تُضاف إلى إعدادات التطبيق.
إدخالات `DOTENV_PUBLIC_KEY*` في ملفات الإعداد بيانات وصفية وتُحذف من قيم التطبيق المحمّلة.
وضع تعيينات `DOTENV_PRIVATE_KEY*` في ملف dotenv أو ملف خصائص للتطبيق خطأ.
تظل متغيرات المفاتيح الخاصة الموروثة خاضعة لقواعد الظهور المعتادة للبيئة الموروثة.

### خصائص Java المشفّرة

يمكن أن تحتوي خاصية Java على قيمة نص مشفّر متوافقة دون علامات اقتباس:

```properties
app.secret=encrypted:...
```

علامة الحذف عنصر نائب للنص المشفّر الفعلي، وليست قيمة مشفّرة صالحة. يحلل Elide خصائص Java أولًا، ثم يفك تشفير
القيمة المفكوكة الترميز بالمفاتيح نفسها المستخدمة مع dotenv. لا تفترض أن واجهة سطر أوامر dotenvx تستطيع تحليل ملفات
خصائص Java أو إعادة كتابتها. يُستخدم النص المفكوك التشفير كقيمة: لا يُعاد تحليله كإعدادات، ولا يُستوفى، ولا يُنفَّذ.

## الأوامر والاختبارات والأخطاء

ينطبق التحميل التلقائي على `run` و `serve` و `dev` و `install` و `build` و `test` و `project` و `classpath`
و `publish` و `java` و `python` و `repl` والتنفيذ المباشر للملفات. تتخطى أوامر المساعدة والإصدار والإكمال التلقائي
والأوامر الإدارية غير المرتبطة الاكتشاف التلقائي للإعدادات. ولا تحمّل أوامر الأدوات مثل `javac` و `kotlinc` هذه
الملفات تلقائيًا. وتطلب خيارات الملفات الصريحة تحميل الإعدادات في الأوامر التي تصل إلى مشغّل التطبيق.

للاختبارات القابلة لإعادة الإنتاج، اختر الملفات صراحةً أو عطّل التنسيقين كليهما:

```sh
elide --env-file .env.test --no-properties test
elide --no-env --no-properties test
```

لا تمسح هذه الخيارات متغيرات البيئة الموروثة. اضبطها أو أزلها بشكل منفصل في مشغّل الاختبارات.
يحتفظ الاستدعاء المحلول بلقطة إعداداته؛ ابدأ استدعاءً جديدًا لالتقاط الملفات أو المفاتيح المعدّلة.

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

للمتغيرات التي تضبط Elide نفسه، راجع [متغيرات بيئة التشغيل](/docs/runtime-env-variables).
ولتفاصيل الخيارات، راجع [مرجع سطر الأوامر](/docs/cli-references).