[PR #1026] [MERGED] C library for Pkl #857

New Issue

2025-12-30T01:27:14+01:00

adam commented

2025-12-30 01:27:14 +01:00

📋 Pull Request Information

Original PR: https://github.com/apple/pkl/pull/1026
Author: @KushalP
Created: 3/18/2025
Status: ✅ Merged
Merged: 5/28/2025
Merged by: @bioball

Base: c-library ← Head: c-library-for-pkl

📝 Commits (10+)

84f9cfb C library for Pkl
dc85b52 Rename to LibPklLibrary
6876907 Remove lib prefix from .h and .c files
5a9e685 Add doxygen-style comments to pkl.h file
e44e441 Move pointer next to variable name
f0c4176 Add TODO comment to clean this up once on a feature-branch
b09abff Add @SuppressWarnings("unused") annotation to LibPkl class
6102e45 Move LibPkl constructor between fields and methods
1996964 Add package-info.java for org.pkl.libpkl package
30c1a46 Propagate param handlerContext so users can trace messages

📊 Changes

17 files changed (+1919 additions, -3 deletions)

View changed files

📝 buildSrc/src/main/kotlin/NativeImageBuild.kt (+5 -1)
📝 gradle/libs.versions.toml (+1 -0)
➕ libpkl/gradle.lockfile (+81 -0)
➕ libpkl/libpkl.gradle.kts (+316 -0)
➕ libpkl/src/main/c/pkl.c (+86 -0)
➕ libpkl/src/main/c/pkl.h (+52 -0)
➕ libpkl/src/main/java/org/pkl/libpkl/LibPkl.java (+96 -0)
➕ libpkl/src/main/java/org/pkl/libpkl/LibPklLogger.java (+29 -0)
➕ libpkl/src/main/java/org/pkl/libpkl/NativeInputStream.java (+46 -0)
➕ libpkl/src/main/java/org/pkl/libpkl/NativeTransport.java (+70 -0)
➕ libpkl/src/main/java/org/pkl/libpkl/package-info.java (+4 -0)
➕ libpkl/src/test/kotlin/org/pkl/libpkl/JNATestClient.kt (+112 -0)
➕ libpkl/src/test/kotlin/org/pkl/libpkl/LibPklLibrary.kt (+37 -0)
➕ libpkl/src/test/kotlin/org/pkl/libpkl/MessagePackDebugRenderer.kt (+107 -0)
➕ libpkl/src/test/kotlin/org/pkl/libpkl/NativeTest.kt (+873 -0)
📝 pkl-core/src/main/java/org/pkl/core/messaging/MessageTransports.java (+2 -2)
📝 settings.gradle.kts (+2 -0)

📄 Description

This introduces native C bindings for Pkl.

Dynamic Library

Using org.graalvm.nativeimage and the native-image binary we
produce a dynamic library (for each OS/Arch variant) that provides a
way to initialise itself with a graal_isolatethread_t.

Methods are annotated with @CEntryPoint and exported.

This change results in an architecture and OS-specific directory being
created which now produces the headers for our shared library
functions:

❯ ll libpkl/build/libs/macos-aarch64/

graal_isolate_dynamic.h
graal_isolate.h
libpkl_internal_dynamic.h
libpkl_internal.dylib
libpkl_internal.h

`libpkl`

The produced libpkl dynamic library wraps the GraalVM C interface
into something that is future-friendly for the needs of a Pkl
integrator. It exports an interface which aligns with SPICE-0015[1].

❯ ll libpkl/build/libs/macos-aarch64/

graal_isolate_dynamic.h
graal_isolate.h
libpkl_internal_dynamic.h
libpkl_internal.dylib
libpkl_internal.h
libpkl.dylib    <--- this is new
pkl.h           <--- this is new

JNA

Testing of the produced libpkl dynamic library is done using Java
Native Access[2] for ease. We provide an interface in Kotlin which
JNA transposes against the libpkl dynamic library discoverable at
the path that is discoverable with jna.library.path.

Load in `projects.pklCommonsCli` to deal with `UnsupportedFeatureException`

This is to deal with the following error:

Caused by: com.oracle.graal.pointsto.constraints.UnsupportedFeatureException: Detected a started Thread in the image heap. Thread name: main. Threads running in the image generator are no longer running at image runtime. If these objects should not be stored in the image heap, you can use

    '--trace-object-instantiation=java.lang.Thread'

[1] https://github.com/apple/pkl-evolution/pull/16

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/apple/pkl/pull/1026 **Author:** [@KushalP](https://github.com/KushalP) **Created:** 3/18/2025 **Status:** ✅ Merged **Merged:** 5/28/2025 **Merged by:** [@bioball](https://github.com/bioball) **Base:** `c-library` ← **Head:** `c-library-for-pkl` --- ### 📝 Commits (10+) - [`84f9cfb`](https://github.com/apple/pkl/commit/84f9cfb5a71ce296e3653002885a7aa521613cde) C library for Pkl - [`dc85b52`](https://github.com/apple/pkl/commit/dc85b5200c3fdda1151f4d42f8bcf58b5b90917d) Rename to `LibPklLibrary` - [`6876907`](https://github.com/apple/pkl/commit/687690797355fbe03aa1f6fe6e2dd25fb23d25db) Remove `lib` prefix from `.h` and `.c` files - [`5a9e685`](https://github.com/apple/pkl/commit/5a9e685cb9274640606b804c3cd95440f7c092a1) Add doxygen-style comments to `pkl.h` file - [`e44e441`](https://github.com/apple/pkl/commit/e44e441d0e5d70bb1b5a6d7c92d9c4b7b9b67173) Move pointer next to variable name - [`f0c4176`](https://github.com/apple/pkl/commit/f0c4176de1e941fd67df522399bb721bff5dee36) Add TODO comment to clean this up once on a feature-branch - [`b09abff`](https://github.com/apple/pkl/commit/b09abff543f0f92b1a52088f588fc430982caabf) Add `@SuppressWarnings("unused")` annotation to `LibPkl` class - [`6102e45`](https://github.com/apple/pkl/commit/6102e4582614a9d510d9e215ece1423ca93196b5) Move `LibPkl` constructor between fields and methods - [`1996964`](https://github.com/apple/pkl/commit/19969648fbaffddf35a5035b8b34ca98440494bc) Add `package-info.java` for `org.pkl.libpkl` package - [`30c1a46`](https://github.com/apple/pkl/commit/30c1a4639ea30bc9c728579f84e90435e7423121) Propagate param `handlerContext` so users can trace messages ### 📊 Changes **17 files changed** (+1919 additions, -3 deletions) <details> <summary>View changed files</summary> 📝 `buildSrc/src/main/kotlin/NativeImageBuild.kt` (+5 -1) 📝 `gradle/libs.versions.toml` (+1 -0) ➕ `libpkl/gradle.lockfile` (+81 -0) ➕ `libpkl/libpkl.gradle.kts` (+316 -0) ➕ `libpkl/src/main/c/pkl.c` (+86 -0) ➕ `libpkl/src/main/c/pkl.h` (+52 -0) ➕ `libpkl/src/main/java/org/pkl/libpkl/LibPkl.java` (+96 -0) ➕ `libpkl/src/main/java/org/pkl/libpkl/LibPklLogger.java` (+29 -0) ➕ `libpkl/src/main/java/org/pkl/libpkl/NativeInputStream.java` (+46 -0) ➕ `libpkl/src/main/java/org/pkl/libpkl/NativeTransport.java` (+70 -0) ➕ `libpkl/src/main/java/org/pkl/libpkl/package-info.java` (+4 -0) ➕ `libpkl/src/test/kotlin/org/pkl/libpkl/JNATestClient.kt` (+112 -0) ➕ `libpkl/src/test/kotlin/org/pkl/libpkl/LibPklLibrary.kt` (+37 -0) ➕ `libpkl/src/test/kotlin/org/pkl/libpkl/MessagePackDebugRenderer.kt` (+107 -0) ➕ `libpkl/src/test/kotlin/org/pkl/libpkl/NativeTest.kt` (+873 -0) 📝 `pkl-core/src/main/java/org/pkl/core/messaging/MessageTransports.java` (+2 -2) 📝 `settings.gradle.kts` (+2 -0) </details> ### 📄 Description This introduces native C bindings for Pkl. Dynamic Library --------------- Using `org.graalvm.nativeimage` and the `native-image` binary we produce a dynamic library (for each OS/Arch variant) that provides a way to initialise itself with a `graal_isolatethread_t`. Methods are annotated with `@CEntryPoint` and exported. This change results in an architecture and OS-specific directory being created which now produces the headers for our shared library functions: ``` ❯ ll libpkl/build/libs/macos-aarch64/ graal_isolate_dynamic.h graal_isolate.h libpkl_internal_dynamic.h libpkl_internal.dylib libpkl_internal.h ``` `libpkl` -------- The produced `libpkl` dynamic library wraps the GraalVM C interface into something that is future-friendly for the needs of a Pkl integrator. It exports an interface which aligns with SPICE-0015[1]. ``` ❯ ll libpkl/build/libs/macos-aarch64/ graal_isolate_dynamic.h graal_isolate.h libpkl_internal_dynamic.h libpkl_internal.dylib libpkl_internal.h libpkl.dylib <--- this is new pkl.h <--- this is new ``` JNA --- Testing of the produced `libpkl` dynamic library is done using Java Native Access[2] for ease. We provide an `interface` in Kotlin which JNA transposes against the `libpkl` dynamic library discoverable at the path that is discoverable with `jna.library.path`. Load in `projects.pklCommonsCli` to deal with `UnsupportedFeatureException` --------------------------------------------------------------------------- This is to deal with the following error: ``` Caused by: com.oracle.graal.pointsto.constraints.UnsupportedFeatureException: Detected a started Thread in the image heap. Thread name: main. Threads running in the image generator are no longer running at image runtime. If these objects should not be stored in the image heap, you can use '--trace-object-instantiation=java.lang.Thread' ``` [1] https://github.com/apple/pkl-evolution/pull/16 --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

adam added the pull-request label 2025-12-30 01:27:14 +01:00

adam closed this issue

2025-12-30 01:27:14 +01:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/pkl#857

[PR #1026] [MERGED] C library for Pkl #857