Справочник 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() не на своём месте вызывает ошибку на этапе конфигурации сборки.