Initial commit

docs/modules/pkl-gradle/partials/gradle-codegen-properties.adoc

@@ -0,0 +1,39 @@
+.indent: Property<String>
+[%collapsible]
+====
+Default: `"  "` (two spaces) +
+Example: `indent = "\t"` (one tab) +
+The characters to use for indenting generated source code.
+====
+
+.outputDir: DirectoryProperty
+[%collapsible]
+====
+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>
+[%collapsible]
+====
+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>
+[%collapsible]
+====
+Default: `false` +
+Example: `generateSpringBootConfig = true` +
+Whether to generate config classes for use with Spring Boot.
+====
+
+// TODO: fixme (implementSerializable)

docs/modules/pkl-gradle/partials/gradle-common-properties.adoc

@@ -0,0 +1,85 @@
+.allowedModules: ListProperty<String>
+[%collapsible]
+====
+Default: `["pkl:", "file:", "modulepath:", "https:", "repl:", "package:", "projectpackage:"]` +
+Example: `allowedModules = ["file:"]` +
+URI patterns that determine which modules can be loaded and evaluated.
+Patterns are matched against the beginning of module URIs.
+(File paths have been converted to `file:` URLs at this stage.)
+At least one pattern needs to match for a module to be loadable.
+Both source modules and transitive modules are subject to this check.
+====
+
+.allowedResources: ListProperty<String>
+[%collapsible]
+====
+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>
+[%collapsible]
+====
+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
+[%collapsible]
+====
+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>
+[%collapsible]
+====
+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>
+[%collapsible]
+====
+Default: `[:]` +
+Example: `externalProperties = ["myProp1": "myValue1", "myProp2": "myValue2"]` +
+External properties that can be read by Pkl code with `read("prop:<propertyName>")`.
+====
+
+.moduleCacheDir: DirectoryProperty
+[%collapsible]
+====
+Default: `null` +
+Example 1: `moduleCacheDir = layout.buildDirectory.dir("pkl-module-cache")` +
+Example 2: `moduleCacheDir.fileValue file("/absolute/path/to/cache")` +
+The cache directory for storing packages.
+If `null`, defaults to `~/.pkl/cache`.
+====
+
+.noCache: Property<Boolean>
+[%collapsible]
+====
+Default: `false` +
+Disable cacheing of packages.
+====
+
+.modulePath: ConfigurableFileCollection
+[%collapsible]
+====
+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.
+====

docs/modules/pkl-gradle/partials/gradle-modules-properties.adoc

@@ -0,0 +1,69 @@
+
+.sourceModules: ListProperty<Object>
+[%collapsible]
+====
+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
+[%collapsible]
+====
+Default: `files()` (empty collection) +
+Example 1: `transitiveModules.from files("module1.pkl", "module2.pkl")` +
+Example 2: `+transitiveModules.from fileTree("config").include("**/*.pkl")+` +
+File paths of modules that are directly or indirectly used by source modules.
+Setting this option enables correct Gradle up-to-date checks, which ensures that your Pkl tasks are executed if any of the transitive files are modified; it does not affect evaluation otherwise.
+Including source modules in `transitiveModules` is permitted but not required.
+Relative paths are resolved against the project directory.
+====
+
+.projectDir: DirectoryProperty
+[%collapsible]
+====
+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>
+[%collapsible]
+====
+Disables loading evaluator settings from the PklProject file.
+====
+
+.noProject: Property<Boolean>
+[%collapsible]
+====
+Disables all behavior related to projects.
+====
+
+.settingsModule: Property<Object>
+[%collapsible]
+====
+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.
+====
+
+include::../partials/gradle-common-properties.adoc[]