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.
Snapshots are published to repository https://s01.oss.sonatype.org/content/groups/public .
|
The plugin is applied as follows:
-
Kotlin
-
Groovy
plugins {
id("org.pkl-lang") version "0.28.0-SNAPSHOT"
}
pluginManagement {
repositories {
maven(url = "https://s01.oss.sonatype.org/content/groups/public")
}
}
plugins {
id "org.pkl-lang" version "0.28.0-SNAPSHOT"
}
pluginManagement {
repositories {
maven { url "https://s01.oss.sonatype.org/content/groups/public" }
}
}
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:
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.