مرجع elide.pkl

الملف elide.pkl هو ملف بيان المشروع: تُعلَن فيه عمليات البناء والتبعيات والاختبارات والمُخرَجات. يبدأ كل ملف بما يلي:

amends "elide:project.pkl"

تشير البادئة elide: إلى المخطط المضمّن في Elide قيد التشغيل، في هذه الوحدة وفي كل وحدة أخرى (elide:Jvm.pkl). لتحديد إصدار المخطط، وسّع الرابط المنشور بدلًا منها: pkl.elide.dev/1.6.0/project.pkl.

يتبع الإصدار قيد التطوير الفرع main حتى صدوره المستقر. إصدارات المخطط المنشورة لا تتغير.

لا تضيف إصدارات التصحيح ضمن الخط MAJOR.MINOR إلا خصائص جديدة. أما الإصدار الثانوي فقد يزيل الخصائص أو يعيد تسميتها أو يغيّر أنواعها، وقد يغيّر القيم الافتراضية.

يطبع الأمر elide project export ملف البيان بعد تقييمه بصيغة JSON، ويسرد elide build --inspect مهامه.

البيانات الوصفية للمشروع

تحمل الخاصية build.flags قيم -f/--flag؛ راجع خيارات البناء.

سياقات المحرك

engine {
  topology = "prespawn"
  contexts { spawn = "auto"; reserve = 2; min = 1; max = 16 }
}

يقيّم كل سياق وحدة الدخول مرة واحدة، بكائناته العامة الخاصة به، قبل أن يصبح الخادم جاهزًا. يتجاوز الخيار --contexts=N|auto في run و serve و dev قيمة spawn. ويتطلب أكثر من سياق واحد نظام Linux.

كتلة OpenTelemetry

opentelemetry {
  service { name = "checkout"; version = "1.4.2"; environment = "production" }
  resource { ["cloud.region"] = "us-east-1" }

  destinations {
    ["collector"] { endpoint = "http://localhost:4317"; protocol = "grpc" }
    ["datadog"] { provider = "datadog"; site = "us5" }
    ["sentry"] { provider = "sentry" }
  }

  traces { sampler = "parentbased_traceidratio"; ratio = 0.25 }
  metrics { interval = 30.s }
  logs { level = "info" }
  runtime { logs = "warn" }
}

يبقى القياس عن بُعد معطّلًا حتى تُعرَّف وجهة هنا، أو في متغيرات OTEL_*/ELIDE_OTEL_*، أو في خيارات --otel-*. وتتجاوز هذه كلها الكتلة، والأولوية للخيارات؛ راجع متغيرات بيئة التشغيل. تقرأ الأوامر elide run و elide serve و elide test و elide build و elide install هذه الكتلة داخل المشروع، ويقرؤها elide run file.js داخل المشروع إذا احتوى elide.pkl على الكلمة opentelemetry. راجع التهيئة. لا تُكتب بيانات الاعتماد هنا أبدًا: سمِّ متغير البيئة الذي يحملها.

كل وجهة:

تُرسل الأخطاء سجلاتٍ من نوع exception وأحداثًا في نطاقات التتبع، إضافة إلى المقياس elide.errors، فيستقبلها كل مزوّد يقبل السجلات أو التتبعات أو المقاييس. راجع نظرة عامة على OpenTelemetry للاستخدام، و المزوّدون لتفاصيل كل مزوّد. وطلب إشارة أو بروتوكول لا يقبله المزوّد خطأ.

Baggage

يمرّر خادم HTTP وعملاء Elide الترويستين traceparent و tracestate. أما ترويسة W3C baggage فلا يمرّرونها إلا إذا فعّلت اتجاهًا لها، لأن الـ baggage القادمة من العميل مدخلات غير موثوقة:

opentelemetry {
  propagation {
    baggage {
      inbound = true
      outbound = true
      allow { "tenant"; "region" }
      spanAttributes { "tenant" }
    }
  }
}

تُسقط الترويسة كاملةً إذا تجاوزت 8,192 بايت أو 180 عضوًا، أو احتوت على عضو تالف. ولا تصل الـ baggage المستلمة من عميل إلى الطلبات الصادرة إلا إذا فُعّل الاتجاهان. ويمكن لشيفرة التطبيق دائمًا قراءة الـ baggage وضبطها وإرسالها عبر واجهة OpenTelemetry البرمجية؛ ولا يؤثر OTEL_PROPAGATORS إلا في تلك الواجهة.

المصادر

sources {
  ["main"] = "lib/**/*.kt"
  ["integrationTest"] {
    type = "test"
    dependsOn { "main" }
    paths { "it/**/*.kt" }
    resources { "it/fixtures"; new { from = "it/config"; into = "META-INF" } }
  }
}

راجع مجموعات المصادر.

التبعيات

dependencies {
  maven {
    packages { "com.google.guava:guava:33.5.0-jre" }
    testPackages { "org.junit.jupiter:junit-jupiter:5.13.4" }
    substitutions { ["com.google.guava:guava"] = "libs/guava-patched.jar" }
  }
  npm { packages { "react@19.0.0" }; devPackages { "typescript@5.6.2" } }
  pypi { packages { "requests>=2" }; optionalPackages { ["dev"] { "pytest>=8" } } }
  spring { version = "4.0.0"; starter { "web" }; testStarter { "test" } }
}

يحتفظ الاستبدال بالتبعيات المتعدية للإحداثية ويضع الملف مكانها في كل classpath. تُحَل المسارات نسبةً إلى ملف البيان الذي يعلنها، ويرث الأعضاء استبدالات الجذر. رتّب المهمة التي تولّد الملف لتُنفَّذ أولًا. الفئات والمستودعات: التبعيات.

JVM

jvm {
  main = "example.Main"
  target = 25
  flags { "--add-opens=java.base/java.lang=ALL-UNNAMED" }
  defs { ["app.env"] = "dev" }
  java { release = 25; compiler { flags { "-Xlint:all" } } }
}

Kotlin

kotlin {
  apiLevel = "auto"
  languageLevel = "auto"
  compilerOptions { allWarningsAsErrors = true; optIn { "kotlin.time.ExperimentalTime" } }
  features { serialization = true; metro = false }
  toolchain = "embedded"
  plugins { ["org.jetbrains.kotlinx.serialization"] { ["mode"] = "json" } }
}

القيم الافتراضية: مُصرّف Kotlin.

JavaScript

سلسلة الأدوات

toolchain { engines { ["elide"] = ">=1.6.0" } }

التطوير

dev {
  source { platform = "github"; project = "example/app" }
  mcp {
    registerElide = true
    advice = true
    resources { new { path = "docs/ARCHITECTURE.md"; name = "architecture" } }
  }
}

الويب

راجع سلسلة أدوات الويب.

المُخرَجات

import "elide:Jvm.pkl" as Jvm

artifacts {
  ["app"] = new Jvm.Jar {
    name = "app.jar"
    options { entrypoint = "example.Main" }
    sources { "main" }  // optional; empty packages every non-test source set
  }
}

يحدد المفتاح اسم مهمة البناء. وتُكتب المخرجات تحت .dev/artifacts/<kind>/.

WebImage

يأخذ WebImage حقول NativeImage وهي from و name و entrypoint و moduleName و dependsOn و options، ولا يملك type، ويضيف:

الحقل entrypoint (أو jvm.main) مطلوب حتى مع autoRun = false. لا تمرّر خيارات خام لهذه الإعدادات الأربعة. الدليل: WebImage؛ والمُخرَجات المبنية بالخيارات: الترحيل.

النشر

publishing {
  maven {
    groupId = "dev.example"
    artifactId = "example"                 // default: the project name
    localRepository = "~/.m2/repository"   // the default
    artifacts { "lib"; "lib-sources" }      // default: every Jar, SourceJar and JavadocJar
    pom {
      name = "Example"
      description = "An example library."  // default: the project description
      url = "https://example.dev"
      licenses { new { name = "Apache-2.0"; url = "https://www.apache.org/licenses/LICENSE-2.0" } }
      developers { new { id = "jdoe"; name = "J. Doe" } }
      scm { url = "https://github.com/example/example" }
    }
    repositories {
      ["internal"] = "https://repo.example.dev/releases"  // or new Jvm.MavenRepositorySpec { url = … }
      ["central"] = new Publishing.CentralPortal {}       // Maven Central; import "elide:Publishing.pkl" as Publishing
    }
    signing { gpg { keyName = "0123ABCD" } }  // optional; omit keyName for gpg's default key
  }
}

يبني الأمر elide publish ملفات JAR المختارة ويثبّتها مع ملف POM في مستودع Maven المحلي. والإصدار هو version المشروع. يحتاج النشر إلى groupId و version وملف Jar واحد بالضبط. يُنشر SourceJar تحت classifier الخاص به (الافتراضي sources)، و JavadocJar تحت javadoc. ويُحَل localRepository النسبي نسبةً إلى ملف البيان الذي يعلنه.

يسرد ملف POM أيضًا، بوصفها تبعيات compile، المكتبات التي يضعها Elide على classpath مشروع Kotlin دون إعلان، لأن المستخدمين يحتاجونها وقت التشغيل: kotlin-stdlib و kotlin-reflect بإصدار Kotlin الخاص بالمشروع، ومكتبات التشغيل التي تفعّلها kotlin.features (kotlinx-coroutines-core و kotlinx-serialization ومكتبة تشغيل Metro). تظهر هذه في ملف POM المنشور مع أن elide.pkl لا يذكرها. عطّل أيًّا منها من مصدره (kotlin.features أو kotlin.compilerOptions.noStdlib)، أو أعلنه بنفسك لتحديد إصدار مختلف. ويضيف jvm.features.graalvm حزمة GraalVM SDK بنطاق runtime.

ينشر elide publish --to <name> بدلًا من ذلك إلى مستودع من repositories، مع مجاميع اختبارية .md5 و .sha1 و .sha256 و .sha512 لكل ملف. تأتي بيانات الاعتماد من ELIDE_MAVEN_<NAME>_USERNAME و ELIDE_MAVEN_<NAME>_PASSWORD، حيث <NAME> هو اسم المستودع بأحرف كبيرة مع تحويل كل محرف ليس حرفًا ولا رقمًا إلى _ (internal → ELIDE_MAVEN_INTERNAL_USERNAME، my-repo → ELIDE_MAVEN_MY_REPO_…)، وإلا فمن credentials المستودع. ويُرفض اسمان يقابلان المتغيرات نفسها (my-repo و my_repo). وتُرفض مستودعات http:// العادية غير localhost ما لم يُمرَّر --allow-http-repositories.

عند ضبط signing، يوقّع النشر البعيد كل ملف باستخدام البرنامج gpg (<file>.asc)؛ ويوقّع signing {} بالمفتاح الافتراضي لـ gpg، ويختار signing { gpg { keyName = "…" } } مفتاحًا بعينه. لا يوقّع النشر المحلي إلا مع --sign، ويعطّل --no-sign التوقيع. يطلب gpg-agent عبارة المرور. في CI، اضبط ELIDE_GPG_PASSPHRASE وسيمرّرها Elide إلى gpg عبر loopback pinentry. لا يقرأ Elide المفتاح نفسه أبدًا.

ينشر مستودع CentralPortal إلى Maven Central عبر Central Publisher Portal. أنشئ رمز مستخدم في Portal ومرّره بوصفه ELIDE_MAVEN_<NAME>_USERNAME و ELIDE_MAVEN_<NAME>_PASSWORD. تدخل كل مشاريع التشغيل في حزمة واحدة موقّعة ذات مجاميع اختبارية وفي عملية نشر واحدة، يتحقق منها Portal ويصدرها وحدةً واحدة. ينتظر Elide حتى يتحقق Portal منها، ويفشل مع أخطاء Portal إن لم تجتز التحقق. أما --no-wait فيعود فور انتهاء الرفع.

قبل البناء، يتحقق Elide مما يشترطه Central ويبلّغ عن كل النواقص دفعة واحدة: في pom الحقول name و description و url و licenses و developers و scm.url؛ ومُخرَج SourceJar ومُخرَج JavadocJar؛ والتوقيع (لذلك يُرفض --no-sign)؛ وإصدار ليس -SNAPSHOT.

في مساحة العمل، يرث الأعضاء كتلة publishing من الجذر باستثناء artifactId و artifacts، وتغلب إعدادات العضو نفسه حقلًا بحقل. وتُورَث المستودعات بأسمائها. والمشروع الذي لا يبني ملف JAR لا ينشر شيئًا مما يرثه.

لنشر بعض مشاريع مساحة العمل فقط، سمِّها (elide publish core util) بدلًا من تغيير كتل publishing الخاصة بها، أو مرّر --skip-existing لتخطي كل إصدار موجود مسبقًا في الوجهة؛ راجع elide publish.

الاختبار

import "elide:Testing.pkl" as Testing

testing { reports { Testing.xmlReport() } }

التغطية

import "elide:Coverage.pkl" as Coverage

coverage {
  enabled = true
  scope = "tests"
  jvm {
    excludes { "org.example.generated.*" }
    reports { Coverage.xmlReport(); Coverage.htmlReport() }
  }
  js { paths { "src" } }
}

راجع الاختبار › التغطية.

مساحات العمل

workspace { members { "core"; "app" } }

كل عضو مجلد له ملف elide.pkl خاص به، ولا يمكن أن يكون للأعضاء أعضاء. ينشئ الأمر elide init --template workspace جذرًا فيه مكتبة core وتطبيق app يعتمد عليها.

// core/elide.pkl
import "elide:Jvm.pkl" as Jvm

dependencies {
  maven {
    packages { "com.google.guava:guava" }  // version from the root
  }
}

artifacts {
  ["jar"] = new Jvm.Jar { name = "core" }
}

// app/elide.pkl
local core = project("core")

dependencies { maven { packages { core } } }

يفشل المرجع إلى مشروع بلا ملف JAR، أو استدعاء friend() في غير موضعه، عند تهيئة البناء.