starred/pkl
1
0
Fork 0
mirror of https://github.com/apple/pkl.git synced 2026-01-11 14:20:35 +01:00
Code Issues 198 Packages Projects Releases 10 Wiki Activity

[PR #1136] [CLOSED] C library for Pkl #908

New Issue
Closed
opened 2025-12-30 01:27:41 +01:00 by adam · 0 comments
adam commented 2025-12-30 01:27:41 +01:00
Owner
Copy Link

📋 Pull Request Information

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

Base: main ← Head: c-library

📝 Commits (2)

  • bbe00d7 C library for Pkl
  • bbb5a3d Document how message is de/serialized

📊 Changes

35 files changed (+2202 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 (+141 -0)
➕ libpkl/src/main/c/pkl.h (+85 -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 (+62 -0)

...and 15 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
  • Use graal_attach_thread (and related C methods) before each pkl_send_message, pkl_version, and pkl_close
  • Provide the -library_name flag to native-image to not require a fully-qualified path for library inclusion
  • Allow multiple instances, instead of using a single global instance
  • 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
  • Document how to use the Message Passing API for sending/receiving messages
  • Make pkl_version() much simpler, and get it to return a hard-coded string value that is automatically string replaced with the version on build

🔄 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/1136 **Author:** [@KushalP](https://github.com/KushalP) **Created:** 7/22/2025 **Status:** ❌ Closed **Base:** `main` ← **Head:** `c-library` --- ### 📝 Commits (2) - [`bbe00d7`](https://github.com/apple/pkl/commit/bbe00d7c5a0b20abf31ca51a109216723266ea3e) C library for Pkl - [`bbb5a3d`](https://github.com/apple/pkl/commit/bbb5a3d9232d8c2c204f3e8a993f0f9f3f443a61) Document how `message` is de/serialized ### 📊 Changes **35 files changed** (+2202 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` (+141 -0) ➕ `libpkl/src/main/c/pkl.h` (+85 -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` (+62 -0) _...and 15 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. - [x] Get [review feedback](https://graalvm.slack.com/archives/CN9KSFB40/p1753198358665599) from GraalVM maintainers on the implementation, specifically the `graal_attach_thread` behaviour - [ ] Use `graal_attach_thread` (and related C methods) before each `pkl_send_message`, `pkl_version`, and `pkl_close` - [ ] Provide the `-library_name` flag to `native-image` to not require a fully-qualified path for library inclusion - [x] Allow multiple instances, instead of using a single global instance - [ ] 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 - [x] Document how to use the Message Passing API for sending/receiving messages - [ ] Make `pkl_version()` much simpler, and get it to return a hard-coded string value that is automatically string replaced with the version on build --- <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:42 +01:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
duplicate
enhancement
good first issue
help wanted
pull-request
Mirrored from GitHub Pull Request
No Label pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
adam
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/pkl#908
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?