elide.pkl-Referenz

elide.pkl ist das Projektmanifest: Es deklariert Builds, Abhängigkeiten, Tests und Artefakte. Jede Datei beginnt mit:

amends "elide:project.pkl"

elide: verweist auf das Schema, das mit dem laufenden Elide ausgeliefert wird, für dieses und jedes andere Modul (elide:Jvm.pkl). Um eine Schemaversion festzulegen, erweitern Sie die veröffentlichte URL: pkl.elide.dev/1.6.0/project.pkl.

Die Version in Entwicklung folgt main bis zu ihrem stabilen Release. Veröffentlichte Schemaversionen sind unveränderlich.

Patch-Releases innerhalb einer MAJOR.MINOR-Linie fügen nur Eigenschaften hinzu. Ein Minor-Release kann Eigenschaften entfernen, umbenennen oder ihren Typ ändern und Standardwerte ändern.

elide project export gibt das ausgewertete Manifest als JSON aus; elide build --inspect listet seine Tasks auf.

Projektmetadaten

build.flags enthält die Werte von -f/--flag; siehe Build-Flags.

Engine-Kontexte

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

Jeder Kontext wertet das Einstiegsmodul einmal mit eigenen Globals aus, bevor der Server bereit ist. --contexts=N|auto bei run, serve und dev überschreibt spawn. Mehr als ein Kontext erfordert Linux.

OpenTelemetry-Block

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" }
}

Telemetrie ist aus, bis ein Ziel hier, in OTEL_*/ELIDE_OTEL_*-Variablen oder in --otel-*-Flags existiert. Diese überschreiben diesen Block, Flags zuerst; siehe Laufzeit-Umgebungsvariablen. elide run, elide serve, elide test, elide build und elide install lesen diesen Block in einem Projekt; elide run file.js liest ihn innerhalb eines Projekts, wenn elide.pkl das Wort opentelemetry enthält. Siehe Konfiguration. Zugangsdaten stehen nie hier: Nennen Sie die Umgebungsvariable, die sie enthält.

Jedes Ziel:

Fehler werden als exception-Log-Einträge und Span-Events sowie als Metrik elide.errors gesendet, sodass jeder Anbieter, der Logs, Traces oder Metriken akzeptiert, sie erhält. Siehe OpenTelemetry-Überblick zur Verwendung und Anbieter zu den einzelnen Anbietern. Ein Signal oder Protokoll von einem Anbieter anzufordern, der es nicht akzeptiert, ist ein Fehler.

Baggage

Der HTTP-Server und die HTTP-Clients von Elide propagieren traceparent und tracestate. W3C-baggage geben sie nur weiter, wenn Sie eine Richtung einschalten, denn Baggage von einem Client ist nicht vertrauenswürdige Eingabe:

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

Ein Header mit mehr als 8.192 Bytes oder 180 Einträgen oder mit einem fehlerhaften Eintrag wird ganz verworfen. Von einem Client empfangene Baggage erreicht ausgehende Anfragen nur, wenn beide Richtungen eingeschaltet sind. Anwendungscode kann Baggage über die OpenTelemetry-API immer lesen, setzen und senden; OTEL_PROPAGATORS wirkt nur auf diese API.

Quellen

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

Siehe Source-Sets.

Abhängigkeiten

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" } }
}

Eine Ersetzung behält die transitiven Abhängigkeiten der Koordinate und setzt die Datei an ihrer Stelle auf jeden Classpath. Pfade werden relativ zum deklarierenden Manifest aufgelöst; Mitglieder erben die der Wurzel. Ordnen Sie den Task, der die Datei erzeugt, davor an. Buckets und Repositorys: Abhängigkeiten.

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" } }
}

Standardwerte: Kotlin-Compiler.

JavaScript

Werkzeugkette

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

Dev

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

Web

Siehe Web-Werkzeugkette.

Artefakte

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
  }
}

Der Schlüssel benennt den Build-Task. Ausgaben landen unter .dev/artifacts/<kind>/.

WebImage

WebImage übernimmt die NativeImage-Felder from, name, entrypoint, moduleName, dependsOn und options, hat kein type und ergänzt:

entrypoint (oder jvm.main) ist auch mit autoRun = false erforderlich. Übergeben Sie für diese vier Einstellungen keine rohen Flags. Anleitung: WebImage; Artefakte auf Flag-Basis: Migration.

Veröffentlichung

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 baut die ausgewählten JARs und installiert sie mit einem POM in das lokale Maven-Repository. Die Version ist die version des Projekts. Eine Publikation braucht eine groupId, eine version und genau ein Jar. Ein SourceJar wird unter seinem classifier veröffentlicht (Standard sources), ein JavadocJar unter javadoc. Ein relatives localRepository wird relativ zum Manifest aufgelöst, das es deklariert.

Das POM listet außerdem als compile-Abhängigkeiten die Bibliotheken, die Elide ohne Deklaration auf den Classpath eines Kotlin-Projekts setzt, denn Nutzer brauchen sie zur Laufzeit: kotlin-stdlib und kotlin-reflect in der Kotlin-Version des Projekts sowie die Laufzeitbibliotheken, die kotlin.features einschaltet (kotlinx-coroutines-core, kotlinx-serialization, die Metro-Laufzeit). Sie erscheinen im veröffentlichten POM, auch wenn elide.pkl sie nicht nennt. Schalten Sie eine dort ab, wo sie herkommt (kotlin.features oder kotlin.compilerOptions.noStdlib), oder deklarieren Sie sie selbst, um eine andere Version festzulegen. jvm.features.graalvm fügt das GraalVM-SDK mit Scope runtime hinzu.

elide publish --to <name> veröffentlicht stattdessen in ein Repository aus repositories, mit Prüfsummen .md5, .sha1, .sha256 und .sha512 für jede Datei. Zugangsdaten kommen aus ELIDE_MAVEN_<NAME>_USERNAME und ELIDE_MAVEN_<NAME>_PASSWORD, wobei <NAME> der Repository-Name in Großbuchstaben ist und jedes Zeichen außer Buchstaben und Ziffern zu _ wird (internal → ELIDE_MAVEN_INTERNAL_USERNAME, my-repo → ELIDE_MAVEN_MY_REPO_…), andernfalls aus den credentials des Repositorys. Zwei Namen, die auf dieselben Variablen abbilden (my-repo und my_repo), werden abgelehnt. Reine http://-Repositorys außer localhost werden ohne --allow-http-repositories abgelehnt.

Ist signing gesetzt, signiert eine entfernte Veröffentlichung jede Datei mit dem gpg-Programm (<file>.asc); signing {} signiert mit dem Standardschlüssel von gpg, und signing { gpg { keyName = "…" } } wählt einen aus. Eine lokale Veröffentlichung signiert nur mit --sign, und --no-sign schaltet das Signieren ab. gpg-agent fragt nach der Passphrase. Setzen Sie für CI ELIDE_GPG_PASSPHRASE; Elide übergibt sie per Loopback-Pinentry an gpg. Elide liest den Schlüssel nie selbst.

Ein CentralPortal-Repository veröffentlicht über das Central Publisher Portal auf Maven Central. Erstellen Sie im Portal ein Benutzertoken und übergeben Sie es als ELIDE_MAVEN_<NAME>_USERNAME und ELIDE_MAVEN_<NAME>_PASSWORD. Alle Projekte des Laufs kommen in ein signiertes Bundle mit Prüfsummen und ein Deployment, das das Portal als Einheit validiert und freigibt. Elide wartet, bis das Portal es validiert hat, und schlägt mit den Fehlern des Portals fehl, wenn es die Prüfung nicht besteht. --no-wait kehrt stattdessen direkt nach dem Upload zurück.

Vor dem Bauen prüft Elide, was Central verlangt, und meldet alles Fehlende auf einmal: pom name, description, url, licenses, developers und scm.url; ein SourceJar- und ein JavadocJar-Artefakt; Signieren (daher wird --no-sign abgelehnt); und eine Version, die kein -SNAPSHOT ist.

In einem Workspace erben Mitglieder den publishing-Block der Wurzel außer artifactId und artifacts, und die eigenen Einstellungen eines Mitglieds haben Feld für Feld Vorrang. Repositorys werden nach Namen geerbt. Ein Projekt, das kein JAR baut, veröffentlicht nichts Geerbtes.

Um nur einige Projekte eines Workspace zu veröffentlichen, nennen Sie sie (elide publish core util), statt ihre publishing-Blöcke zu ändern, oder übergeben Sie --skip-existing, um jede Version auszulassen, die bereits im Ziel liegt; siehe elide publish.

Tests

import "elide:Testing.pkl" as Testing

testing { reports { Testing.xmlReport() } }

Abdeckung

import "elide:Coverage.pkl" as Coverage

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

Siehe Tests › Abdeckung.

Workspaces

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

Jedes Mitglied ist ein Verzeichnis mit eigener elide.pkl; Mitglieder können keine Mitglieder haben. elide init --template workspace erstellt eine Wurzel mit einer core-Bibliothek und einer app, die davon abhängt.

// 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 } } }

Eine Referenz auf ein Projekt ohne JAR oder ein falsch platziertes friend() schlägt fehl, wenn der Build konfiguriert wird.