Elide Projects

Elide is capable of creating and managing Elide-native projects through a project toolchain.

An Elide Project consists of:

1. Project manifest - elide.pkl is a powerful configurable Pkl-based manifest.
2. Work directory - .dev acts as an internal directory, that Elide uses to store output and intermediate states of build tasks.
3. Lockfile - .dev/elide.build.bin and .dev/elide.lock.v2.bin are read-only binary files used by Elide tooling. Generally, users shouldn't edit them.

Project CLI

There are three CLI commands that can depend on an Elide project to work, which they can access in two ways:

1. Direct passing - by passing --project PATH you can specify the manifest that will be loaded for this command.
2. Auto-detection - if no path is provided, the command will attempt to find a project manifest in the current directory.

As such a plain call of,

 elide build

will attempt to search for manifest in a local directory, while

 elide build -p PATH

will try to fetch the manifest from the path.

Building a Project

It's possible to view a full list of tasks that a build command generates from the project manifest.

 elide build --inspect

To run a specific task,

 elide build TASK

For example,

 elide build :compile-java-main

Elide Project Manifest

The project manifest has a regimented, yet flexible structure.

# Importing project schema
amends "elide:project.pkl" 

# Importing configuration-specific schema
import "elide:Sources.pkl" as Src

# Project metadata
name = "project"
version = "1.0.0"
description = "example project"

# Project configuration
sources {
  ["main"] = new Src.SourceSetSpec {
    paths {
      "src/main/java<<>>*.java"
    }
  }
}

Project Metadata

Sources

For Elide project to build, sources have to be specified in the manifest. A general template of declaring sources is

import "elide:Sources.pkl" as Src
sources {
  ["main"] = new Src.SourceSetSpec {
    paths {
      "src/main/java<<>>*.java"
    }
  }
}

The import allows you to use source schema and helps Elide to parse the source section of the manifest.

Sources themselves are declared by paths, which are a list of pattern-matched paths.

Entrypoint

Specifying an entrypoint allows Elide to automatically detect scripts to run.

entrypoint {
  "some.entry"
}

As such if during elide run no script was specified, Elide will attempt to fetch an entrypoint filepath from the manifest.

Scripts

Scripts are key value pairs, intended to work similar to scripts of Node's package.json.

If elide run receives a non-option argument that matches the name of a script, the script is executed instead of the parameter being interpreted as a path.

For example, if you specify in script

scripts {
  ["help"] = "elide --help"
}

Dependencies

Elide comes with an in-built dependency manager.

There are two ways to declare a Maven dependency

import "elide:Jvm.pkl" as Jvm  

dependencies {
  maven {
    packages {
      "com.google.guava:guava:33.4.8-jre",
      new Jvm.MavenPackageSpec {
        group = "com.google.guava"
        name = "guava"
        version = "33.4.8-jre"
      }
    }
  }
}

Maven dependencies are installed in your local Maven repository and linked into your project through .dev file.

import "elide:Jvm.pkl" as Jvm 

dependencies {
  maven {
    repositories {
      ["central"] = new Jvm.MavenRepositorySpec {
        name = "Maven Central"
        description = "The central Maven repository"
        url = "https:<<>>
      }
      ["google"] = "https://maven.google.com"
    }
  }
}

Or specify a local repository and connect to maven central

dependencies {
  maven {
    localRepository = ".m2/repository"
  }
}

JVM

Elide has a mechanism that allows for high level of configuration of how Elide interacts with the JVM.

In order to start configuring the JVM, you have to import the JVM-specific schema.

import "elide:Jvm.pkl" as Jvm
jvm {
  # your configuration here
}

At the high-level, you can specify what JVM you want elide to target and specify and entry point for your JVM.

jvm {
  main = "test.class"
  target = "latest"
  javaHome = "home"
}

Kotlin

Elide allows to configure Kotlin behavior.

kotlin {
  # your configuration here
}

plugins {
  ["plugin"] = {
    ["setting"] = "value",
  }
}

JavaScript

Elide allows to configure JavaScript ECMA level for the project.

javascript {
  ecma = "latest"
}

Native Image

Elide allows for configuration of project-wide native compiler.

In order to start configuring the native compiler, you have to import a specific schema.

import "elide:NativeImage.pkl" as NativeImage

nativeImage {
  # your configuration here
}

Engine

This configuration is responsible for configuration of the execution engine used by Elide when running a project.

engine {
  # your configuration here
}

Dev

Dev configurations allow Elide to integrate fully into a development process of a project.

In order to start configuring dev settings, you have to import a specific schema.

import "elide:Dev.pkl" as Dev

dev {
  # dev configuration here
}

resources {
      new Dev.McpResource {
        # some resource config
      }
    }

Toolchain

Toolchain settings let you configure which Elide engine version to use.

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

Artifacts

Elide can produce a variety of artifacts that can be placed into your project. These are declared as key-value pairs inside artifact configuration.

artifacts {
  ["some-artifact"] = {
    # some artifact
  }
}

import "elide:Jvm.pkl" as Jvm

artifacts {
  ["some-jar"] = new Jvm.Jar {
    # some config here
  }
}

Web

import "elide:Web.pkl" as Web

web {
  css {
    targets {
        new Web.CssTarget {
          # some config
        }
    }
  }
}

Elide Lockfile

Elide lockfile contains information about project metadata as well as a resolved dependency graph. It allows for faster elide build as unmodified dependency list will be skipped and resolved dependency graph will be used