mirror of
https://github.com/apple/pkl.git
synced 2026-01-18 17:37:07 +01:00
b5208a2b5b
* Swap Kotlin/Groovy tab order in documentation * Use Kotlin DSL repository extension function
137 lines
3.7 KiB
Plaintext
137 lines
3.7 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
|
|
|
|
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 bundled with the library.
|
|
As we do not currently ship the CLI as a self-contained Jar, we recommend to provision it with a Maven compatible build tool as shown in <<install-library>>.
|
|
|
|
[[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
|
|
|
|
As mentioned in <<install-cli,Installation>>, the CLI is bundled with the library.
|
|
To run the CLI, execute the library Jar or its `org.pkl.codegen.kotlin.Main` main class.
|
|
|
|
*Synopsis:* `java -cp <classpath> -jar pkl-codegen-kotlin.jar [<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 generate Kdoc based on doc comments for Pkl modules, classes, and properties.
|
|
====
|
|
|
|
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/pkl-examples_ repository.
|