# elide.pkl Reference

> Every block and field of the elide.pkl project manifest.

```pkl
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`](https://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](#sources). |
| `dependencies` | Maven, npm and PyPI packages; see [Dependencies](#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](#engine-contexts). |
| `toolchain` | Accepted Elide versions; see [Toolchain](#toolchain). |
| `dev` | Source info, MCP, dev server; see [Dev](#dev). |
| `web` | Web asset settings; see [Web](#web). |
| `artifacts` | Build outputs; see [Artifacts](#artifacts). |
| `testing` | Test reports; see [Testing](#testing). |
| `coverage` | Coverage; see [Testing › Coverage](https://elide.help/docs/toolchain/testing#coverage). |
| `workspace` | Member projects; see [Workspaces](#workspaces). |

`build.flags` holds the `-f`/`--flag` values; see [Build Flags](https://elide.help/docs/toolchain/build-flags).

## Engine contexts

```pkl
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

```pkl
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](https://elide.help/docs/toolchain/source-sets).

## Dependencies

```pkl
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](#workspaces). |
| 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](https://elide.help/docs/toolchain/dependencies).

## JVM

```pkl
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](https://elide.help/docs/toolchain/jvm/javac#build-projects). | `"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

```pkl
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](https://elide.help/docs/toolchain/jvm/kotlinc#build-projects).

## JavaScript

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

## Toolchain

```pkl
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

```pkl
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](https://elide.help/docs/toolchain/web#manifest-settings).

## Artifacts

```pkl
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](https://elide.help/docs/toolchain/jvm/jar#project-artifacts) |
| `NativeImage` | `elide:NativeImage.pkl` | [Native Image](https://elide.help/docs/toolchain/jvm/native-image#project-artifact) |
| `WebImage` | `elide:NativeImage.pkl` | [WebImage](#webimage) |
| `ContainerImage` | `elide:Container.pkl` | [JVM Containers](https://elide.help/docs/toolchain/jvm/containers) |
| `StaticSite` | `elide:Web.pkl` | [Static Sites](https://elide.help/docs/toolchain/web/static-site) |

| 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](https://elide.help/docs/toolchain/jvm/native-image#project-artifact)), 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](https://elide.help/docs/toolchain/jvm/webimage#build-a-complete-project); flag-based artifacts:
[migration](https://elide.help/docs/toolchain/jvm/webimage#compile-without-a-project-manifest).

## Testing

```pkl
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](https://elide.help/docs/toolchain/testing#coverage).

## Workspaces

```pkl
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. |

```pkl
// 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" }
}
```

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