Split libpkl libraries between shared and static libs (#1812)

This adds a `libpkl-static.pc` so pkg-config users can link either
statically or dynamically via `pkg-config --libs libpkl`, or
`pkg-config --libs libpkl-static`.

Additionally, this fixes an issue where the replace tokens wasn't
doing anything, leaving the `@version@` token intact in the archive.

Additionally, this adds an `-install_name` when building the dylib for macOS.

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

docs/modules/libpkl/pages/index.adoc

@@ -1,4 +1,5 @@
 = libpkl
+include::ROOT:partial$component-attributes.adoc[]
 
 libpkl is a C library for driving Pkl evaluation.
 
@@ -32,9 +33,10 @@ The archive has the following structure:
     ├── include
     │   └── pkl.h
     ├── lib
+    │   ├── libpkl.<shared library extension>
     │   ├── libpkl.<static library extension>
-    │   ├── libpkl.<dynamic library extension>
     │   └── pkgconfig
+    │       ├── libpkl-static.pc
     │       └── libpkl.pc
     ├── LICENSE.txt
     ├── README.md
@@ -43,7 +45,7 @@ The archive has the following structure:
 
 The file extensions are as follows:
 |===
-|OS |Static Library Extension |Dynamic library extension
+|OS |Static Library Extension |Shared library extension
 
 |macOS
 |`.a`
@@ -58,6 +60,44 @@ The file extensions are as follows:
 |`.dll`
 |===
 
+=== Linking to the static vs. shared library
+
+The simplest way to configure your compiler to link to either the static or the shared library is to use https://en.wikipedia.org/wiki/Pkg-config[pkg-config].
+
+The libpkl library ships with two pkg-config files: `libpkl.pc`, and `libpkl-static.pc`.
+
+The normal `libpkl.pc` links to the shared library.
+
+To unambiguously link to the static library, use `libpkl-static.pc`.
+
+For example, when using `cc`:
+
+[source,shell]
+----
+# Link against the shared library
+cc -o myprogram myprogram.c $(pkg-config --libs --cflags libpkl)
+
+# Link against the static library
+cc -o myprogram myprogram.c $(pkg-config --static --libs --cflags libpkl-static)
+----
+
+
+If libpkl is installed in a non-system directory, set `PKG_CONFIG_PATH` to the subpath `lib/pkgconfig` within the directory that contains libpkl. For example, given libpkl directory `/path/to/libpkl`, the environment variable should have `/path/to/libpkl/lib/pkgconfig`.
+
+NOTE: Windows can use pkg-config through the https://www.msys2.org/docs/pkgconfig/[MSYS2 toolchain]. Using pkg-config on Windows implies compiling with gcc-style compiler like https://code.visualstudio.com/docs/cpp/config-mingw[MinGW], instead of MSVC.
+
+[NOTE]
+====
+It's also possible to link to the static library with the normal `libpkl.pc`.
+
+For example:
+
+[source,shell]
+----
+cc -Wl,-Bstatic $(pkg-config --libs --cflags libpkl)
+----
+====
+
 == Building libpkl from source
 
 To build libpkl from source, the apple/pkl repository first must be cloned down to a host OS.
@@ -79,7 +119,10 @@ cd pkl/
 ./gradlew libpkl:buildNative
 ----
 
-The resulting archive will be written to `libpkl/build/distributions`.
+This results in two directories of interest:
+
+* `libpkl/build/distributions/`: directory containing archives (`.zip` on Windows, `.tar.gz` on macOS/Linux) of C libraries.
+* `libpkl/build/native-libs/<os>-<arch>`: directory containing the built library files (the inner structure of the archive).
 
 Cross-compilation is not supported.