Gradle Plugin

The Gradle plugin offers the following features:

Plugin versions coincide with Pkl versions. That is, plugin version x.y.z uses Pkl version x.y.z.

Installation

The Gradle plugin is available from Maven Central. It requires Java 11 or higher and Gradle 6.8 or higher. Earlier Gradle versions are not supported.

The plugin is applied as follows:

  • Groovy

  • Kotlin

build.gradle
plugins {
  id "org.pkl-lang" version "0.25.3"
}
settings.gradle
pluginManagement {
    repositories {
        mavenCentral()
    }
}
build.gradle.kts
plugins {
  id("org.pkl-lang") version "0.25.3"
}
settings.gradle.kts
pluginManagement {
    repositories {
        mavenCentral()
    }
}

Module Evaluation

This feature integrates the Pkl evaluator into Gradle builds.

Usage

To add an evaluator to the build, add a named configuration block inside pkl.evaluators:

  • build.gradle

  • build.gradle.kts

pkl {
  evaluators {
    evalPkl {
      sourceModules.add(file("module1.pkl"))
      transitiveModules.from file("module2.pkl")
      outputFile = layout.buildDirectory.file("module1.yaml")
      outputFormat = "yaml"
    }
  }
}
pkl {
  evaluators {
    register("evalPkl") {
      sourceModules.add(file("module1.pkl"))
      transitiveModules.from(file("module2.pkl"))
      outputFile.set(layout.buildDirectory.file("module1.yaml"))
      outputFormat.set("yaml")
    }
  }
}

To guarantee correct Gradle up-to-date behavior, transitiveModules needs to contain all module files transitively referenced by sourceModules.

For each declared evaluator, the Pkl plugin creates an equally named task. Hence the above evaluator can be run with:

$ ./gradlew evalPkl

For a ready-to-go example with full source code, see codegen-java in the pkl/pkl-examples repository.

Configuration Options

outputFormat: Property<String>

Default: "pcf"
Example: outputFormat = "yaml"
The output format to generate. The default output renderer for a module supports the following formats:

  • "json"

  • "jsonnet"

  • "pcf"

  • "plist"

  • "properties"

  • "textproto"

  • "xml"

  • "yaml"

outputFile: RegularFileProperty

Default: file("%{moduleDir}/%{moduleName}.%{outputFormat}") (places output files next to the source modules)
Example: outputFile = layout.projectDirectory.file("config.yaml")
The file path where the output file is placed. Relative paths are resolved against the project directory.

If multiple source modules are given, placeholders can be used to map them to different output files. The following placeholders are supported:

%{moduleDir}

The directory path of the module, relative to the working directory. Only available when evaluating file-based modules.

%{moduleName}

The simple module name as inferred from the module URI. For hierarchical module URIs such as file:///foo/bar/baz.pkl, this is the last path segment without file extension.

%{outputFormat}

The requested output format. Only available if outputFormat is set.

If multiple sources modules are mapped to the same output file, their outputs are concatenated. By default, module outputs are separated with ---, as in a YAML stream. The separator can be customized using the moduleOutputSeparator option.

multipleFileOutputDir: DirectoryProperty

Example 1: multipleFileOutputDir = layout.projectDirectory.dir("output")
Example 2: multipleFileOutputDir = layout.projectDirectory.file("%{moduleDir}/output") The directory where a module’s output files are placed.

Setting this option causes Pkl to evaluate a module’s output.files property and write the files specified therein. Within output.files, a key determines a file’s path relative to multipleFileOutputDir, and a value determines the file’s contents.

This option cannot be used together with any of the following:

This option supports the same placeholders as outputFile.

For additional details, see Multiple File Output in the language reference.

moduleOutputSeparator: Property<String>

Default: "---" (as in a YAML stream)
The separator to use when multiple module outputs are written to the same file.

expression: Property<String>

Default: (none)
Example: expression = "topLevelProperty.subValue"
The expression to be evaluated within the module.

This option causes Pkl to evaluate the provided expression instead of the module’s output.text or output.files properties. The resulting value is then stringified, and written to the designated output file.

For example, consider the following Pkl module:

my-pod.pkl
metadata {
  name = "my-pod"
}

The expression metadata.name evaluates to text my-pod.

Common properties:

sourceModules: ListProperty<Object>

Default: []
Example 1: sourceModules = ["module1.pkl", "module2.pkl"]
Example 2: sourceModules = fileTree("config").include("**/*.pkl")
List of Pkl modules which are used for this operation.

This property accepts the following types to represent a module:

  • java.net.URI

  • java.io.File

  • java.nio.file.Path

  • java.net.URL

  • java.lang.CharSequence - if the represented string looks like a URI (it contains a scheme), the input is treated as a URI. Otherwise, it is treated as a path. Relative paths are resolved against the project directory.

  • org.gradle.api.file.FileSystemLocation

transitiveModules: ConfigurableFileCollection

Default: files() (empty collection)
Example 1: transitiveModules.from files("module1.pkl", "module2.pkl")
Example 2: transitiveModules.from fileTree("config").include("**/*.pkl")
File paths of modules that are directly or indirectly used by source modules. Setting this option enables correct Gradle up-to-date checks, which ensures that your Pkl tasks are executed if any of the transitive files are modified; it does not affect evaluation otherwise. Including source modules in transitiveModules is permitted but not required. Relative paths are resolved against the project directory.

projectDir: DirectoryProperty

Default: null
Example 1: projectDir = layout.projectDirectory.dir("pkl")
Example 2: projectDir.fileValue file("/some/absolute/path")

Directory where the project lives.

A project is a directory that contains a PklProject file, which is used to declare package dependencies, as well as common evaluator settings to be applied in the project.

If null, this is determined by searching up from the working directory for a directory that contains a PklProject file, until evalRootDir or the file system root is reached.

omitProjectSettings: Property<Boolean>

Disables loading evaluator settings from the PklProject file.

noProject: Property<Boolean>

Disables all behavior related to projects.

settingsModule: Property<Object>

Default: null
Example: settingsModule = layout.projectDirectory.file("mySettings.pkl")
The Pkl settings module to use. This property accepts the same input types as the sourceModules property.

If null, ~/.pkl/settings.pkl or defaults specified in the pkl.settings standard library module are used.

allowedModules: ListProperty<String>

Default: ["pkl:", "file:", "modulepath:", "https:", "repl:", "package:", "projectpackage:"]
Example: allowedModules = ["file:"]
URI patterns that determine which modules can be loaded and evaluated. Patterns are matched against the beginning of module URIs. (File paths have been converted to file: URLs at this stage.) At least one pattern needs to match for a module to be loadable. Both source modules and transitive modules are subject to this check.

allowedResources: ListProperty<String>

Default: ["env:", "prop:", "modulepath:", "https:", "file:", "package:", "projectpackage:"]
Example: allowedResources = ["env:", "prop:"]
URL patterns that determine which external resources can be read. Patterns are matched against the beginning of resource URLs. At least one pattern needs to match for a resource to be readable.

environmentVariables: MapProperty<String, String>

Default: [:] (note that Gradle default differs from CLI default)
Example 1: environmentVariables = ["MY_VAR_1": "myValue1", "MY_VAR_2": "myValue2"]
Example 2: environmentVariables = System.getenv()
Environment variables that can be read by Pkl code with read("env:<envVariableName>").

evalRootDir: DirectoryProperty

Default: rootProject.layout.projectDirectory
Example 1: evalRootDir = layout.projectDirectory.dir("pkl-modules")
Example 2: evalRootDir.fileValue file("/some/absolute/path")

Root directory for file: modules and resources. If non-null, access to file-based modules and resources is restricted to those located under the root directory. Any symlinks are resolved before this check is performed.

evalTimeout: Property<java.time.Duration>

Default: null
Example: evalTimeout = Duration.ofSeconds(10)
Duration after which evaluation of a source module will be timed out. Note that a timeout is treated the same as a program error in that any subsequent source modules will not be evaluated.

externalProperties: MapProperty<String, String>

Default: [:]
Example: externalProperties = ["myProp1": "myValue1", "myProp2": "myValue2"]
External properties that can be read by Pkl code with read("prop:<propertyName>").

moduleCacheDir: DirectoryProperty

Default: null
Example 1: moduleCacheDir = layout.buildDirectory.dir("pkl-module-cache")
Example 2: moduleCacheDir.fileValue file("/absolute/path/to/cache")
The cache directory for storing packages. If null, defaults to ~/.pkl/cache.

noCache: Property<Boolean>

Default: false
Disable cacheing of packages.

modulePath: ConfigurableFileCollection

Default: files() (empty collection)
Example: modulePath.from files("dir1", "zip1.zip", "jar1.jar")
The directories, ZIP archives, or JAR archives to search when resolving modulepath: URIs. Relative paths are resolved against the project directory.

Tests

This feature integrates the Pkl test evaluator into Gradle builds.

Usage

To add tests to the build, add a named configuration block inside pkl.tests:

  • build.gradle

  • build.gradle.kts

pkl {
  tests {
    testPkl {
      sourceModules.add(files("module1_test.pkl", "module2_test.pkl"))
      junitReportsDir = layout.buildDirectory.dir("reports")
      overwrite = false
    }
  }
}
pkl {
  tests {
    register("testPkl") {
      sourceModules.addAll(files("module1_test.pkl", "module2_test.pkl"))
      junitReportsDir.set(layout.buildDirectory.dir("reports"))
      overwrite.set(false)
    }
  }
}
junitReportsDir: DirectoryProperty

Default: null
Example: junitReportsDir = layout.buildDirectory.dir("reports")
Whether and where to generate JUnit XML reports.

overwrite: Property<Boolean>

Default: false
Whether to ignore expected example files and generate them again.

Common properties:

sourceModules: ListProperty<Object>

Default: []
Example 1: sourceModules = ["module1.pkl", "module2.pkl"]
Example 2: sourceModules = fileTree("config").include("**/*.pkl")
List of Pkl modules which are used for this operation.

This property accepts the following types to represent a module:

  • java.net.URI

  • java.io.File

  • java.nio.file.Path

  • java.net.URL

  • java.lang.CharSequence - if the represented string looks like a URI (it contains a scheme), the input is treated as a URI. Otherwise, it is treated as a path. Relative paths are resolved against the project directory.

  • org.gradle.api.file.FileSystemLocation

transitiveModules: ConfigurableFileCollection

Default: files() (empty collection)
Example 1: transitiveModules.from files("module1.pkl", "module2.pkl")
Example 2: transitiveModules.from fileTree("config").include("**/*.pkl")
File paths of modules that are directly or indirectly used by source modules. Setting this option enables correct Gradle up-to-date checks, which ensures that your Pkl tasks are executed if any of the transitive files are modified; it does not affect evaluation otherwise. Including source modules in transitiveModules is permitted but not required. Relative paths are resolved against the project directory.

projectDir: DirectoryProperty

Default: null
Example 1: projectDir = layout.projectDirectory.dir("pkl")
Example 2: projectDir.fileValue file("/some/absolute/path")

Directory where the project lives.

A project is a directory that contains a PklProject file, which is used to declare package dependencies, as well as common evaluator settings to be applied in the project.

If null, this is determined by searching up from the working directory for a directory that contains a PklProject file, until evalRootDir or the file system root is reached.

omitProjectSettings: Property<Boolean>

Disables loading evaluator settings from the PklProject file.

noProject: Property<Boolean>

Disables all behavior related to projects.

settingsModule: Property<Object>

Default: null
Example: settingsModule = layout.projectDirectory.file("mySettings.pkl")
The Pkl settings module to use. This property accepts the same input types as the sourceModules property.

If null, ~/.pkl/settings.pkl or defaults specified in the pkl.settings standard library module are used.

allowedModules: ListProperty<String>

Default: ["pkl:", "file:", "modulepath:", "https:", "repl:", "package:", "projectpackage:"]
Example: allowedModules = ["file:"]
URI patterns that determine which modules can be loaded and evaluated. Patterns are matched against the beginning of module URIs. (File paths have been converted to file: URLs at this stage.) At least one pattern needs to match for a module to be loadable. Both source modules and transitive modules are subject to this check.

allowedResources: ListProperty<String>

Default: ["env:", "prop:", "modulepath:", "https:", "file:", "package:", "projectpackage:"]
Example: allowedResources = ["env:", "prop:"]
URL patterns that determine which external resources can be read. Patterns are matched against the beginning of resource URLs. At least one pattern needs to match for a resource to be readable.

environmentVariables: MapProperty<String, String>

Default: [:] (note that Gradle default differs from CLI default)
Example 1: environmentVariables = ["MY_VAR_1": "myValue1", "MY_VAR_2": "myValue2"]
Example 2: environmentVariables = System.getenv()
Environment variables that can be read by Pkl code with read("env:<envVariableName>").

evalRootDir: DirectoryProperty

Default: rootProject.layout.projectDirectory
Example 1: evalRootDir = layout.projectDirectory.dir("pkl-modules")
Example 2: evalRootDir.fileValue file("/some/absolute/path")

Root directory for file: modules and resources. If non-null, access to file-based modules and resources is restricted to those located under the root directory. Any symlinks are resolved before this check is performed.

evalTimeout: Property<java.time.Duration>

Default: null
Example: evalTimeout = Duration.ofSeconds(10)
Duration after which evaluation of a source module will be timed out. Note that a timeout is treated the same as a program error in that any subsequent source modules will not be evaluated.

externalProperties: MapProperty<String, String>

Default: [:]
Example: externalProperties = ["myProp1": "myValue1", "myProp2": "myValue2"]
External properties that can be read by Pkl code with read("prop:<propertyName>").

moduleCacheDir: DirectoryProperty

Default: null
Example 1: moduleCacheDir = layout.buildDirectory.dir("pkl-module-cache")
Example 2: moduleCacheDir.fileValue file("/absolute/path/to/cache")
The cache directory for storing packages. If null, defaults to ~/.pkl/cache.

noCache: Property<Boolean>

Default: false
Disable cacheing of packages.

modulePath: ConfigurableFileCollection

Default: files() (empty collection)
Example: modulePath.from files("dir1", "zip1.zip", "jar1.jar")
The directories, ZIP archives, or JAR archives to search when resolving modulepath: URIs. Relative paths are resolved against the project directory.

Java Code Generation

This feature integrates the Java code generator into Gradle builds.

Usage

To add a Java code generator to the build, add a named configuration block inside pkl.javaCodeGenerators:

  • build.gradle

  • build.gradle.kts

pkl {
  javaCodeGenerators {
    genJava {
      sourceModules.addAll(files("Template1.pkl", "Template2.pkl"))
    }
  }
}
pkl {
  javaCodeGenerators {
    register("genJava") {
      sourceModules.addAll(files("Template1.pkl", "Template2.pkl"))
    }
  }
}

To compile generated classes together with test code rather than main code, use sourceSet = sourceSets.test.

To generate getter methods instead of public final fields, use generateGetters = true.

For each declared Java code generator, the Pkl plugin creates an equally named task. Hence, the above generator can be run with:

$ ./gradlew genJava

For a ready-to-go example with full source code, see codegen-java in the pkl/pkl-examples repository.

Configuration Options

generateGetters: Property<Boolean>

Default: false
Example: generateGetters = true
Whether to generate private final fields and public getter methods rather than public final fields.

preferJavaxInjectAnnotation: Boolean

Default: false
Example: preferJavaxInjectAnnotation = true
Whether to annotate constructor parameters with @javax.inject.Named instead of @org.pkl.config.java.mapper.Named. If true, the generated code will have a compile dependency on javax.inject:javax.inject:1.

Common code generation properties:

indent: Property<String>

Default: " " (two spaces)
Example: indent = "\t" (one tab)
The characters to use for indenting generated source code.

outputDir: DirectoryProperty

Default: layout.buildDirectory.dir("generated/pkl/<generator_name>")
Example: outputDir = layout.projectDirectory.dir("src/main/pkl")
The directory where generated classes are placed.

The default places generated sources within the build directory of the project, to avoid sources from being committed into the repository on accident.

sourceSet: Property<SourceSet>

Default: sourceSets.main (if it exists; no default otherwise)
Example: sourceSet = sourceSets.test
The Gradle source set that generated code is compiled together with.

For the codegen tasks, the modulePath property defaults to the compilation classpath of this source set, as well as all of the source directories of the resource source directory set of this source set. This setup makes it possible to rely on modules defined in classpath dependencies of your project or in the resources of your project.

For projects which apply the idea plugin and are opened in IntelliJ IDEA, this option determines whether generated sources are marked as test sources (if the source set’s name contains the word "test") or regular sources (otherwise).

generateSpringBootConfig: Property<Boolean>

Default: false
Example: generateSpringBootConfig = true
Whether to generate config classes for use with Spring Boot.

Common properties:

sourceModules: ListProperty<Object>

Default: []
Example 1: sourceModules = ["module1.pkl", "module2.pkl"]
Example 2: sourceModules = fileTree("config").include("**/*.pkl")
List of Pkl modules which are used for this operation.

This property accepts the following types to represent a module:

  • java.net.URI

  • java.io.File

  • java.nio.file.Path

  • java.net.URL

  • java.lang.CharSequence - if the represented string looks like a URI (it contains a scheme), the input is treated as a URI. Otherwise, it is treated as a path. Relative paths are resolved against the project directory.

  • org.gradle.api.file.FileSystemLocation

transitiveModules: ConfigurableFileCollection

Default: files() (empty collection)
Example 1: transitiveModules.from files("module1.pkl", "module2.pkl")
Example 2: transitiveModules.from fileTree("config").include("**/*.pkl")
File paths of modules that are directly or indirectly used by source modules. Setting this option enables correct Gradle up-to-date checks, which ensures that your Pkl tasks are executed if any of the transitive files are modified; it does not affect evaluation otherwise. Including source modules in transitiveModules is permitted but not required. Relative paths are resolved against the project directory.

projectDir: DirectoryProperty

Default: null
Example 1: projectDir = layout.projectDirectory.dir("pkl")
Example 2: projectDir.fileValue file("/some/absolute/path")

Directory where the project lives.

A project is a directory that contains a PklProject file, which is used to declare package dependencies, as well as common evaluator settings to be applied in the project.

If null, this is determined by searching up from the working directory for a directory that contains a PklProject file, until evalRootDir or the file system root is reached.

omitProjectSettings: Property<Boolean>

Disables loading evaluator settings from the PklProject file.

noProject: Property<Boolean>

Disables all behavior related to projects.

settingsModule: Property<Object>

Default: null
Example: settingsModule = layout.projectDirectory.file("mySettings.pkl")
The Pkl settings module to use. This property accepts the same input types as the sourceModules property.

If null, ~/.pkl/settings.pkl or defaults specified in the pkl.settings standard library module are used.

allowedModules: ListProperty<String>

Default: ["pkl:", "file:", "modulepath:", "https:", "repl:", "package:", "projectpackage:"]
Example: allowedModules = ["file:"]
URI patterns that determine which modules can be loaded and evaluated. Patterns are matched against the beginning of module URIs. (File paths have been converted to file: URLs at this stage.) At least one pattern needs to match for a module to be loadable. Both source modules and transitive modules are subject to this check.

allowedResources: ListProperty<String>

Default: ["env:", "prop:", "modulepath:", "https:", "file:", "package:", "projectpackage:"]
Example: allowedResources = ["env:", "prop:"]
URL patterns that determine which external resources can be read. Patterns are matched against the beginning of resource URLs. At least one pattern needs to match for a resource to be readable.

environmentVariables: MapProperty<String, String>

Default: [:] (note that Gradle default differs from CLI default)
Example 1: environmentVariables = ["MY_VAR_1": "myValue1", "MY_VAR_2": "myValue2"]
Example 2: environmentVariables = System.getenv()
Environment variables that can be read by Pkl code with read("env:<envVariableName>").

evalRootDir: DirectoryProperty

Default: rootProject.layout.projectDirectory
Example 1: evalRootDir = layout.projectDirectory.dir("pkl-modules")
Example 2: evalRootDir.fileValue file("/some/absolute/path")

Root directory for file: modules and resources. If non-null, access to file-based modules and resources is restricted to those located under the root directory. Any symlinks are resolved before this check is performed.

evalTimeout: Property<java.time.Duration>

Default: null
Example: evalTimeout = Duration.ofSeconds(10)
Duration after which evaluation of a source module will be timed out. Note that a timeout is treated the same as a program error in that any subsequent source modules will not be evaluated.

externalProperties: MapProperty<String, String>

Default: [:]
Example: externalProperties = ["myProp1": "myValue1", "myProp2": "myValue2"]
External properties that can be read by Pkl code with read("prop:<propertyName>").

moduleCacheDir: DirectoryProperty

Default: null
Example 1: moduleCacheDir = layout.buildDirectory.dir("pkl-module-cache")
Example 2: moduleCacheDir.fileValue file("/absolute/path/to/cache")
The cache directory for storing packages. If null, defaults to ~/.pkl/cache.

noCache: Property<Boolean>

Default: false
Disable cacheing of packages.

modulePath: ConfigurableFileCollection

Default: files() (empty collection)
Example: modulePath.from files("dir1", "zip1.zip", "jar1.jar")
The directories, ZIP archives, or JAR archives to search when resolving modulepath: URIs. Relative paths are resolved against the project directory.

Kotlin Code Generation

This feature integrates the Kotlin code generator into Gradle builds.

Usage

To add a Kotlin code generator to the build, add a named configuration block inside pkl.kotlinCodeGenerators:

  • build.gradle

  • build.gradle.kts

pkl {
  kotlinCodeGenerators {
    genKotlin {
      sourceModules.addAll(files("Template1.pkl", "Template2.pkl"))
    }
  }
}
pkl {
  kotlinCodeGenerators {
    register("genKotlin") {
      sourceModules.addAll(files("Template1.pkl", "Template2.pkl"))
    }
  }
}

To compile generated classes together with test code rather than main code, use sourceSet = sourceSets.test.

For each declared Kotlin code generator, the Pkl plugin creates an equally named task. Hence the above generator can be run with:

$ ./gradlew genKotlin

For a ready-to-go example with full source code, see codegen-kotlin in the pkl/pkl-examples repository.

Configuration Options

(None)

Common code generation properties:

indent: Property<String>

Default: " " (two spaces)
Example: indent = "\t" (one tab)
The characters to use for indenting generated source code.

outputDir: DirectoryProperty

Default: layout.buildDirectory.dir("generated/pkl/<generator_name>")
Example: outputDir = layout.projectDirectory.dir("src/main/pkl")
The directory where generated classes are placed.

The default places generated sources within the build directory of the project, to avoid sources from being committed into the repository on accident.

sourceSet: Property<SourceSet>

Default: sourceSets.main (if it exists; no default otherwise)
Example: sourceSet = sourceSets.test
The Gradle source set that generated code is compiled together with.

For the codegen tasks, the modulePath property defaults to the compilation classpath of this source set, as well as all of the source directories of the resource source directory set of this source set. This setup makes it possible to rely on modules defined in classpath dependencies of your project or in the resources of your project.

For projects which apply the idea plugin and are opened in IntelliJ IDEA, this option determines whether generated sources are marked as test sources (if the source set’s name contains the word "test") or regular sources (otherwise).

generateSpringBootConfig: Property<Boolean>

Default: false
Example: generateSpringBootConfig = true
Whether to generate config classes for use with Spring Boot.

Common properties:

sourceModules: ListProperty<Object>

Default: []
Example 1: sourceModules = ["module1.pkl", "module2.pkl"]
Example 2: sourceModules = fileTree("config").include("**/*.pkl")
List of Pkl modules which are used for this operation.

This property accepts the following types to represent a module:

  • java.net.URI

  • java.io.File

  • java.nio.file.Path

  • java.net.URL

  • java.lang.CharSequence - if the represented string looks like a URI (it contains a scheme), the input is treated as a URI. Otherwise, it is treated as a path. Relative paths are resolved against the project directory.

  • org.gradle.api.file.FileSystemLocation

transitiveModules: ConfigurableFileCollection

Default: files() (empty collection)
Example 1: transitiveModules.from files("module1.pkl", "module2.pkl")
Example 2: transitiveModules.from fileTree("config").include("**/*.pkl")
File paths of modules that are directly or indirectly used by source modules. Setting this option enables correct Gradle up-to-date checks, which ensures that your Pkl tasks are executed if any of the transitive files are modified; it does not affect evaluation otherwise. Including source modules in transitiveModules is permitted but not required. Relative paths are resolved against the project directory.

projectDir: DirectoryProperty

Default: null
Example 1: projectDir = layout.projectDirectory.dir("pkl")
Example 2: projectDir.fileValue file("/some/absolute/path")

Directory where the project lives.

A project is a directory that contains a PklProject file, which is used to declare package dependencies, as well as common evaluator settings to be applied in the project.

If null, this is determined by searching up from the working directory for a directory that contains a PklProject file, until evalRootDir or the file system root is reached.

omitProjectSettings: Property<Boolean>

Disables loading evaluator settings from the PklProject file.

noProject: Property<Boolean>

Disables all behavior related to projects.

settingsModule: Property<Object>

Default: null
Example: settingsModule = layout.projectDirectory.file("mySettings.pkl")
The Pkl settings module to use. This property accepts the same input types as the sourceModules property.

If null, ~/.pkl/settings.pkl or defaults specified in the pkl.settings standard library module are used.

allowedModules: ListProperty<String>

Default: ["pkl:", "file:", "modulepath:", "https:", "repl:", "package:", "projectpackage:"]
Example: allowedModules = ["file:"]
URI patterns that determine which modules can be loaded and evaluated. Patterns are matched against the beginning of module URIs. (File paths have been converted to file: URLs at this stage.) At least one pattern needs to match for a module to be loadable. Both source modules and transitive modules are subject to this check.

allowedResources: ListProperty<String>

Default: ["env:", "prop:", "modulepath:", "https:", "file:", "package:", "projectpackage:"]
Example: allowedResources = ["env:", "prop:"]
URL patterns that determine which external resources can be read. Patterns are matched against the beginning of resource URLs. At least one pattern needs to match for a resource to be readable.

environmentVariables: MapProperty<String, String>

Default: [:] (note that Gradle default differs from CLI default)
Example 1: environmentVariables = ["MY_VAR_1": "myValue1", "MY_VAR_2": "myValue2"]
Example 2: environmentVariables = System.getenv()
Environment variables that can be read by Pkl code with read("env:<envVariableName>").

evalRootDir: DirectoryProperty

Default: rootProject.layout.projectDirectory
Example 1: evalRootDir = layout.projectDirectory.dir("pkl-modules")
Example 2: evalRootDir.fileValue file("/some/absolute/path")

Root directory for file: modules and resources. If non-null, access to file-based modules and resources is restricted to those located under the root directory. Any symlinks are resolved before this check is performed.

evalTimeout: Property<java.time.Duration>

Default: null
Example: evalTimeout = Duration.ofSeconds(10)
Duration after which evaluation of a source module will be timed out. Note that a timeout is treated the same as a program error in that any subsequent source modules will not be evaluated.

externalProperties: MapProperty<String, String>

Default: [:]
Example: externalProperties = ["myProp1": "myValue1", "myProp2": "myValue2"]
External properties that can be read by Pkl code with read("prop:<propertyName>").

moduleCacheDir: DirectoryProperty

Default: null
Example 1: moduleCacheDir = layout.buildDirectory.dir("pkl-module-cache")
Example 2: moduleCacheDir.fileValue file("/absolute/path/to/cache")
The cache directory for storing packages. If null, defaults to ~/.pkl/cache.

noCache: Property<Boolean>

Default: false
Disable cacheing of packages.

modulePath: ConfigurableFileCollection

Default: files() (empty collection)
Example: modulePath.from files("dir1", "zip1.zip", "jar1.jar")
The directories, ZIP archives, or JAR archives to search when resolving modulepath: URIs. Relative paths are resolved against the project directory.

Pkldoc generation

This features integrates the Pkldoc generator into Gradle builds.

Usage

To add a Pkldoc generator to the build, add a named configuration block inside pkl.pkldocGenerators:

  • build.gradle

  • build.gradle.kts

pkl {
  pkldocGenerators {
    pkldoc {
      sourceModules.addAll(files("doc-package-info.pkl", "Template1.pkl", "Template2.pkl"))
    }
  }
}
pkl {
  pkldocGenerators {
    register("pkldoc") {
      sourceModules.addAll(files("doc-package-info.pkl", "Template1.pkl", "Template2.pkl"))
    }
  }
}

For each declared Pkldoc generator, the Pkl plugin creates an equally named task. Hence, the above generator can be run with:

$ ./gradlew pkldoc

For a ready-to-go example with full source code, see pkldoc in the pkl/pkl-examples repository.

Configuration Options

The following properties can be configured inside a Pkldoc generator’s configuration block:

outputDir: DirectoryProperty

Default: layout.buildDirectory.dir("pkldoc/<generator_name>")
Example: outputDir = layout.projectDirectory.dir("pkl-docs")
The directory where generated documentation is placed.

Common properties:

sourceModules: ListProperty<Object>

Default: []
Example 1: sourceModules = ["module1.pkl", "module2.pkl"]
Example 2: sourceModules = fileTree("config").include("**/*.pkl")
List of Pkl modules which are used for this operation.

This property accepts the following types to represent a module:

  • java.net.URI

  • java.io.File

  • java.nio.file.Path

  • java.net.URL

  • java.lang.CharSequence - if the represented string looks like a URI (it contains a scheme), the input is treated as a URI. Otherwise, it is treated as a path. Relative paths are resolved against the project directory.

  • org.gradle.api.file.FileSystemLocation

transitiveModules: ConfigurableFileCollection

Default: files() (empty collection)
Example 1: transitiveModules.from files("module1.pkl", "module2.pkl")
Example 2: transitiveModules.from fileTree("config").include("**/*.pkl")
File paths of modules that are directly or indirectly used by source modules. Setting this option enables correct Gradle up-to-date checks, which ensures that your Pkl tasks are executed if any of the transitive files are modified; it does not affect evaluation otherwise. Including source modules in transitiveModules is permitted but not required. Relative paths are resolved against the project directory.

projectDir: DirectoryProperty

Default: null
Example 1: projectDir = layout.projectDirectory.dir("pkl")
Example 2: projectDir.fileValue file("/some/absolute/path")

Directory where the project lives.

A project is a directory that contains a PklProject file, which is used to declare package dependencies, as well as common evaluator settings to be applied in the project.

If null, this is determined by searching up from the working directory for a directory that contains a PklProject file, until evalRootDir or the file system root is reached.

omitProjectSettings: Property<Boolean>

Disables loading evaluator settings from the PklProject file.

noProject: Property<Boolean>

Disables all behavior related to projects.

settingsModule: Property<Object>

Default: null
Example: settingsModule = layout.projectDirectory.file("mySettings.pkl")
The Pkl settings module to use. This property accepts the same input types as the sourceModules property.

If null, ~/.pkl/settings.pkl or defaults specified in the pkl.settings standard library module are used.

allowedModules: ListProperty<String>

Default: ["pkl:", "file:", "modulepath:", "https:", "repl:", "package:", "projectpackage:"]
Example: allowedModules = ["file:"]
URI patterns that determine which modules can be loaded and evaluated. Patterns are matched against the beginning of module URIs. (File paths have been converted to file: URLs at this stage.) At least one pattern needs to match for a module to be loadable. Both source modules and transitive modules are subject to this check.

allowedResources: ListProperty<String>

Default: ["env:", "prop:", "modulepath:", "https:", "file:", "package:", "projectpackage:"]
Example: allowedResources = ["env:", "prop:"]
URL patterns that determine which external resources can be read. Patterns are matched against the beginning of resource URLs. At least one pattern needs to match for a resource to be readable.

environmentVariables: MapProperty<String, String>

Default: [:] (note that Gradle default differs from CLI default)
Example 1: environmentVariables = ["MY_VAR_1": "myValue1", "MY_VAR_2": "myValue2"]
Example 2: environmentVariables = System.getenv()
Environment variables that can be read by Pkl code with read("env:<envVariableName>").

evalRootDir: DirectoryProperty

Default: rootProject.layout.projectDirectory
Example 1: evalRootDir = layout.projectDirectory.dir("pkl-modules")
Example 2: evalRootDir.fileValue file("/some/absolute/path")

Root directory for file: modules and resources. If non-null, access to file-based modules and resources is restricted to those located under the root directory. Any symlinks are resolved before this check is performed.

evalTimeout: Property<java.time.Duration>

Default: null
Example: evalTimeout = Duration.ofSeconds(10)
Duration after which evaluation of a source module will be timed out. Note that a timeout is treated the same as a program error in that any subsequent source modules will not be evaluated.

externalProperties: MapProperty<String, String>

Default: [:]
Example: externalProperties = ["myProp1": "myValue1", "myProp2": "myValue2"]
External properties that can be read by Pkl code with read("prop:<propertyName>").

moduleCacheDir: DirectoryProperty

Default: null
Example 1: moduleCacheDir = layout.buildDirectory.dir("pkl-module-cache")
Example 2: moduleCacheDir.fileValue file("/absolute/path/to/cache")
The cache directory for storing packages. If null, defaults to ~/.pkl/cache.

noCache: Property<Boolean>

Default: false
Disable cacheing of packages.

modulePath: ConfigurableFileCollection

Default: files() (empty collection)
Example: modulePath.from files("dir1", "zip1.zip", "jar1.jar")
The directories, ZIP archives, or JAR archives to search when resolving modulepath: URIs. Relative paths are resolved against the project directory.

Project packaging

This feature is the Gradle analogy for the project package command in the CLI. It prepares package assets to be published from a project.

There are two differences between this feature and the CLI:

  • Input project directories are required (the CLI determines a project from the current working directory if arguments are omitted).

  • Output directory defaults to a path within the build directory.

Usage

  • build.gradle

  • build.gradle.kts

pkl {
  project {
    packagers {
      makePackages {
        projectDirectories.from(file("pkl-config/"))
      }
    }
  }
}
pkl {
  project {
    packagers {
      register("makePackages") {
        projectDirectories.from(file("pkl-config/"))
      }
    }
  }
}

For each declared packager, the Pkl plugin creates an equally named task. Hence, the above packager can be run with:

$ ./gradlew makePackages

Configuration Options

projectDirectories: ConfigurableFileCollection

Default: (none)
Example: projectDirectories.from(file("pkl-config/""))
The project directories to create packages for.

skipPublishCheck: Property<Boolean>

Default: (false)
Example: skipPublishCheck.set(true)

Skips checking whether a package has already been published with different contents.

By default, the packager will check whether a package at the same version has already been published. If the package has been published, it validates that the package’s metadata is identical to the locally generated metadata.

outputPath: DirectoryProperty

Default: project.getLayout().getBuildDirectory().dir("generated/pkl/packages")

The directory to write artifacts to. Accepts the following placeholders:

%{name}

The name of the package

%{version}

The version of the package

junitReportsDir: DirectoryProperty

Default: null
Example: junitReportsDir = layout.buildDirectory.dir("reports")
Whether and where to generate JUnit XML reports.

overwrite: Property<Boolean>

Default: false
Whether to ignore expected example files and generate them again.

Common propeties:

allowedModules: ListProperty<String>

Default: ["pkl:", "file:", "modulepath:", "https:", "repl:", "package:", "projectpackage:"]
Example: allowedModules = ["file:"]
URI patterns that determine which modules can be loaded and evaluated. Patterns are matched against the beginning of module URIs. (File paths have been converted to file: URLs at this stage.) At least one pattern needs to match for a module to be loadable. Both source modules and transitive modules are subject to this check.

allowedResources: ListProperty<String>

Default: ["env:", "prop:", "modulepath:", "https:", "file:", "package:", "projectpackage:"]
Example: allowedResources = ["env:", "prop:"]
URL patterns that determine which external resources can be read. Patterns are matched against the beginning of resource URLs. At least one pattern needs to match for a resource to be readable.

environmentVariables: MapProperty<String, String>

Default: [:] (note that Gradle default differs from CLI default)
Example 1: environmentVariables = ["MY_VAR_1": "myValue1", "MY_VAR_2": "myValue2"]
Example 2: environmentVariables = System.getenv()
Environment variables that can be read by Pkl code with read("env:<envVariableName>").

evalRootDir: DirectoryProperty

Default: rootProject.layout.projectDirectory
Example 1: evalRootDir = layout.projectDirectory.dir("pkl-modules")
Example 2: evalRootDir.fileValue file("/some/absolute/path")

Root directory for file: modules and resources. If non-null, access to file-based modules and resources is restricted to those located under the root directory. Any symlinks are resolved before this check is performed.

evalTimeout: Property<java.time.Duration>

Default: null
Example: evalTimeout = Duration.ofSeconds(10)
Duration after which evaluation of a source module will be timed out. Note that a timeout is treated the same as a program error in that any subsequent source modules will not be evaluated.

externalProperties: MapProperty<String, String>

Default: [:]
Example: externalProperties = ["myProp1": "myValue1", "myProp2": "myValue2"]
External properties that can be read by Pkl code with read("prop:<propertyName>").

moduleCacheDir: DirectoryProperty

Default: null
Example 1: moduleCacheDir = layout.buildDirectory.dir("pkl-module-cache")
Example 2: moduleCacheDir.fileValue file("/absolute/path/to/cache")
The cache directory for storing packages. If null, defaults to ~/.pkl/cache.

noCache: Property<Boolean>

Default: false
Disable cacheing of packages.

modulePath: ConfigurableFileCollection

Default: files() (empty collection)
Example: modulePath.from files("dir1", "zip1.zip", "jar1.jar")
The directories, ZIP archives, or JAR archives to search when resolving modulepath: URIs. Relative paths are resolved against the project directory.

Project Resolving

This feature is the Gradle analogy for the project resolve command in the CLI. It takes the dependencies of a project, and writes the resolved versions a file at path PklProject.deps.json, within the root directory of the project.

Usage

  • build.gradle

  • build.gradle.kts

pkl {
  project {
    resolvers {
      resolvePklDeps {
        projectDirectories.from(file("pkl-config/"))
      }
    }
  }
}
pkl {
  project {
    resolvers {
      register("resolvePklDeps") {
        projectDirectories.from(file("pkl-config/"))
      }
    }
  }
}

For each declared resolver, the Pkl plugin creates an equally named task. Hence, the above resolver can be run with:

$ ./gradlew resolvePklDeps

Configuration Options

projectDirectories: ConfigurableFileCollection

Default: (none)
Example: projectDirectories.from(file("pkl-config/""))
The project directories to create packages for.

Common propeties:

allowedModules: ListProperty<String>

Default: ["pkl:", "file:", "modulepath:", "https:", "repl:", "package:", "projectpackage:"]
Example: allowedModules = ["file:"]
URI patterns that determine which modules can be loaded and evaluated. Patterns are matched against the beginning of module URIs. (File paths have been converted to file: URLs at this stage.) At least one pattern needs to match for a module to be loadable. Both source modules and transitive modules are subject to this check.

allowedResources: ListProperty<String>

Default: ["env:", "prop:", "modulepath:", "https:", "file:", "package:", "projectpackage:"]
Example: allowedResources = ["env:", "prop:"]
URL patterns that determine which external resources can be read. Patterns are matched against the beginning of resource URLs. At least one pattern needs to match for a resource to be readable.

environmentVariables: MapProperty<String, String>

Default: [:] (note that Gradle default differs from CLI default)
Example 1: environmentVariables = ["MY_VAR_1": "myValue1", "MY_VAR_2": "myValue2"]
Example 2: environmentVariables = System.getenv()
Environment variables that can be read by Pkl code with read("env:<envVariableName>").

evalRootDir: DirectoryProperty

Default: rootProject.layout.projectDirectory
Example 1: evalRootDir = layout.projectDirectory.dir("pkl-modules")
Example 2: evalRootDir.fileValue file("/some/absolute/path")

Root directory for file: modules and resources. If non-null, access to file-based modules and resources is restricted to those located under the root directory. Any symlinks are resolved before this check is performed.

evalTimeout: Property<java.time.Duration>

Default: null
Example: evalTimeout = Duration.ofSeconds(10)
Duration after which evaluation of a source module will be timed out. Note that a timeout is treated the same as a program error in that any subsequent source modules will not be evaluated.

externalProperties: MapProperty<String, String>

Default: [:]
Example: externalProperties = ["myProp1": "myValue1", "myProp2": "myValue2"]
External properties that can be read by Pkl code with read("prop:<propertyName>").

moduleCacheDir: DirectoryProperty

Default: null
Example 1: moduleCacheDir = layout.buildDirectory.dir("pkl-module-cache")
Example 2: moduleCacheDir.fileValue file("/absolute/path/to/cache")
The cache directory for storing packages. If null, defaults to ~/.pkl/cache.

noCache: Property<Boolean>

Default: false
Disable cacheing of packages.

modulePath: ConfigurableFileCollection

Default: files() (empty collection)
Example: modulePath.from files("dir1", "zip1.zip", "jar1.jar")
The directories, ZIP archives, or JAR archives to search when resolving modulepath: URIs. Relative paths are resolved against the project directory.