elide.pkl reference

elide.pkl is the project manifest: it declares builds, dependencies, tests and artifacts. Every file starts with:

amends "elide:project.pkl"

elide: resolves to the schema bundled with the running Elide, for this and every other module (elide:Jvm.pkl). To pin a schema version, amend the published URL: pkl.elide.dev/1.6.3/project.pkl.

Schema versions are independent of the Elide runtime version. A development schema can be locked before it is published; the URL above stays on a published version. Published development versions follow main until their stable release, after which they are immutable.

Patch releases within a MAJOR.MINOR line only add properties. A minor release can remove, rename or retype properties and change defaults.

elide project export prints the evaluated manifest as JSON; elide build --inspect lists its tasks.

Project metadata

build.flags holds the -f/--flag values; see Build Flags.

Engine contexts

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

Each context evaluates the entry module once, with its own globals, before the server is ready. --contexts=N|auto on run, serve and dev overrides spawn. More than one context requires 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" }
}

Telemetry is off until a destination exists here, in OTEL_*/ELIDE_OTEL_* variables, or in --otel-* flags. Those override this block, flags first; see Runtime Environment Variables. elide run, elide serve, elide test, elide build and elide install in a project read this block; elide run file.js inside a project reads it when elide.pkl contains the word opentelemetry. See Configuration. Credentials are never written here: name the environment variable that holds them.

Each destination:

Errors are sent as exception log records and span events, plus the elide.errors metric, so every provider that accepts logs, traces, or metrics receives them. See OpenTelemetry for usage and Providers for each provider. Asking a provider for a signal or protocol it does not accept is an error.

Baggage

Elide’s HTTP server and clients propagate traceparent and tracestate. They pass W3C baggage only when you turn a direction on, because baggage arriving from a client is untrusted input:

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

A header over 8,192 bytes or 180 members, or with any malformed member, is dropped whole. Baggage received from a client reaches outgoing requests only when both directions are on. Application code can always read, set and send baggage through the OpenTelemetry API; OTEL_PROPAGATORS affects only that API.

Sources

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

See Source Sets.

Dependencies

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

A substitution keeps the coordinate’s transitive dependencies and puts the file on every classpath in its place. Paths resolve against the declaring manifest; members inherit the root’s. Order the task that generates the file first. Buckets and repositories: Dependencies.

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

C header bindings

In 1.6.2, declare native bindings under jvm.java.bindings and select them for the Java source set that owns their generated classes:

jvm {
  java {
    bindings {
      ["api"] {
        headers { "native/api.h" }
        packageName = "example.nativeapi"
        headerClassName = "NativeApi"
        includeDirs { "native/include" }
        libraries { "answer" }
      }
    }
    sourceSets {
      ["main"] { bindings { "api" } }
    }
  }
}

Paths resolve against the owning project. A group has one owning source set; dependent sets use its classes through their normal dependencies. Declaring a group does not select it for compilation. These bindings require a distribution with native tools. See C header bindings for generation-only targets, exported sources, incremental inputs, and command-line selections, and jextract for native-library loading at runtime.

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

Defaults: Kotlin Compiler.

JavaScript

Toolchain

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

See Web Toolchain.

Artifacts

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

The key names the build task. Outputs go under .dev/artifacts/<kind>/.

WebImage

WebImage takes the NativeImage fields from, name, entrypoint, moduleName, dependsOn and options, has no type, and adds:

entrypoint (or jvm.main) is required even with autoRun = false. Do not pass raw flags for these four settings. Guide: WebImage; flag-based artifacts: migration.

Publishing

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 builds the selected JARs and installs them with a POM into the local Maven repository. The version is the project’s version. A publication needs a groupId, a version and exactly one Jar. A SourceJar publishes under its classifier (default sources), a JavadocJar under javadoc. A relative localRepository resolves against the manifest that declares it.

The POM also lists libraries Elide puts on a Kotlin project’s classpath without a declaration, as compile dependencies, because consumers need them at run time: kotlin-stdlib and kotlin-reflect at the project’s Kotlin version, and the runtimes kotlin.features turns on (kotlinx-coroutines-core, kotlinx-serialization, the Metro runtime). These appear in the published POM even though elide.pkl doesn’t name them. Turn one off where it comes from (kotlin.features, or kotlin.compilerOptions.noStdlib), or declare it yourself to pin a different version. jvm.features.graalvm adds the GraalVM SDK at runtime scope.

elide publish --to <name> publishes to a repository from repositories instead, with .md5, .sha1, .sha256 and .sha512 checksums for every file. Credentials come from ELIDE_MAVEN_<NAME>_USERNAME and ELIDE_MAVEN_<NAME>_PASSWORD, where <NAME> is the repository name uppercased with every character other than a letter or digit turned into _ (internal → ELIDE_MAVEN_INTERNAL_USERNAME, my-repo → ELIDE_MAVEN_MY_REPO_…), and otherwise from the repository’s credentials. Two names that map to the same variables (my-repo and my_repo) are refused. Plain http:// repositories other than localhost are refused without --allow-http-repositories.

With signing set, a remote publish signs every file with the gpg binary (<file>.asc); signing {} signs with gpg’s default key, and signing { gpg { keyName = "…" } } picks one. A local publish signs only with --sign, and --no-sign turns signing off. gpg-agent asks for the passphrase. For CI, set ELIDE_GPG_PASSPHRASE and Elide passes it to gpg through loopback pinentry. Elide never reads the key itself.

A CentralPortal repository publishes to Maven Central through the Central Publisher Portal. Create a user token in the Portal and pass it as ELIDE_MAVEN_<NAME>_USERNAME and ELIDE_MAVEN_<NAME>_PASSWORD. Every project of the run goes into one signed, checksummed bundle and one deployment, which the Portal validates and releases as a unit. Elide waits until the Portal has validated it, and fails with the Portal’s errors if it does not pass. --no-wait returns right after the upload instead.

Before building, Elide checks what Central requires and reports everything missing at once: pom name, description, url, licenses, developers and scm.url; a SourceJar and a JavadocJar artifact; signing (so --no-sign is refused); and a version that is not a -SNAPSHOT.

In a workspace, members inherit the root’s publishing block except artifactId and artifacts, and a member’s own settings win field by field. Repositories are inherited by name. A project that builds no JAR publishes nothing it inherits.

To publish only some of a workspace’s projects, name them (elide publish core util) rather than changing their publishing blocks, or pass --skip-existing to leave out every version already in the target; see elide publish.

Testing

import "elide:Testing.pkl" as Testing

testing { reports { Testing.xmlReport() } }

Coverage

import "elide:Coverage.pkl" as Coverage

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

See Testing › Coverage.

Workspaces

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

Each member is a directory with its own elide.pkl; members cannot have members. elide init --template workspace creates a root with a core library and an app that depends on it.

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

A reference to a project with no JAR, or a misplaced friend(), fails when the build is configured.

Micronaut

See the Micronaut guide for complete build, test, and Native Image workflows.

Use the Micronaut Core version, not the platform BOM version. Core module names expand to io.micronaut:micronaut-<name>:<version>; the matching micronaut-inject-java processor is installed and used by Java compilation. Independently versioned modules, such as Micronaut Serialization, remain ordinary Maven coordinates.

dependencies {
  micronaut {
    version = "4.10.23"
    modules { "runtime"; "http-server-netty" }
    testModules { "http-client" }
  }
}
jvm {
  micronaut {
    config {
      micronaut {
        application { name = "example" }
        server { port = 8080 }
      }
      custom {
        enabled = true
        origins = new Listing { "https://example.com" }
      }
    }
  }
}

The optional jvm.micronaut.config accepts arbitrary JSON-compatible keys and values. Elide renders it with Pkl’s JSON renderer and stages application.json on production classpaths and in JARs. Elide adds the matching micronaut-jackson-core runtime dependency for the JSON configuration loader. When supplying your own JSON resources, declare that loader yourself. An authored application.json conflicts with this generated resource and fails the build; omit the block to supply your own configuration through resources. Environment-specific files may still be provided through resources. Changes to generated configuration invalidate resource and JAR tasks.

Direct io.micronaut:micronaut-* Core dependencies also select the matching processor after workspace version pins are applied. Conflicting Core or processor versions fail validation. Satellite-module versions and transitive-only framework dependencies do not select a processor: declare a Core module or use the shorthand. This integration uses the existing Java annotation-processing path; it does not enable KSP or Kotlin-source annotation processing in project builds.

Runnable examples are in tools/smoketests/micronaut-pkl and tools/smoketests/micronaut-resources. The sample guide includes run, packaging, and smoke-test commands.

Test containers

testing.testcontainers describes disposable infrastructure shared by the project’s selected test runners. Declare named entries in containers, each with an image, optional command and environment, exposed TCP ports, and a wait strategy. environment on the outer block binds container connection values into JavaScript/TypeScript and JVM test environments. startupTimeoutSeconds bounds total startup.

See Shared test containers for the complete configuration, readiness options, prerequisites, and lifecycle.