Довідник elide.pkl

elide.pkl — маніфест проєкту: у ньому оголошуються збирання, залежності, тести й артефакти. Кожен файл починається так:

amends "elide:project.pkl"

elide: вказує на схему, вбудовану в запущений Elide, для цього та всіх інших модулів (elide:Jvm.pkl). Щоб закріпити версію схеми, розширюйте опубліковану URL-адресу: 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" }
    }
  }
}

Заголовок понад 8192 байти або 180 елементів чи з будь-яким некоректним елементом відкидається повністю. Baggage від клієнта потрапляє у вихідні запити, лише коли ввімкнено обидва напрямки. Код застосунку завжди може читати, задавати й надсилати baggage через API OpenTelemetry; OTEL_PROPAGATORS впливає лише на цей API.

Вихідні файли

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() не на своєму місці спричиняє помилку під час конфігурації збирання.