Référence elide.pkl

elide.pkl est le manifeste du projet : il déclare les builds, les dépendances, les tests et les artefacts. Chaque fichier commence par :

amends "elide:project.pkl"

elide: désigne le schéma fourni avec l’Elide en cours d’exécution, pour ce module comme pour tous les autres (elide:Jvm.pkl). Pour épingler une version du schéma, amendez l’URL publiée : pkl.elide.dev/1.6.0/project.pkl.

La version en développement suit main jusqu’à sa version stable. Les versions publiées du schéma sont immuables.

Les versions correctives d’une ligne MAJOR.MINOR ne font qu’ajouter des propriétés. Une version mineure peut supprimer, renommer ou retyper des propriétés et changer des valeurs par défaut.

elide project export affiche le manifeste évalué en JSON ; elide build --inspect liste ses tâches.

Métadonnées du projet

build.flags contient les valeurs de -f/--flag ; voir Options de build.

Contextes du moteur

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

Chaque contexte évalue le module d’entrée une fois, avec ses propres globales, avant que le serveur soit prêt. --contexts=N|auto sur run, serve et dev remplace spawn. Plus d’un contexte nécessite Linux.

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

La télémétrie est désactivée tant qu’aucune destination n’existe ici, dans les variables OTEL_*/ELIDE_OTEL_* ou dans les options --otel-*. Celles-ci remplacent ce bloc, les options en premier ; voir Variables d’environnement d’exécution. elide run, elide serve, elide test, elide build et elide install lisent ce bloc dans un projet ; elide run file.js le lit dans un projet quand elide.pkl contient le mot opentelemetry. Voir Configuration. Les identifiants ne sont jamais écrits ici : indiquez la variable d’environnement qui les contient.

Chaque destination :

Les erreurs sont envoyées sous forme d’entrées de journal et d’événements de span exception, plus la métrique elide.errors, si bien que tout fournisseur qui accepte les journaux, les traces ou les métriques les reçoit. Voir Présentation d’OpenTelemetry pour l’utilisation et Fournisseurs pour chaque fournisseur. Demander à un fournisseur un signal ou un protocole qu’il n’accepte pas est une erreur.

Baggage

Le serveur et les clients HTTP d’Elide propagent traceparent et tracestate. Ils ne transmettent le baggage W3C que si vous activez une direction, car le baggage reçu d’un client est une entrée non fiable :

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

Un en-tête de plus de 8 192 octets ou 180 membres, ou contenant un membre mal formé, est entièrement ignoré. Le baggage reçu d’un client n’atteint les requêtes sortantes que si les deux directions sont activées. Le code de l’application peut toujours lire, définir et envoyer du baggage via l’API OpenTelemetry ; OTEL_PROPAGATORS n’affecte que cette API.

Sources

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

Voir Source sets.

Dépendances

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

Une substitution conserve les dépendances transitives de la coordonnée et la remplace par le fichier sur chaque classpath. Les chemins sont résolus par rapport au manifeste qui les déclare ; les membres héritent de ceux de la racine. La tâche qui génère le fichier doit s’exécuter avant. Groupes et dépôts : Dépendances.

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

Valeurs par défaut : Compilateur Kotlin.

JavaScript

Chaîne d’outils

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

Voir Chaîne d’outils Web.

Artefacts

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

La clé nomme la tâche de build. Les sorties vont dans .dev/artifacts/<kind>/.

WebImage

WebImage reprend les champs NativeImage from, name, entrypoint, moduleName, dependsOn et options, n’a pas de type et ajoute :

entrypoint (ou jvm.main) est requis même avec autoRun = false. Ne passez pas d’options brutes pour ces quatre réglages. Guide : WebImage ; artefacts définis par options : migration.

Publication

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 construit les JAR sélectionnés et les installe avec un POM dans le dépôt Maven local. La version est la version du projet. Une publication nécessite un groupId, une version et exactement un Jar. Un SourceJar est publié sous son classifier (par défaut sources), un JavadocJar sous javadoc. Un localRepository relatif est résolu par rapport au manifeste qui le déclare.

Le POM liste aussi, en tant que dépendances compile, les bibliothèques qu’Elide place sur le classpath d’un projet Kotlin sans déclaration, car les consommateurs en ont besoin à l’exécution : kotlin-stdlib et kotlin-reflect dans la version Kotlin du projet, et les bibliothèques d’exécution qu’active kotlin.features (kotlinx-coroutines-core, kotlinx-serialization, le runtime Metro). Elles figurent dans le POM publié même si elide.pkl ne les nomme pas. Désactivez-en une là d’où elle vient (kotlin.features ou kotlin.compilerOptions.noStdlib), ou déclarez-la vous-même pour épingler une autre version. jvm.features.graalvm ajoute le SDK GraalVM avec la portée runtime.

elide publish --to <name> publie plutôt dans un dépôt de repositories, avec des sommes de contrôle .md5, .sha1, .sha256 et .sha512 pour chaque fichier. Les identifiants viennent de ELIDE_MAVEN_<NAME>_USERNAME et ELIDE_MAVEN_<NAME>_PASSWORD, où <NAME> est le nom du dépôt en majuscules, chaque caractère autre qu’une lettre ou un chiffre étant remplacé par _ (internal → ELIDE_MAVEN_INTERNAL_USERNAME, my-repo → ELIDE_MAVEN_MY_REPO_…), et sinon des credentials du dépôt. Deux noms qui correspondent aux mêmes variables (my-repo et my_repo) sont refusés. Les dépôts en http:// simple autres que localhost sont refusés sans --allow-http-repositories.

Si signing est défini, une publication distante signe chaque fichier avec le programme gpg (<file>.asc) ; signing {} signe avec la clé par défaut de gpg, et signing { gpg { keyName = "…" } } en choisit une. Une publication locale ne signe qu’avec --sign, et --no-sign désactive la signature. gpg-agent demande la phrase secrète. En CI, définissez ELIDE_GPG_PASSPHRASE ; Elide la transmet à gpg via le pinentry en mode loopback. Elide ne lit jamais la clé lui-même.

Un dépôt CentralPortal publie sur Maven Central via le Central Publisher Portal. Créez un jeton utilisateur dans le Portal et passez-le comme ELIDE_MAVEN_<NAME>_USERNAME et ELIDE_MAVEN_<NAME>_PASSWORD. Tous les projets de l’exécution vont dans un seul bundle signé et accompagné de sommes de contrôle, et dans un seul déploiement, que le Portal valide et publie comme un tout. Elide attend que le Portal l’ait validé, et échoue avec les erreurs du Portal si la validation ne passe pas. --no-wait rend la main juste après l’envoi.

Avant le build, Elide vérifie ce qu’exige Central et signale tout ce qui manque en une fois : name, description, url, licenses, developers et scm.url de pom ; un artefact SourceJar et un artefact JavadocJar ; la signature (donc --no-sign est refusé) ; et une version autre que -SNAPSHOT.

Dans un espace de travail, les membres héritent du bloc publishing de la racine sauf artifactId et artifacts, et les réglages propres d’un membre l’emportent champ par champ. Les dépôts sont hérités par nom. Un projet qui ne construit aucun JAR ne publie rien de ce dont il hérite.

Pour ne publier que certains projets d’un espace de travail, nommez-les (elide publish core util) au lieu de modifier leurs blocs publishing, ou passez --skip-existing pour ignorer toute version déjà présente dans la cible ; voir elide publish.

Tests

import "elide:Testing.pkl" as Testing

testing { reports { Testing.xmlReport() } }

Couverture

import "elide:Coverage.pkl" as Coverage

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

Voir Tests › Couverture.

Espaces de travail

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

Chaque membre est un répertoire avec son propre elide.pkl ; les membres ne peuvent pas avoir de membres. elide init --template workspace crée une racine avec une bibliothèque core et une app qui en dépend.

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

Une référence à un projet sans JAR, ou un friend() mal placé, échoue lors de la configuration du build.