mirror of
https://github.com/apple/pkl.git
synced 2026-07-09 14:42:50 +02:00
Daniel Chao
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-snapshot-repo}")
|
|
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-snapshot-repo}" }
|
|
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.
|