elide.pkl Reference — Elide Docs

amends "elide:project.pkl"

elide: resolves to the schema bundled with the running Elide; import "elide:Jvm.pkl" and the other modules work the same way. To pin a schema version, amend the published URL instead: pkl.elide.dev/1.6.0/project.pkl.

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

Pinned version	Result
Older than the running Elide	Uses that version’s definitions; a property removed since fails, naming the version.
Newer than the running Elide	Allowed; a property the running Elide lacks fails, naming the upgrade needed.
Another major version	Refused.

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

Project metadata

Property	Purpose
`name`, `version`, `description`	Project identity; `version` also names application archives.
`entrypoint`	File(s) `elide run` uses when given none.
`scripts`	Named shell commands for `elide run NAME`.
`sources`	Source sets; see Sources.
`dependencies`	Maven, npm and PyPI packages; see Dependencies.
`jvm`, `kotlin`, `javascript`	Language and compiler settings.
`nativeImage`	Project-wide compiler options; not merged into artifact `options` in 1.6.0.
`engine`	Serving contexts; see Engine contexts.
`toolchain`	Accepted Elide versions; see Toolchain.
`dev`	Source info, MCP, dev server; see Dev.
`web`	Web asset settings; see Web.
`artifacts`	Build outputs; see Artifacts.
`testing`	Test reports; see Testing.
`coverage`	Coverage; see Testing › Coverage.
`workspace`	Member projects; see Workspaces.

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

Engine contexts

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

Property	Meaning	Default
`topology`	`"prespawn"`, the only value.	`"prespawn"`
`contexts.spawn`	Context count: a positive integer, or `"auto"` (physical cores minus `reserve`, clamped).	`1`
`contexts.reserve`	Cores subtracted for `"auto"`; does not pin CPUs.	`2`
`contexts.min`, `contexts.max`	Bounds for any count.	`1`, none
`maxContexts`	Deprecated fixed count; cannot combine with `contexts`.	—

Each context evaluates the entry module once, with its own globals; all finish before the server is ready. --contexts=N|auto on run, serve and dev overrides spawn. More than one context requires Linux.

Sources

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

Property	Meaning	Empty or absent
`type`	`"source"`, `"test"`, `"example"` or `"other"`.	Inferred from the name.
`paths`	Globs or directories.	`src/<name>/<language>`.
`resources`	Paths, or `new { from; into }` roots.	`src/<name>/resources`.
`dependsOn`	Source sets visible to this one.	Test and example sets see `main`.

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

Block	Properties
`maven`	`packages`, `devPackages`, `modules`, `compileOnly`, `runtimeOnly`, `processors`, `testPackages`, `kotlinPlugins`, `exclusions`, `substitutions`, `repositories`, `enableDefaultRepositories`, `localRepository`
`npm`	`packages`, `devPackages`
`pypi`	`packages`, `optionalPackages` (named groups); `elide install` does not install them.
`spring`	`version`, `starter`, `testStarter`; expands into `maven`.

Value	Form
Maven entry	`"group:artifact:version[:classifier]"`, a `MavenPackageSpec` (`group`, `name`, `version`, `classifier` or `coordinate`), a local JAR path, or a project reference.
Repository	A URL, or a spec with `url`, `name`, `description`, `credentials` (`username`, `password`, `ntlmDomain`, `ntlmWorkstation`).
`substitutions` key	`group:artifact` (any version) or `group:artifact:version`; the value is a file path.

A substitution keeps the coordinate’s resolution and transitive dependencies but puts the file on every classpath in its place. Paths resolve against the declaring manifest; members inherit the root’s. A generated file needs its task ordered 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" } } }
}

Property	Meaning	Default
`main`	Entrypoint class for `elide run`, JARs, applications and native images.	—
`target`	Bytecode target: `8` … `29`, `1.8`, `"latest"`, `"stable"` or `"auto"`.	`"auto"` (21)
`javaHome`	Java home for external compiles and forked JVMs.	Elide’s own
`preferBali`	Prefer `bali` from `PATH` for external JVM runs.	`false`
`features.testing`	JUnit dependencies on test sets.	`true`
`features.automodules`	Automatic modules for JARs without a descriptor.	`true`
`features.graalvm`	`org.graalvm` SDK APIs on the compile classpath.	`false`
`java.source`, `java.release`	Source and `--release` levels; see Java Compiler.	`"auto"`
`java.compiler.mode`	`"embedded"` or `"external"`.	`"embedded"`
`java.compiler.flags`	Extra `javac` flags.	none
`flags`	JVM flags for `elide run`, the test JVM and start scripts.	none
`defs`	System properties (`-D`), applied wherever `flags` are.	none
`debug`	Compile with `-g`.	`true`

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

Property	Meaning
`apiLevel`, `languageLevel`	`"auto"`, `"latest"`, `"stable"`, or `"1.9"` … `"2.5"`.
`compilerOptions`	`optIn`, `progressiveMode`, `extraWarnings`, `allWarningsAsErrors`, `suppressWarnings`, `verbose`, `freeCompilerArgs`, `apiVersion`, `languageVersion`, `includeRuntime`, `noStdlib`, `javaParameters`, `jvmTarget`, `noJdk`, `jvmTargetValidationMode`, `incremental`
`features`	`testing`, `kotlinx`, `defaultPlugins`, `serialization`, `coroutines`, `atomicfu`, `powerAssert`, `metro`, `reflection`
`toolchain`	`"embedded"`, `new Kotlin.ManagedKotlinToolchain { version }` or `new Kotlin.CustomKotlinToolchain { path }`.
`plugins`	Options per compiler-plugin id, passed as `-P plugin:<id>:<key>=<value>`.

Defaults: Kotlin Compiler.

JavaScript

Property	Meaning	Default
`javascript.ecma`	Target: a year `2015` … `2025`, `"stable"` or `"latest"`.	`"stable"`

Toolchain

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

Property	Meaning
`engines["elide"]`	Version or semver range, or `new { version = "…" }`; a running Elide outside it fails validation.
`engines[<other>]`	Accepted, not enforced.

Dev

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

Property	Meaning	Default
`source.platform`, `source.project`, `source.subpath`	Source host: `"github"`, `"gitlab"`, `"bitbucket"`, `"git"` or another name.	—
`mcp.registerElide`	Register Elide as an MCP tool.	`true`
`mcp.advice`	Expose `elide project advice` as an MCP resource.	`true`
`mcp.resources`	Extra MCP resources: `path`, `name`, `description`, `mimeType` (detected if omitted).	none
`server.host`, `server.port`	Unused by `elide dev`, which takes `--host`/`--port` (default `127.0.0.1:3000`).	`"0.0.0.0"`, `8080`

Web

Property	Meaning	Default
`web.css.minify`	Minify built CSS.	`true`
`web.css.targets`	Browser targets: `new { browser = "chrome"; version = "120" }`.	none
`web.minifyHtml`	Minify rendered HTML.	`true`
`web.browsers`	Browser targets for all outputs; `css.targets` overrides it for CSS.	none

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

Type	Module	Fields
`Jar`, `SourceJar`, `JavadocJar`, `JvmApplication`	`elide:Jvm.pkl`	JAR Assembly
`NativeImage`	`elide:NativeImage.pkl`	Native Image
`WebImage`	`elide:NativeImage.pkl`	WebImage
`ContainerImage`	`elide:Container.pkl`	JVM Containers
`StaticSite`	`elide:Web.pkl`	Static Sites

Common field	Meaning
`dependsOn`	Artifact names to build first.
`name` (JARs)	`"app"` and `"app.jar"` both give `app.jar`; a `SourceJar` gives `app-sources.jar`.

WebImage

WebImage takes the NativeImage fields from, name, entrypoint, moduleName, dependsOn and options (see Native Image), has no type, and adds:

Property	Values	Default
`backend`	`"wasm-gc"` (host GC) or `"wasm-lm"` (linear memory).	`"wasm-gc"`
`runtime`	`"generic"`, `"browser"` or `"node"`.	`"generic"`
`autoRun`	Start the program when the loader loads.	`true`
`sourceMap`	Emit a JavaScript source map.	`false`

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

Testing

import "elide:Testing.pkl" as Testing

testing { reports { Testing.xmlReport() } }

Property	Meaning
`testing.reports`	Report formats for every runner, written to `.dev/reports/tests/<language>/<source-set>/`; same as `--reporter=junit`.

Coverage is the top-level coverage block; 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 generates a root with a core library and an app that depends on it.

Behavior	Rule
Build scope	From the root, `elide build`/`elide test` cover every project; from a member, only that member.
Cross-project tasks	`elide build core:compile-kotlin-main`, or `elide build core` for its default tasks.
Shared state	Resolved dependencies and build state are stored in the root `.dev`; outputs stay in each project’s `.dev`.
Version pins	A member can omit a Maven version and take the root’s; a conflicting version is an error.

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

Reference	Meaning
`project("core")`	The project’s `Jvm.Jar` artifact plus its compile classpath; built only when needed. JVM sources alone do not count.
`project("core").artifact("fat")`	Pick one JAR when the project declares several.
`project("core").friend()`	Also see `core`’s Kotlin `internal` declarations (not its dependencies’). Only in `packages`, `modules`, `compileOnly`, `testPackages`.
`module.project("core")`	Use in place, inside an object body; bare `project(…)` does not resolve there.
`new Artifacts.ProjectArtifact { project = "core"; artifact = "fat" }`	Explicit form; `import "elide:Artifacts.pkl" as Artifacts`.

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