[PR #1134] [CLOSED] C library for Pkl #906

New Issue

adam · 2025-12-30T01:27:41+01:00

adam commented

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

📋 Pull Request Information

Original PR: https://github.com/apple/pkl/pull/1134
Author: @KushalP
Created: 7/22/2025
Status: ❌ Closed

Base: main ← Head: c-library

📝 Commits (1)

bdd3f01 C library for Pkl

📊 Changes

33 files changed (+2123 additions, -301 deletions)

View changed files

📝 .circleci/config.pkl (+5 -2)
📝 .circleci/config.yml (+878 -60)
📝 .circleci/jobs/BuildNativeJob.pkl (+13 -1)
📝 buildSrc/src/main/kotlin/BuildInfo.kt (+26 -16)
📝 buildSrc/src/main/kotlin/NativeImageBuild.kt (+61 -17)
➕ buildSrc/src/main/kotlin/Target.kt (+82 -0)
📝 buildSrc/src/main/kotlin/pklNativeExecutable.gradle.kts (+67 -136)
📝 buildSrc/src/main/kotlin/pklNativeLifecycle.gradle.kts (+19 -50)
📝 gradle/libs.versions.toml (+4 -0)
➕ libpkl/gradle.lockfile (+73 -0)
➕ libpkl/libpkl.gradle.kts (+258 -0)
➕ libpkl/src/main/c/pkl.c (+120 -0)
➕ libpkl/src/main/c/pkl.h (+59 -0)
➕ libpkl/src/main/java/org/pkl/libpkl/LibPkl.java (+93 -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/nativeTest/kotlin/org/pkl/libpkl/LibPklJNA.kt (+40 -0)
➕ libpkl/src/nativeTest/kotlin/org/pkl/libpkl/LibPklMessageTransport.kt (+59 -0)

...and 13 more files

📄 Description

This PR introduces native C bindings for Pkl. See: https://github.com/apple/pkl/issues/993

Dynamic Library

Using org.graalvm.nativeimage and the native-image binary we produce a dynamic -shared 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:

❯ ls libpkl/build/native-libs/macos-aarch64/
graal_isolate_dynamic.h
graal_isolate.h
libpkl_internal_dynamic.h
libpkl_internal.dylib
libpkl_internal.h
libpkl.dylib                  <---- this is the interface we're exposing
libpkl.dylib.dSYM.            <---- debug symbols for the interface we're exposing
pkl.h                         <---- this is the interface we're exposing

Gradle Tasks

NativeImageBuild has been extended to allow creating a shared library. Alongside this, a :libpkl:nativeTest task has been creating which uses JNA to drive the dynamic library from Java.

JNA

Testing of the produced libpkl dynamic library is done using Java Native Access 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.

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

Note the last three items called out in the Dynamic Library section.

Outstanding tasks

There's work remaining before this can be merged.

Get review feedback from GraalVM maintainers on the implementation, specifically the graal_attach_thread behaviour
Provide the -library_name flag to native-image to not require a fully-qualified path for library inclusion
The implementation is inherently single-threaded, how can we allow this to be safe to use across multiple threads?
Allow configuring a release build
Merge libpkl_internal.dylib and libpkl.dylib into a single artefact that is easier for users to consume as libpkl.dylib
Remove architecture-specific builds that have been added for testing

_{🔄 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/1134 **Author:** [@KushalP](https://github.com/KushalP) **Created:** 7/22/2025 **Status:** ❌ Closed **Base:** `main` ← **Head:** `c-library` --- ### 📝 Commits (1) - [`bdd3f01`](https://github.com/apple/pkl/commit/bdd3f01b25edfc7e50c7a65006b71b35d7c993e3) C library for Pkl ### 📊 Changes **33 files changed** (+2123 additions, -301 deletions) <details> <summary>View changed files</summary> 📝 `.circleci/config.pkl` (+5 -2) 📝 `.circleci/config.yml` (+878 -60) 📝 `.circleci/jobs/BuildNativeJob.pkl` (+13 -1) 📝 `buildSrc/src/main/kotlin/BuildInfo.kt` (+26 -16) 📝 `buildSrc/src/main/kotlin/NativeImageBuild.kt` (+61 -17) ➕ `buildSrc/src/main/kotlin/Target.kt` (+82 -0) 📝 `buildSrc/src/main/kotlin/pklNativeExecutable.gradle.kts` (+67 -136) 📝 `buildSrc/src/main/kotlin/pklNativeLifecycle.gradle.kts` (+19 -50) 📝 `gradle/libs.versions.toml` (+4 -0) ➕ `libpkl/gradle.lockfile` (+73 -0) ➕ `libpkl/libpkl.gradle.kts` (+258 -0) ➕ `libpkl/src/main/c/pkl.c` (+120 -0) ➕ `libpkl/src/main/c/pkl.h` (+59 -0) ➕ `libpkl/src/main/java/org/pkl/libpkl/LibPkl.java` (+93 -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/nativeTest/kotlin/org/pkl/libpkl/LibPklJNA.kt` (+40 -0) ➕ `libpkl/src/nativeTest/kotlin/org/pkl/libpkl/LibPklMessageTransport.kt` (+59 -0) _...and 13 more files_ </details> ### 📄 Description This PR introduces native C bindings for Pkl. See: https://github.com/apple/pkl/issues/993 ## Dynamic Library Using `org.graalvm.nativeimage` and the `native-image` binary we produce a dynamic `-shared` 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: ``` ❯ ls libpkl/build/native-libs/macos-aarch64/ graal_isolate_dynamic.h graal_isolate.h libpkl_internal_dynamic.h libpkl_internal.dylib libpkl_internal.h libpkl.dylib <---- this is the interface we're exposing libpkl.dylib.dSYM. <---- debug symbols for the interface we're exposing pkl.h <---- this is the interface we're exposing ``` ## Gradle Tasks `NativeImageBuild` has been extended to allow creating a shared library. Alongside this, a `:libpkl:nativeTest` task has been creating which uses JNA to drive the dynamic library from Java. ### JNA Testing of the produced `libpkl` dynamic library is done using [Java Native Access](https://github.com/java-native-access/jna) 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`. ## `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](https://github.com/apple/pkl-evolution/pull/16). Note the last three items called out in the **Dynamic Library** section. ## Outstanding tasks There's work remaining before this can be merged. - [ ] Get review feedback from GraalVM maintainers on the implementation, specifically the `graal_attach_thread` behaviour - [ ] Provide the `-library_name` flag to `native-image` to not require a fully-qualified path for library inclusion - [ ] The implementation is inherently single-threaded, how can we allow this to be safe to use across multiple threads? - [ ] Allow configuring a _release_ build - [ ] Merge `libpkl_internal.dylib` and `libpkl.dylib` into a single artefact that is easier for users to consume as `libpkl.dylib` - [ ] Remove architecture-specific builds that have been added for testing --- <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:41 +01:00

adam closed this issue

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

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/pkl#906