Referencia de elide.pkl

elide.pkl es el manifiesto del proyecto: declara compilaciones, dependencias, pruebas y artefactos. Todo archivo empieza con:

amends "elide:project.pkl"

elide: apunta al esquema incluido en el Elide en ejecución, para este y cualquier otro módulo (elide:Jvm.pkl). Para fijar una versión del esquema, enmiende la URL publicada: pkl.elide.dev/1.6.0/project.pkl.

La versión en desarrollo sigue a main hasta su versión estable. Las versiones publicadas del esquema son inmutables.

Las versiones de parche dentro de una línea MAJOR.MINOR solo añaden propiedades. Una versión menor puede eliminar, renombrar o cambiar el tipo de propiedades y cambiar valores predeterminados.

elide project export imprime el manifiesto evaluado como JSON; elide build --inspect lista sus tareas.

Metadatos del proyecto

build.flags contiene los valores de -f/--flag; consulte Opciones de compilación.

Contextos del motor

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

Cada contexto evalúa el módulo de entrada una vez, con sus propios globales, antes de que el servidor esté listo. --contexts=N|auto en run, serve y dev anula spawn. Más de un contexto requiere Linux.

Bloque de 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 telemetría está desactivada hasta que exista un destino aquí, en variables OTEL_*/ELIDE_OTEL_* o en opciones --otel-*. Estas anulan este bloque, las opciones primero; consulte Variables de entorno del runtime. elide run, elide serve, elide test, elide build y elide install leen este bloque dentro de un proyecto; elide run file.js dentro de un proyecto lo lee cuando elide.pkl contiene la palabra opentelemetry. Consulte Configuración. Las credenciales nunca se escriben aquí: indique la variable de entorno que las contiene.

Cada destino:

Los errores se envían como entradas de registro y eventos de span exception, además de la métrica elide.errors, de modo que todo proveedor que acepte registros, trazas o métricas los recibe. Consulte Descripción general de OpenTelemetry para el uso y Proveedores para cada proveedor. Pedir a un proveedor una señal o un protocolo que no acepta es un error.

Baggage

El servidor y los clientes HTTP de Elide propagan traceparent y tracestate. Solo transmiten baggage W3C cuando usted activa una dirección, porque el baggage que llega de un cliente es una entrada no confiable:

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

Una cabecera de más de 8192 bytes o 180 miembros, o con algún miembro mal formado, se descarta entera. El baggage recibido de un cliente llega a las peticiones salientes solo cuando ambas direcciones están activadas. El código de la aplicación siempre puede leer, definir y enviar baggage mediante la API de OpenTelemetry; OTEL_PROPAGATORS solo afecta a esa API.

Fuentes

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

Consulte Conjuntos de fuentes.

Dependencias

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

Una sustitución conserva las dependencias transitivas de la coordenada y la reemplaza por el archivo en todos los classpaths. Las rutas se resuelven respecto al manifiesto que las declara; los miembros heredan las de la raíz. La tarea que genera el archivo debe ejecutarse antes. Grupos y repositorios: Dependencias.

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

Valores predeterminados: Compilador Kotlin.

JavaScript

Cadena de herramientas

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

Consulte Cadena de herramientas web.

Artefactos

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 clave da nombre a la tarea de compilación. Las salidas van a .dev/artifacts/<kind>/.

WebImage

WebImage admite los campos de NativeImage from, name, entrypoint, moduleName, dependsOn y options, no tiene type y añade:

entrypoint (o jvm.main) es obligatorio incluso con autoRun = false. No pase opciones sin procesar para estos cuatro ajustes. Guía: WebImage; artefactos basados en opciones: migración.

Publicación

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 compila los JAR seleccionados y los instala con un POM en el repositorio local de Maven. La versión es la version del proyecto. Una publicación necesita un groupId, una version y exactamente un Jar. Un SourceJar se publica con su classifier (por defecto sources), un JavadocJar con javadoc. Un localRepository relativo se resuelve respecto al manifiesto que lo declara.

El POM también lista, como dependencias compile, las bibliotecas que Elide pone en el classpath de un proyecto Kotlin sin declararlas, porque los consumidores las necesitan en tiempo de ejecución: kotlin-stdlib y kotlin-reflect en la versión de Kotlin del proyecto, y los entornos de ejecución que activa kotlin.features (kotlinx-coroutines-core, kotlinx-serialization, el entorno de ejecución de Metro). Aparecen en el POM publicado aunque elide.pkl no los nombre. Desactive uno donde se origina (kotlin.features o kotlin.compilerOptions.noStdlib), o declárelo usted mismo para fijar otra versión. jvm.features.graalvm añade el SDK de GraalVM con ámbito runtime.

elide publish --to <name> publica en cambio en un repositorio de repositories, con sumas de verificación .md5, .sha1, .sha256 y .sha512 para cada archivo. Las credenciales se toman de ELIDE_MAVEN_<NAME>_USERNAME y ELIDE_MAVEN_<NAME>_PASSWORD, donde <NAME> es el nombre del repositorio en mayúsculas con cada carácter que no sea letra o dígito convertido en _ (internal → ELIDE_MAVEN_INTERNAL_USERNAME, my-repo → ELIDE_MAVEN_MY_REPO_…), y si no, de las credentials del repositorio. Se rechazan dos nombres que corresponden a las mismas variables (my-repo y my_repo). Los repositorios http:// sin cifrar que no sean localhost se rechazan sin --allow-http-repositories.

Con signing definido, una publicación remota firma cada archivo con el programa gpg (<file>.asc); signing {} firma con la clave predeterminada de gpg, y signing { gpg { keyName = "…" } } elige una. Una publicación local solo firma con --sign, y --no-sign desactiva la firma. gpg-agent pide la frase de contraseña. Para CI, defina ELIDE_GPG_PASSPHRASE y Elide la pasa a gpg mediante pinentry en modo loopback. Elide nunca lee la clave por sí mismo.

Un repositorio CentralPortal publica en Maven Central a través del Central Publisher Portal. Cree un token de usuario en el Portal y páselo como ELIDE_MAVEN_<NAME>_USERNAME y ELIDE_MAVEN_<NAME>_PASSWORD. Todos los proyectos de la ejecución van en un único paquete firmado y con sumas de verificación, y en un único despliegue, que el Portal valida y publica como una unidad. Elide espera a que el Portal lo haya validado y falla con los errores del Portal si no pasa la validación. --no-wait termina justo después de la subida.

Antes de compilar, Elide comprueba lo que exige Central e informa de todo lo que falta a la vez: name, description, url, licenses, developers y scm.url de pom; un artefacto SourceJar y uno JavadocJar; la firma (por lo que se rechaza --no-sign); y una versión que no sea -SNAPSHOT.

En un espacio de trabajo, los miembros heredan el bloque publishing de la raíz salvo artifactId y artifacts, y los ajustes propios de un miembro prevalecen campo por campo. Los repositorios se heredan por nombre. Un proyecto que no compila ningún JAR no publica nada de lo que hereda.

Para publicar solo algunos proyectos de un espacio de trabajo, nómbrelos (elide publish core util) en lugar de cambiar sus bloques publishing, o pase --skip-existing para omitir toda versión que ya esté en el destino; consulte elide publish.

Pruebas

import "elide:Testing.pkl" as Testing

testing { reports { Testing.xmlReport() } }

Cobertura

import "elide:Coverage.pkl" as Coverage

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

Consulte Pruebas › Cobertura.

Espacios de trabajo

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

Cada miembro es un directorio con su propio elide.pkl; los miembros no pueden tener miembros. elide init --template workspace crea una raíz con una biblioteca core y una app que depende de ella.

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

Una referencia a un proyecto sin JAR, o un friend() mal colocado, falla al configurar la compilación.