mirror of
https://github.com/apple/pkl.git
synced 2026-01-11 22:30:54 +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
124 lines
4.0 KiB
Plaintext
124 lines
4.0 KiB
Plaintext
= pkl-config-kotlin Library
|
|
include::ROOT:partial$component-attributes.adoc[]
|
|
:uri-pkl-config-kotlin-maven-module: {uri-maven-docsite}/artifact/org.pkl-lang/pkl-config-kotlin
|
|
:uri-pkl-config-kotlin-main-sources: {uri-github-tree}/pkl-config-kotlin/src/main/kotlin/org/pkl/config/kotlin
|
|
:uri-pkl-config-kotlin-test-sources: {uri-github-tree}/pkl-config-kotlin/src/test/kotlin/org/pkl/config/kotlin
|
|
:uri-pkl-config-kotlin-ConverterFactories: {uri-pkl-config-kotlin-main-sources}/ConverterFactories.kt
|
|
:uri-pkl-config-kotlin-ConfigExtensions: {uri-pkl-config-kotlin-main-sources}/ConfigExtensions.kt
|
|
|
|
The _pkl-config-kotlin_ library extends xref:java-binding:pkl-config-java.adoc[pkl-config-java] with Kotlin specific extension methods and object converters.
|
|
We recommend that Kotlin projects depend on this library instead of _pkl-config-java_.
|
|
|
|
== Installation
|
|
|
|
The _pkl-config-kotlin_ library is available {uri-pkl-config-kotlin-maven-module}[from Maven Central].
|
|
It requires Java 17 or higher and Kotlin 1.5 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-config-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-config-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"]
|
|
----
|
|
<project>
|
|
<dependency>
|
|
<groupId>org.pkl-lang</groupId>
|
|
<artifactId>pkl-config-kotlin</artifactId>
|
|
<version>{pkl-artifact-version}</version>
|
|
</dependency>
|
|
ifndef::is-release-version[]
|
|
<repositories>
|
|
<repository>
|
|
<id>sonatype-s01</id>
|
|
<name>Sonatype S01</name>
|
|
<url>{uri-sonatype}</url>
|
|
</repository>
|
|
</repositories>
|
|
endif::[]
|
|
</project>
|
|
----
|
|
|
|
== Usage
|
|
|
|
Below is the Kotlin version of the Java xref:java-binding:pkl-config-java.adoc#config-evaluator-java-example[ConfigEvaluator] example.
|
|
Differences to the Java version are called out.
|
|
|
|
[source,kotlin,indent=0]
|
|
----
|
|
include::{examplesdir}/KotlinConfigExample.kt[tags=usage]
|
|
----
|
|
<1> Use the `forKotlin()` method to preconfigure the builder with Kotlin specific conversions.
|
|
In particular, `forKotlin()` eliminates the need to annotate constructor parameters of Kotlin classes and Kotlin data classes with `@Named`.
|
|
<2> The evaluator should be closed once it is no longer needed.
|
|
Here this is done with a Kotlin `use {}` expression.
|
|
Any data returned by the evaluator before calling `close()` remains valid.
|
|
<3> Navigate to the `"pigeon"` child.
|
|
The subscript notation is shorthand for `config.get("pigeon")`.
|
|
<4> Convert `"age"` to `Int` with the `Config.to()` extension method.
|
|
The target type is provided as a type argument.
|
|
Always use `Config.to()` instead of `Config.as()` in Kotlin.
|
|
<5> `Config.to()` makes conversions to parameterized types straightforward:
|
|
`to<List<String>>()` instead of `as(JavaType.listOf(String::class.java))`.
|
|
|
|
For properties that are allowed to be `null`, convert to a nullable type:
|
|
|
|
[source,kotlin,indent=0]
|
|
----
|
|
include::{examplesdir}/KotlinConfigExample.kt[tags=nullable]
|
|
----
|
|
<1> To indicate that `null` is an allowed value, convert to the nullable type `String?`.
|
|
Converting to `String` would result in a `ConversionException`.
|
|
|
|
For a ready-to-go example with full source code,
|
|
see link:{uri-config-kotlin-example}[config-kotlin] in the _pkl-jvm-examples_ repository.
|
|
|
|
== Further Information
|
|
|
|
Refer to the Javadoc and sources published with the library, or browse the library's {uri-pkl-config-kotlin-main-sources}[main] and {uri-pkl-config-kotlin-test-sources}[test] sources.
|