mirror of
https://github.com/apple/pkl.git
synced 2026-01-17 00:47:07 +01:00
b445713b8c
This adds logic to build and publish the other executables related to Pkl. These are: * pkl-doc * pkl-codegen-kotlin * pkl-codegen-java pkl-codegen-kotlin and pkl-codegen-java are published as executable JARs, whereas pkldoc is published both as an executable JAR, and also native executables (matching the set of os/arch supported by Pkl). The reason this only publishes executable JARs for pkl-codegen-kotlin and pkl-codegen-java is because we expect that the Java requirement is not a problem for these users, and that the native executable provides negligible added value. As part of this, the following changes are made: * Introduce `pklJavaExecutable` plugin, which sets up building and publishing of executable JAR. * Introduce `pklNativeExecutable` plugin, which sets up building and publishing of native executables. * Introduce `NativeImageBuild` Gradle task, which knows how to build native-image executables. * Introduce `ExecutableSpec` extension, for projects that publish executables to configure how those executables should be published. * `./griddles buildNative`, by default, will only build the executable of the host OS/Arch, and will no longer cross-build. * The target arch of `./gradlew buildNative` can be changed using `-Dpkl.targetArch=<aarch64|amd64>`. * On linux/amd64 only, with `./gradlew buildNative`, a statically linked executable can be built using `-Dpkl.musl=true` * Make `javaExecutable` a dependency of `assemble` * Make `testStartJavaExecutable` a dependency of `check` * Change name `pklNativeBuild` to `pklNativeLifecycle` to better match the plugin's purpose * Remove Truffle SVM classes from main source set (don't publish these classes as part of the pkl-cli JAR) * Change CircleCI definition to publish new executables * Change CircleCI definition to call `buildNative` instead of individual task names
172 lines
4.2 KiB
Plaintext
172 lines
4.2 KiB
Plaintext
= Kotlin Code Generator
|
|
include::ROOT:partial$component-attributes.adoc[]
|
|
:uri-pkl-codegen-kotlin-maven-module: {uri-maven-docsite}/artifact/org.pkl-lang/pkl-codegen-kotlin
|
|
:uri-pkl-codegen-kotlin-download: {uri-sonatype-snapshot-download}&a=pkl-cli-codegen-kotlin&e=jar
|
|
|
|
ifdef::is-release-version[]
|
|
:uri-pkl-codegen-kotlin-download: {github-releases}/pkl-codegen-kotlin
|
|
endif::[]
|
|
|
|
The Kotlin source code generator reads Pkl classes and generates corresponding Kotlin classes with equally named properties.
|
|
|
|
Together with xref:java-binding:pkl-config-java.adoc#object-mapping[Object Mapping], code generation provides a complete solution for consuming Pkl configuration as statically typed Kotlin objects.
|
|
Kotlin code never drifts from the configuration structure defined in Pkl, and the entire configuration tree can be code-completed in Kotlin IDEs.
|
|
|
|
== Installation
|
|
|
|
The code generator is offered as Gradle plugin, Java library, and CLI.
|
|
|
|
=== Gradle Plugin
|
|
|
|
See xref:pkl-gradle:index.adoc#installation[Installation] in the Gradle plugin chapter.
|
|
|
|
[[install-library]]
|
|
=== Java Library
|
|
|
|
The `pkl-codegen-kotlin` library is available {uri-pkl-codegen-kotlin-maven-module}[from Maven Central].
|
|
It requires Java 17 or higher and Kotlin 1.3 or higher.
|
|
|
|
==== Gradle
|
|
|
|
To use the library in a Gradle project, declare the following dependency:
|
|
|
|
[tabs]
|
|
====
|
|
Kotlin::
|
|
+
|
|
.build.gradle.kts
|
|
[source,kotlin,subs="+attributes"]
|
|
----
|
|
dependencies {
|
|
implementation("org.pkl-lang:pkl-codegen-kotlin:{pkl-artifact-version}")
|
|
}
|
|
|
|
repositories {
|
|
ifdef::is-release-version[]
|
|
mavenCentral()
|
|
endif::[]
|
|
ifndef::is-release-version[]
|
|
maven(url = "{uri-sonatype}")
|
|
endif::[]
|
|
}
|
|
----
|
|
|
|
Groovy::
|
|
+
|
|
.build.gradle
|
|
[source,groovy,subs="+attributes"]
|
|
----
|
|
dependencies {
|
|
implementation "org.pkl-lang:pkl-codegen-kotlin:{pkl-artifact-version}"
|
|
}
|
|
|
|
repositories {
|
|
ifdef::is-release-version[]
|
|
mavenCentral()
|
|
endif::[]
|
|
ifndef::is-release-version[]
|
|
maven { url "{uri-sonatype}" }
|
|
endif::[]
|
|
}
|
|
----
|
|
====
|
|
|
|
==== Maven
|
|
|
|
To use the library in a Maven project, declare the following dependency:
|
|
|
|
.pom.xml
|
|
[source,xml,subs="+attributes"]
|
|
----
|
|
<dependency>
|
|
<groupId>org.pkl-lang</groupId>
|
|
<artifactId>pkl-codegen-kotlin</artifactId>
|
|
<version>{pkl-artifact-version}</version>
|
|
</dependency>
|
|
----
|
|
|
|
[[install-cli]]
|
|
=== CLI
|
|
|
|
The CLI is available as a Java executable.
|
|
|
|
It works on multiple platforms, and requires a Java 17 (or higher) runtime on the system path.
|
|
|
|
To download:
|
|
|
|
[tabs]
|
|
====
|
|
macOS/Linux::
|
|
+
|
|
[source,shell]
|
|
[subs="+attributes"]
|
|
----
|
|
curl -L -o pkl-codegen-kotlin '{uri-pkl-codegen-kotlin-download}'
|
|
chmod +x pkl-codegen-kotlin
|
|
./pkl-codegen-kotlin --version
|
|
----
|
|
|
|
Windows::
|
|
+
|
|
[source,PowerShell]
|
|
[subs="+attributes"]
|
|
----
|
|
Invoke-WebRequest '{uri-pkl-codegen-kotlin-download}' -OutFile pkl-codegen-kotlin.bat
|
|
.\pkl-codegen-kotlin --version
|
|
----
|
|
====
|
|
|
|
This should print something similar to:
|
|
|
|
[source,shell]
|
|
[subs="+attributes"]
|
|
----
|
|
pkl-codegen-kotlin {pkl-version} (macOS 14.2, Java 17.0.10)
|
|
----
|
|
|
|
[[usage]]
|
|
== Usage
|
|
|
|
The code generator is offered as Gradle plugin, Java library, and CLI.
|
|
|
|
=== Gradle Plugin
|
|
|
|
See xref:pkl-gradle:index.adoc#kotlin-code-gen[Kotlin Code Generation] in the Gradle plugin chapter.
|
|
|
|
=== Java Library
|
|
|
|
The library offers two APIs: a high-level API that corresponds to the CLI, and a lower-level API that provides additional features and control.
|
|
The entry points for these APIs are `org.pkl.codegen.kotlin.CliKotlinCodeGenerator` and `org.pkl.codegen.kotlin.KotlinCodeGenerator`, respectively.
|
|
For more information, refer to the KDoc documentation.
|
|
|
|
=== CLI
|
|
|
|
*Synopsis:* `pkl-codegen-kotlin [<options>] <modules>`
|
|
|
|
`<modules>`::
|
|
The absolute or relative URIs of the modules to generate classes for.
|
|
Relative URIs are resolved against the working directory.
|
|
|
|
==== Options
|
|
|
|
.--generate-kdoc
|
|
[%collapsible]
|
|
====
|
|
Default: (flag not set) +
|
|
Flag that indicates to preserve Pkl doc comments by generating corresponding KDoc comments.
|
|
====
|
|
|
|
Common code generator options:
|
|
|
|
include::../../java-binding/partials/cli-codegen-options.adoc[]
|
|
|
|
Common CLI options:
|
|
|
|
include::../../pkl-cli/partials/cli-common-options.adoc[]
|
|
|
|
[[full-example]]
|
|
== Full Example
|
|
|
|
For a ready-to-go example with full source code,
|
|
see link:{uri-codegen-kotlin-example}[codegen-kotlin] in the _pkl-jvm-examples_ repository.
|