= 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.