mirror of
https://github.com/apple/pkl.git
synced 2026-03-27 11:31:11 +01:00
Publish executables for pkldoc, pkl-codegen-java, pkl-codegen-kotlin (#1023)
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
This commit is contained in:
Daniel Chao
@@ -145,3 +145,5 @@ endif::[]
|
||||
:uri-messagepack-spec: https://github.com/msgpack/msgpack/blob/master/spec.md
|
||||
|
||||
:uri-pkl-roadmap: https://github.com/orgs/apple/projects/12/views/1
|
||||
|
||||
:uri-sonatype-snapshot-download: https://s01.oss.sonatype.org/service/local/artifact/maven/redirect?r=snapshots&g=org.pkl-lang&v={pkl-artifact-version}
|
||||
|
||||
@@ -5,7 +5,7 @@ import org.pkl.core.ModuleSource;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
@SuppressWarnings("unused")
|
||||
// the pkl/pkl-examples repo has a similar example
|
||||
// the pkl-jvm-examples repo has a similar example
|
||||
public class JavaConfigExample {
|
||||
@Test
|
||||
public void usage() {
|
||||
|
||||
@@ -2,6 +2,12 @@
|
||||
include::ROOT:partial$component-attributes.adoc[]
|
||||
:uri-pkl-codegen-java-maven-module: {uri-maven-docsite}/artifact/org.pkl-lang/pkl-codegen-java
|
||||
|
||||
:uri-pkl-codegen-java-download: {uri-sonatype-snapshot-download}&a=pkl-cli-codegen-java&e=jar
|
||||
|
||||
ifdef::is-release-version[]
|
||||
:uri-pkl-cli-codegen-java-download: {github-releases}/pkl-codegen-java
|
||||
endif::[]
|
||||
|
||||
The Java source code generator takes Pkl class definitions as an input, and generates corresponding Java classes with equally named properties.
|
||||
|
||||
The benefits of code generation are:
|
||||
@@ -103,8 +109,41 @@ endif::[]
|
||||
[[install-cli]]
|
||||
=== CLI
|
||||
|
||||
The CLI is bundled with the Java 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>>.
|
||||
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-java '{uri-pkl-codegen-java-download}'
|
||||
chmod +x pkl-codegen-java
|
||||
./pkl-codegen-java --version
|
||||
----
|
||||
|
||||
Windows::
|
||||
+
|
||||
[source,PowerShell]
|
||||
[subs="+attributes"]
|
||||
----
|
||||
Invoke-WebRequest '{uri-pkl-codegen-java-download}' -OutFile pkl-codegen-java.bat
|
||||
.\pkl-codegen-java --version
|
||||
----
|
||||
====
|
||||
|
||||
This should print something similar to:
|
||||
|
||||
[source,shell]
|
||||
[subs="+attributes"]
|
||||
----
|
||||
pkl-codegen-java {pkl-version} (macOS 14.2, Java 17.0.10)
|
||||
----
|
||||
|
||||
[[codegen-java-usage]]
|
||||
== Usage
|
||||
@@ -123,10 +162,7 @@ For more information, refer to the Javadoc documentation.
|
||||
|
||||
=== CLI
|
||||
|
||||
As explained in <<install-cli,Installation>>, the CLI is bundled with the Java library.
|
||||
To run the CLI, execute the library Jar or its `org.pkl.codegen.java.Main` main class.
|
||||
|
||||
*Synopsis:* `java -cp <classpath> -jar pkl-codegen-java.jar [<options>] <modules>`
|
||||
*Synopsis:* `pkl-codegen-java [<options>] <modules>`
|
||||
|
||||
`<modules>`::
|
||||
The absolute or relative URIs of the modules to generate classes for.
|
||||
@@ -180,4 +216,4 @@ include::../../pkl-cli/partials/cli-common-options.adoc[]
|
||||
== Full Example
|
||||
|
||||
For a ready-to-go example with full source code,
|
||||
see link:{uri-codegen-java-example}[codegen-java] in the _pkl/pkl-examples_ repository.
|
||||
see link:{uri-codegen-java-example}[codegen-java] in the _pkl-jvm-examples_ repository.
|
||||
|
||||
@@ -6,7 +6,7 @@ import org.pkl.config.kotlin.to
|
||||
import org.pkl.core.ModuleSource
|
||||
import org.junit.jupiter.api.Test
|
||||
|
||||
// the pkl/pkl-examples repo has a similar example
|
||||
// the pkl-jvm-examples repo has a similar example
|
||||
class KotlinConfigExample {
|
||||
@Test
|
||||
fun usage() {
|
||||
|
||||
@@ -1,6 +1,11 @@
|
||||
= 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.
|
||||
|
||||
@@ -83,8 +88,41 @@ To use the library in a Maven project, declare the following 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>>.
|
||||
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
|
||||
@@ -103,10 +141,7 @@ 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>`
|
||||
*Synopsis:* `pkl-codegen-kotlin [<options>] <modules>`
|
||||
|
||||
`<modules>`::
|
||||
The absolute or relative URIs of the modules to generate classes for.
|
||||
@@ -133,4 +168,4 @@ include::../../pkl-cli/partials/cli-common-options.adoc[]
|
||||
== 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.
|
||||
see link:{uri-codegen-kotlin-example}[codegen-kotlin] in the _pkl-jvm-examples_ repository.
|
||||
|
||||
@@ -116,7 +116,7 @@ include::{examplesdir}/KotlinConfigExample.kt[tags=nullable]
|
||||
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/pkl-examples_ repository.
|
||||
see link:{uri-config-kotlin-example}[config-kotlin] in the _pkl-jvm-examples_ repository.
|
||||
|
||||
== Further Information
|
||||
|
||||
|
||||
@@ -3,7 +3,6 @@ include::ROOT:partial$component-attributes.adoc[]
|
||||
:uri-homebrew: https://brew.sh
|
||||
:uri-mise: https://mise.jdx.dev
|
||||
|
||||
:uri-sonatype-snapshot-download: https://s01.oss.sonatype.org/service/local/artifact/maven/redirect?r=snapshots&g=org.pkl-lang&v={pkl-artifact-version}
|
||||
:uri-pkl-macos-amd64-download: {uri-sonatype-snapshot-download}&a=pkl-cli-macos-amd64&e=bin
|
||||
:uri-pkl-macos-aarch64-download: {uri-sonatype-snapshot-download}&a=pkl-cli-macos-aarch64&e=bin
|
||||
:uri-pkl-linux-amd64-download: {uri-sonatype-snapshot-download}&a=pkl-cli-linux-amd64&e=bin
|
||||
|
||||
@@ -6,7 +6,7 @@ import org.pkl.core.PModule;
|
||||
import org.pkl.core.PObject;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
// the pkl/pkl-examples repo has a similar example
|
||||
// the pkl-jvm-examples repo has a similar example
|
||||
@SuppressWarnings({"unchecked", "unused", "ConstantConditions"})
|
||||
public class CoreEvaluatorExample {
|
||||
@Test
|
||||
|
||||
@@ -5,6 +5,23 @@ include::ROOT:partial$component-attributes.adoc[]
|
||||
:uri-DocPackageInfo: {uri-pkl-stdlib-docs}/DocPackageInfo/
|
||||
:uri-CliDocGenerator: {uri-pkl-doc-main-sources}/CliDocGenerator.kt
|
||||
:uri-DocGenerator: {uri-pkl-doc-main-sources}/DocGenerator.kt
|
||||
:uri-pkldoc-macos-amd64-download: {uri-sonatype-snapshot-download}&a=pkldoc-macos-amd64&e=bin
|
||||
:uri-pkldoc-macos-aarch64-download: {uri-sonatype-snapshot-download}&a=pkldoc-macos-aarch64&e=bin
|
||||
:uri-pkldoc-linux-amd64-download: {uri-sonatype-snapshot-download}&a=pkldoc-linux-amd64&e=bin
|
||||
:uri-pkldoc-linux-aarch64-download: {uri-sonatype-snapshot-download}&a=pkldoc-linux-aarch64&e=bin
|
||||
:uri-pkldoc-alpine-download: {uri-sonatype-snapshot-download}&a=pkldoc-alpine-linux-amd64&e=bin
|
||||
:uri-pkldoc-windows-download: {uri-sonatype-snapshot-download}&a=pkldoc-windows-amd64&e=exe
|
||||
:uri-pkldoc-java-download: {uri-sonatype-snapshot-download}&a=pkldoc-java&e=jar
|
||||
|
||||
ifdef::is-release-version[]
|
||||
:uri-pkldoc-macos-amd64-download: {github-releases}/pkldoc-macos-amd64
|
||||
:uri-pkldoc-macos-aarch64-download: {github-releases}/pkldoc-macos-aarch64
|
||||
:uri-pkldoc-linux-amd64-download: {github-releases}/pkldoc-linux-amd64
|
||||
:uri-pkldoc-linux-aarch64-download: {github-releases}/pkldoc-linux-aarch64
|
||||
:uri-pkldoc-alpine-download: {github-releases}/pkldoc-alpine-linux-amd64
|
||||
:uri-pkldoc-windows-download: {github-releases}/pkldoc-windows-amd64.exe
|
||||
:uri-pkldoc-java-download: {github-releases}/jpkldoc
|
||||
endif::[]
|
||||
|
||||
_Pkldoc_ is a documentation website generator that produces navigable and searchable API documentation for Pkl modules.
|
||||
|
||||
@@ -153,8 +170,33 @@ endif::[]
|
||||
[[install-cli]]
|
||||
=== CLI
|
||||
|
||||
The CLI is bundled with the library and does not currently ship as a native executable or a self-contained Jar.
|
||||
We recommend to provision it with a Maven compatible build tool as shown in <<install-library,Library Installation>>.
|
||||
The CLI comes in multiple flavors:
|
||||
|
||||
* Native macOS executable for amd64 (tested on macOS 10.15)
|
||||
* Native Linux executable for amd64
|
||||
* Native Linux executable for aarch64
|
||||
* Native Alpine Linux executable for amd64 (cross-compiled and tested on Oracle Linux 8)
|
||||
* Native Windows executable for amd64 (tested on Windows Server 2022)
|
||||
* Java executable (tested with Java 17/21 on macOS and Oracle Linux)
|
||||
|
||||
.What is the Difference Between the Linux and Alpine Linux Executables?
|
||||
[NOTE]
|
||||
====
|
||||
The Linux executable is dynamically linked against _glibc_ and _libstdc{plus}{plus}_,
|
||||
whereas, the Alpine Linux executable is statically linked against _musl libc_ and _libstdc{plus}{plus}_.
|
||||
====
|
||||
|
||||
The Java executable works on multiple platforms and has a smaller binary size than the native executables.
|
||||
However, it requires a Java 17 (or higher) runtime on the system path, and has a noticeable startup delay.
|
||||
|
||||
Download links:
|
||||
|
||||
* macOS aarch64: {uri-pkldoc-macos-aarch64-download}
|
||||
* macOS amd64: {uri-pkldoc-macos-amd64-download}
|
||||
* Linux aarch64: {uri-pkldoc-linux-aarch64-download}
|
||||
* Linux amd64: {uri-pkldoc-linux-amd64-download}
|
||||
* Alpine Linux amd64: {uri-pkldoc-alpine-download}
|
||||
* Windows amd64: {uri-pkldoc-windows-download}
|
||||
|
||||
[[usage]]
|
||||
== Usage
|
||||
@@ -216,10 +258,7 @@ For more information, refer to the Javadoc documentation.
|
||||
|
||||
=== CLI
|
||||
|
||||
As mentioned in <<install-cli,CLI Installation>>, the CLI is bundled with the library.
|
||||
To run the CLI, execute the library Jar or its `org.pkl.doc.Main` class.
|
||||
|
||||
*Synopsis:* `java -cp <classpath> -jar pkl-doc.jar [<options>] <modules>`
|
||||
*Synopsis:* `pkldoc [<options>] <modules>`
|
||||
|
||||
`<modules>`::
|
||||
The absolute or relative URIs of docsite descriptors, package descriptors, and the modules for which to generate documentation.
|
||||
@@ -252,4 +291,4 @@ include::../../pkl-cli/partials/cli-common-options.adoc[]
|
||||
== Full Example
|
||||
|
||||
For a ready-to-go example with full source code and detailed walkthrough,
|
||||
see link:{uri-pkldoc-example}[pkldoc] in the _pkl/pkl-examples_ repository.
|
||||
see link:{uri-pkldoc-example}[pkldoc] in the _pkl-jvm-examples_ repository.
|
||||
|
||||
@@ -134,7 +134,7 @@ $ ./gradlew evalPkl
|
||||
----
|
||||
|
||||
For a ready-to-go example with full source code,
|
||||
see link:{uri-build-eval-example}[codegen-java] in the _pkl/pkl-examples_ repository.
|
||||
see link:{uri-build-eval-example}[codegen-java] in the _pkl-jvm-examples_ repository.
|
||||
|
||||
=== Configuration Options
|
||||
|
||||
@@ -361,7 +361,7 @@ $ ./gradlew genJava
|
||||
----
|
||||
|
||||
For a ready-to-go example with full source code,
|
||||
see link:{uri-codegen-java-example}[codegen-java] in the _pkl/pkl-examples_ repository.
|
||||
see link:{uri-codegen-java-example}[codegen-java] in the _pkl-jvm-examples_ repository.
|
||||
|
||||
=== Configuration Options
|
||||
|
||||
@@ -451,7 +451,7 @@ $ ./gradlew genKotlin
|
||||
----
|
||||
|
||||
For a ready-to-go example with full source code,
|
||||
see link:{uri-codegen-kotlin-example}[codegen-kotlin] in the _pkl/pkl-examples_ repository.
|
||||
see link:{uri-codegen-kotlin-example}[codegen-kotlin] in the _pkl-jvm-examples_ repository.
|
||||
|
||||
=== Configuration Options
|
||||
|
||||
@@ -520,7 +520,7 @@ $ ./gradlew pkldoc
|
||||
----
|
||||
|
||||
For a ready-to-go example with full source code,
|
||||
see link:{uri-pkldoc-example}[pkldoc] in the _pkl/pkl-examples_ repository.
|
||||
see link:{uri-pkldoc-example}[pkldoc] in the _pkl-jvm-examples_ repository.
|
||||
|
||||
=== Configuration Options
|
||||
|
||||
|
||||
Reference in New Issue
Block a user