Add documentation for libpkl (#1801)

This adds a new Antora module for libpkl, and updates the language
bindings documentation.

Co-authored-by: Jen Basch <jbasch94@gmail.com>
Co-authored-by: Islon Scherer <islonscherer@gmail.com>

docs/modules/ROOT/pages/language-bindings.adoc

@@ -4,6 +4,7 @@
 * xref:kotlin-binding:index.adoc[Kotlin]
 * xref:swift:ROOT:index.adoc[Swift]
 * xref:go:ROOT:index.adoc[Go]
+* xref:libpkl:index.adoc[libpkl]
 * xref:bindings-specification:index.adoc[Specification]
 ** xref:bindings-specification:message-passing-api.adoc[Message Passing API]
 ** xref:bindings-specification:binary-encoding.adoc[Pkl Binary Encoding]

docs/modules/bindings-specification/pages/index.adoc

@@ -7,7 +7,10 @@ Pkl can be embedded within any host application.
 The host application has access to low level controls.
 It is able to manage the lifecycle of evaluators, as well as provide custom modules and resources to Pkl.
 
-Currently, Pkl must be embedded as a child process, by shelling out to the CLI using the xref:pkl-cli:index.adoc#command-server[`pkl server`] command. In the future, a C library will also be provided.
+Pkl can be embedded in one of two ways:
+
+. By spawning xref:pkl-cli:index.adoc#command-server[`pkl server`] as a subprocess, and communicating with it via STDIN/STDOUT.
+. By linking to the xref:libpkl:index.adoc[libpkl library].
 
 When embedded, communication between a host application and Pkl happens via message passing.
 The message passing specification can be found in xref:message-passing-api.adoc[].
@@ -20,7 +23,7 @@ NOTE: Pkl's Java and Kotlin libraries binds to Pkl directly, and do not use mess
 
 A language binding for Pkl should generally have the following components:
 
-. A client that spawns `pkl server`, and talks to it using message passing.
+. A client that either spawns `pkl server` or links to `libpkl`, and talks to it using message passing.
 . A deserializer that turns xref:binary-encoding.adoc[pkl binary encoding] into a structure in the host language.
 . A code generator that transforms Pkl schemas into schemas written in the host language.
   The code generator is mostly written in Pkl, with a lightweight executable that acts as the glue layer.

docs/modules/libpkl/pages/index.adoc

@@ -0,0 +1,89 @@
+= libpkl
+
+libpkl is a C library for driving Pkl evaluation.
+
+It is designed to be a low-level API that interacts with Pkl via the xref:bindings-specification:message-passing-api.adoc[message passing API].
+It is meant to be paired with higher level logic written in a host language within the context of a Pkl language binding library.
+The higher level logic deals with implementing the evaluator API, and serializing/deserializing messages according to the message passing API.
+
+== Linking to libpkl
+
+It is possible to link to libpkl either as a static library or a dynamic library.
+
+Statically linking to libpkl means that it is possible to copy libpkl's library code directly into your own library or executable at compile time, meaning that it is self-contained.
+However, this impacts the binary size of your application, as libpkl's library files are around 100MB.
+
+On the other hand, dynamically linking to libpkl has negligible impact on binary size, but requires that end users have libpkl installed on their OS.
+
+== Distribution
+
+We publish archives that contain header files, as well as both shared and static libraries.
+
+The distributions are published as releases on GitHub, and can be downloaded for the appropriate OS/architecture.
+
+The archives contain both statically linked and dynamically linked binaries for each OS.
+
+The archive has the following structure:
+
+[source]
+----
+.
+└── libpkl-<version>-<os>-<arch>
+    ├── include
+    │   └── pkl.h
+    ├── lib
+    │   ├── libpkl.<static library extension>
+    │   ├── libpkl.<dynamic library extension>
+    │   └── pkgconfig
+    │       └── libpkl.pc
+    ├── LICENSE.txt
+    ├── README.md
+    └── THIRD-PARTY-NOTICES.txt
+----
+
+The file extensions are as follows:
+|===
+|OS |Static Library Extension |Dynamic library extension
+
+|macOS
+|`.a`
+|`.dylib`
+
+|Linux
+|`.a`
+|`.so`
+
+|Windows
+|`.lib`
+|`.dll`
+|===
+
+== Building libpkl from source
+
+To build libpkl from source, the apple/pkl repository first must be cloned down to a host OS.
+
+Build machine requirements:
+
+* Java 21 or higher
+* zlib
+* C compiler
+** `cc` (gcc, clang) toolchain on Unix
+** MSVC toolchain on Windows
+
+Example:
+
+[source,shell]
+----
+git clone git@github.com:apple/pkl.git
+cd pkl/
+./gradlew libpkl:buildNative
+----
+
+The resulting archive will be written to `libpkl/build/distributions`.
+
+Cross-compilation is not supported.
+
+== ABI compatibility
+
+libpkl is ABI compatible across Pkl versions.
+The underlying Pkl version can be accessed using the `pkl_version()` method.

docs/nav.adoc

@@ -23,6 +23,7 @@
 **** xref:kotlin-binding:pkl-config-kotlin.adoc[pkl-config-kotlin Library]
 *** xref:swift:ROOT:index.adoc[Swift]
 *** xref:go:ROOT:index.adoc[Go]
+*** xref:libpkl:index.adoc[libpkl]
 *** xref:bindings-specification:index.adoc[Specification]
 **** xref:bindings-specification:message-passing-api.adoc[Message Passing API]
 **** xref:bindings-specification:binary-encoding.adoc[Pkl Binary Encoding]