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 17 or higher and Gradle 8.1 or higher. Earlier Gradle versions are not supported.

The plugin is applied as follows:

  • Kotlin

  • Groovy

build.gradle.kts
plugins {
  id("org.pkl-lang") version "0.27.0"
}
settings.gradle.kts
pluginManagement {
    repositories {
        mavenCentral()
    }
}
build.gradle
plugins {
  id "org.pkl-lang" version "0.27.0"
}
settings.gradle
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"))
      outputFile = layout.buildDirectory.file("module1.yaml")
      outputFormat = "yaml"
    }
  }
}
pkl {
  evaluators {
    register("evalPkl") {
      sourceModules.add(file("module1.pkl"))
      outputFile.set(layout.buildDirectory.file("module1.yaml"))
      outputFormat.set("yaml")
    }
  }
}

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: [computed by pkl-gradle]
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.

This property, along with sourceModules, is the set of input files used to determine whether this task is up-to-date or not.

By default, Pkl computes this property by analyzing the imports of the source modules. Setting this property explicitly causes Pkl to skip the analyze imports step.

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.

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.

color: Property<Boolean>

Default: false
Format messages using ANSI color.

noCache: Property<Boolean>

Default: false
Disable caching 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.

proxy: Property<URI>

Default: null
Example: proxy = uri("http://proxy.example.com:1234")
Configures HTTP connections to connect to the provided proxy address. The URI must have scheme http, and may not contain anything other than a host and port.

noProxy: ListProperty<String>

Default: null
Example: noProxy = ["example.com", "169.254.0.0/16"]
Hosts to which all connections should bypass the proxy. Hosts can be specified by name, IP address, or IP range using CIDR notation.

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: [computed by pkl-gradle]
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.

This property, along with sourceModules, is the set of input files used to determine whether this task is up-to-date or not.

By default, Pkl computes this property by analyzing the imports of the source modules. Setting this property explicitly causes Pkl to skip the analyze imports step.

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.

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.

color: Property<Boolean>

Default: false
Format messages using ANSI color.

noCache: Property<Boolean>

Default: false
Disable caching 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.

proxy: Property<URI>

Default: null
Example: proxy = uri("http://proxy.example.com:1234")
Configures HTTP connections to connect to the provided proxy address. The URI must have scheme http, and may not contain anything other than a host and port.

noProxy: ListProperty<String>

Default: null
Example: noProxy = ["example.com", "169.254.0.0/16"]
Hosts to which all connections should bypass the proxy. Hosts can be specified by name, IP address, or IP range using CIDR notation.

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.

renames: MapProperty<String, String>

Default: [:]
Example: renames = ["foo.": "com.example.foo.", "bar.Config": "com.example.bar.Config"]
Allows to change default class and package names (derived from Pkl module names) in the generated code.

When you need the generated class or package names to be different from the default names derived from the Pkl module names, you can define a rename mapping, where the key is the original Pkl module name prefix, and the value is its replacement. When you do, the generated code’s package declarations, class names, as well as file locations, will be modified according to this mapping.

The prefixes are replaced literally, which means that dots at the end are important. If you want to rename packages only, in most cases, you must ensure that you have an ending dot on both sides of a mapping (except for an empty mapping, if you use it), otherwise you may get unexpected results:

// Assuming the following mapping configuration:
renames = [
  "com.foo.": "x",  // Dot on the left only
  "org.bar": "y.",  // Dot on the right only
  "net.baz": "z"    // No dots
]

// The following renames will be made:
"com.foo.bar" -> "xbar"       // Target prefix merged into the suffix
"org.bar.baz" -> "y..baz"     // Double dot, invalid name
"net.baz.qux" -> "z.qux"      // Looks okay, but...
"net.bazqux"  -> "zqux"       // ...may cut the name in the middle.

When computing the appropriate target name, the longest matching prefix is used:

// Assuming the following mapping configuration:
renames = [
  "com.foo.Main": "w.Main",
  "com.foo.": "x.",
  "com.": "y.",
  "": "z."
]

// The following renames will be made:
com.foo.Main -> w.Main
com.foo.bar  -> x.bar
com.baz.qux  -> y.baz.qux
org.foo.bar  -> z.org.foo.bar

Keys in this mapping can be arbitrary strings, including an empty string. Values must be valid dot-separated fully qualifed class name prefixes, possibly terminated by a dot.

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: [computed by pkl-gradle]
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.

This property, along with sourceModules, is the set of input files used to determine whether this task is up-to-date or not.

By default, Pkl computes this property by analyzing the imports of the source modules. Setting this property explicitly causes Pkl to skip the analyze imports step.

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.

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.

color: Property<Boolean>

Default: false
Format messages using ANSI color.

noCache: Property<Boolean>

Default: false
Disable caching 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.

proxy: Property<URI>

Default: null
Example: proxy = uri("http://proxy.example.com:1234")
Configures HTTP connections to connect to the provided proxy address. The URI must have scheme http, and may not contain anything other than a host and port.

noProxy: ListProperty<String>

Default: null
Example: noProxy = ["example.com", "169.254.0.0/16"]
Hosts to which all connections should bypass the proxy. Hosts can be specified by name, IP address, or IP range using CIDR notation.

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.

renames: MapProperty<String, String>

Default: [:]
Example: renames = ["foo.": "com.example.foo.", "bar.Config": "com.example.bar.Config"]
Allows to change default class and package names (derived from Pkl module names) in the generated code.

When you need the generated class or package names to be different from the default names derived from the Pkl module names, you can define a rename mapping, where the key is the original Pkl module name prefix, and the value is its replacement. When you do, the generated code’s package declarations, class names, as well as file locations, will be modified according to this mapping.

The prefixes are replaced literally, which means that dots at the end are important. If you want to rename packages only, in most cases, you must ensure that you have an ending dot on both sides of a mapping (except for an empty mapping, if you use it), otherwise you may get unexpected results:

// Assuming the following mapping configuration:
renames = [
  "com.foo.": "x",  // Dot on the left only
  "org.bar": "y.",  // Dot on the right only
  "net.baz": "z"    // No dots
]

// The following renames will be made:
"com.foo.bar" -> "xbar"       // Target prefix merged into the suffix
"org.bar.baz" -> "y..baz"     // Double dot, invalid name
"net.baz.qux" -> "z.qux"      // Looks okay, but...
"net.bazqux"  -> "zqux"       // ...may cut the name in the middle.

When computing the appropriate target name, the longest matching prefix is used:

// Assuming the following mapping configuration:
renames = [
  "com.foo.Main": "w.Main",
  "com.foo.": "x.",
  "com.": "y.",
  "": "z."
]

// The following renames will be made:
com.foo.Main -> w.Main
com.foo.bar  -> x.bar
com.baz.qux  -> y.baz.qux
org.foo.bar  -> z.org.foo.bar

Keys in this mapping can be arbitrary strings, including an empty string. Values must be valid dot-separated fully qualifed class name prefixes, possibly terminated by a dot.

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: [computed by pkl-gradle]
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.

This property, along with sourceModules, is the set of input files used to determine whether this task is up-to-date or not.

By default, Pkl computes this property by analyzing the imports of the source modules. Setting this property explicitly causes Pkl to skip the analyze imports step.

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.

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.

color: Property<Boolean>

Default: false
Format messages using ANSI color.

noCache: Property<Boolean>

Default: false
Disable caching 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.

proxy: Property<URI>

Default: null
Example: proxy = uri("http://proxy.example.com:1234")
Configures HTTP connections to connect to the provided proxy address. The URI must have scheme http, and may not contain anything other than a host and port.

noProxy: ListProperty<String>

Default: null
Example: noProxy = ["example.com", "169.254.0.0/16"]
Hosts to which all connections should bypass the proxy. Hosts can be specified by name, IP address, or IP range using CIDR notation.

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: [computed by pkl-gradle]
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.

This property, along with sourceModules, is the set of input files used to determine whether this task is up-to-date or not.

By default, Pkl computes this property by analyzing the imports of the source modules. Setting this property explicitly causes Pkl to skip the analyze imports step.

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.

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.

color: Property<Boolean>

Default: false
Format messages using ANSI color.

noCache: Property<Boolean>

Default: false
Disable caching 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.

proxy: Property<URI>

Default: null
Example: proxy = uri("http://proxy.example.com:1234")
Configures HTTP connections to connect to the provided proxy address. The URI must have scheme http, and may not contain anything other than a host and port.

noProxy: ListProperty<String>

Default: null
Example: noProxy = ["example.com", "169.254.0.0/16"]
Hosts to which all connections should bypass the proxy. Hosts can be specified by name, IP address, or IP range using CIDR notation.

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 properties:

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.

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.

color: Property<Boolean>

Default: false
Format messages using ANSI color.

noCache: Property<Boolean>

Default: false
Disable caching 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.

proxy: Property<URI>

Default: null
Example: proxy = uri("http://proxy.example.com:1234")
Configures HTTP connections to connect to the provided proxy address. The URI must have scheme http, and may not contain anything other than a host and port.

noProxy: ListProperty<String>

Default: null
Example: noProxy = ["example.com", "169.254.0.0/16"]
Hosts to which all connections should bypass the proxy. Hosts can be specified by name, IP address, or IP range using CIDR notation.

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 properties:

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.

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.

color: Property<Boolean>

Default: false
Format messages using ANSI color.

noCache: Property<Boolean>

Default: false
Disable caching 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.

proxy: Property<URI>

Default: null
Example: proxy = uri("http://proxy.example.com:1234")
Configures HTTP connections to connect to the provided proxy address. The URI must have scheme http, and may not contain anything other than a host and port.

noProxy: ListProperty<String>

Default: null
Example: noProxy = ["example.com", "169.254.0.0/16"]
Hosts to which all connections should bypass the proxy. Hosts can be specified by name, IP address, or IP range using CIDR notation.

Analyze Imports

This feature is the Gradle analogy for the analyze imports command in the CLI. It builds a graph of imports of the provided source modules.

Usage

  • build.gradle

  • build.gradle.kts

pkl {
  analyzers {
    imports {
      appConfig {
        sourceModules.add(file("src/main/resources/appConfig.pkl"))
      }
    }
  }
}
pkl {
  analyzers {
    imports {
      register("appConfig") {
        sourceModules.add(file("src/main/resources/appConfig.pkl"))
      }
    }
  }
}

Configuration Options

outputFormat: Property<String>

Same meaning as outputFormat in Module Evaluation.

outputFile: RegularFileProperty<String>

Same meaning as outputFile in Module Evaluation.

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: [computed by pkl-gradle]
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.

This property, along with sourceModules, is the set of input files used to determine whether this task is up-to-date or not.

By default, Pkl computes this property by analyzing the imports of the source modules. Setting this property explicitly causes Pkl to skip the analyze imports step.

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.

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.

color: Property<Boolean>

Default: false
Format messages using ANSI color.

noCache: Property<Boolean>

Default: false
Disable caching 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.

proxy: Property<URI>

Default: null
Example: proxy = uri("http://proxy.example.com:1234")
Configures HTTP connections to connect to the provided proxy address. The URI must have scheme http, and may not contain anything other than a host and port.

noProxy: ListProperty<String>

Default: null
Example: noProxy = ["example.com", "169.254.0.0/16"]
Hosts to which all connections should bypass the proxy. Hosts can be specified by name, IP address, or IP range using CIDR notation.