C library for Pkl

[KushalP]

This PR introduces native C bindings for Pkl. See: #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

[KushalP]

I'm validating the interface here using pkl-go to get a feel for how language integrators would use this:

For a language like Go, where Go routines can be moved across OS threads without the user knowing, it can lead to issues with the Graal C interfaces like:

Fatal error: StackOverflowError: Enabling the yellow zone of the stack did not make any stack space available. Possible reasons for that: 1) A call from native code to Java code provided the wrong JNI environment or the wrong IsolateThread; 2) Frames of native code filled the stack, and now there is not even enough stack space left to throw a regular StackOverflowError; 3) An internal VM error occurred.

We don't want to expose the inner workings to users, so we need to be defensive to this case.

[KushalP]

Rebased against 0.30.0 release

[bioball]

Closing this; work is continuing on #1238