docs: describe runtime-agnostic FFI usage

Author: Katze719

README.md

@@ -3,9 +3,16 @@
 [![Build](https://github.com/Serial-IO/cpp-bindings-linux/actions/workflows/build_binary.yml/badge.svg)](https://github.com/Serial-IO/cpp-bindings-linux/actions/workflows/build_binary.yml)
 [![JSR](https://jsr.io/badges/@serial/cpp-bindings-linux)](https://jsr.io/@serial/cpp-bindings-linux)
 
-Linux shared library for serial communication. It implements the
-[`cpp-core`](https://github.com/Serial-IO/cpp-core) interface and provides functions for discovering, opening,
-configuring, reading from, and writing to serial ports.
+Runtime-agnostic Linux shared library for serial communication. It implements
+the [`cpp-core`](https://github.com/Serial-IO/cpp-core) interface and provides
+functions for discovering, opening, configuring, reading from, and writing to
+serial ports.
+
+The library exposes a C-compatible ABI and can be used from any language or
+runtime that can load a GNU/Linux shared library and call C functions. Release
+artifacts include machine-readable FFI metadata for generating runtime-specific
+adapters, including exported symbols, types, callbacks, structs, defaults, and
+API documentation.
 
 ## Requirements
 
@@ -69,7 +76,9 @@ ctest --test-dir build --output-on-failure
 
 Tests that require a serial device use `SERIAL_TEST_PORT`. They are skipped when no suitable device is available.
 
-The optional Deno FFI smoke tests require Deno 2 and a built library:
+The optional runtime integration smoke tests currently use Deno 2 as their FFI
+test harness and require a built library. Deno is not required to consume the
+library from another compatible runtime:
 
 ```sh
 cd integration_tests

jsr/README.md

@@ -7,35 +7,45 @@ Binaries are provided as a
 [package on JSR](https://jsr.io/@serial/cpp-bindings-linux). They are serialized
 as a base64 string inside the JSON file.
 
+The contained shared libraries and FFI metadata are runtime-agnostic. They can
+be used by any language or runtime that can decode base64, write a file, load a
+GNU/Linux shared library, and call its C ABI. The TypeScript exports are a
+convenient distribution format, not a dependency on a particular runtime.
+
 The package contains portable binaries for `x86_64-linux-gnu` and
 `aarch64-linux-gnu`, both requiring glibc 2.28 or newer. The x86-64 artifact
 uses the generic x86-64 baseline.
 
 It also includes cpp-core FFI API metadata generated with
 [ASTrein](https://github.com/Katze719/ASTrein) at `bin/x86_64/ffi.json` and
 `bin/aarch64/ffi.json`. It describes the exported C symbols, parameter and
-return types, callbacks, default values, and API documentation used by
-downstream FFI adapter generators.
+return types, callbacks, structs, default values, and API documentation used by
+runtime-specific FFI adapter generators.
 
 This package is primarily intended as a dependency for
 [`@serial/serial`](https://jsr.io/@serial/serial). However, it can also be used
 independently.
 
 ## Usage
 
-Import the JSON and write the binary data to disk. Each architecture export also
-contains its matching FFI metadata:
+Select the export matching the host architecture. Each export contains the
+base64-encoded shared library and its matching FFI metadata:
 
 ```ts
 import { aarch64, x86_64 } from "@serial/cpp-bindings-linux/bin";
 
-const binary = Deno.build.arch === "aarch64" ? aarch64 : x86_64;
-Deno.writeFileSync(`./${binary.filename}`, Uint8Array.fromBase64(binary.data));
+// Select this with the architecture API provided by your runtime.
+const binary = x86_64;
 
-// The matching FFI metadata is available as `binary.ffi`.
-// Now you can open the binary using for example `Deno.dlopen`...
+// Decode `binary.data`, write it to `binary.filename`, and load it using your
+// runtime's filesystem and native FFI APIs. `binary.ffi` describes the C API
+// and its structs for generating or configuring a runtime-specific adapter.
 ```
 
+Non-JavaScript consumers can download the same architecture-specific `.so` and
+`.ffi.json` files directly from the
+[GitHub releases](https://github.com/Serial-IO/cpp-bindings-linux/releases).
+
 > [!NOTE]
 > For a more in depth guide, check out the
 > [Wiki](https://github.com/Serial-IO/cpp-bindings-linux/wiki) section on how to

jsr/jsr.json

@@ -1,7 +1,7 @@
 {
   "name": "@serial/cpp-bindings-linux",
   "version": "",
-  "description": "C++ Linux Bindings for the serial library",
+  "description": "Runtime-agnostic GNU/Linux serial FFI binaries and API metadata",
   "license": "LGPL-3.0-only",
   "exports": {
     "./bin": "./src/bin/index.ts"

jsr/src/bin/index.ts

@@ -7,14 +7,12 @@
  * ```ts
  * import { aarch64, x86_64 } from "@serial/cpp-bindings-linux/bin";
  *
- * const binary = Deno.build.arch === "aarch64" ? aarch64 : x86_64;
+ * // Select this with the architecture API provided by your runtime.
+ * const binary = x86_64;
  *
- * Deno.writeFileSync(
- *   `./${binary.filename}`,
- *   Uint8Array.fromBase64(binary.data),
- * );
- *
- * // The matching FFI metadata is available as `binary.ffi`.
+ * // Decode `binary.data`, write it to `binary.filename`, and load it using
+ * // your runtime's filesystem and native FFI APIs. The matching C API
+ * // metadata, including struct definitions, is available as `binary.ffi`.
  * ```
  * @module
  */
@@ -28,15 +26,17 @@ import x86_64ffi from "../../bin/x86_64/ffi.json" with { type: "json" };
  * The serialized `aarch64-linux-gnu` shared library and its FFI metadata.
  *
  * The library targets ARMv8-A and requires glibc 2.28 or newer. Decode `data`
- * from base64 and write it to `filename` before loading it with `Deno.dlopen`.
+ * from base64, write it to `filename`, and load it using the filesystem and
+ * native FFI APIs provided by your runtime.
  */
 const aarch64 = {
   ...aarch64Library,
   /**
    * ASTrein-generated metadata describing the library's exported C API.
    *
-   * It contains symbols, parameter and return types, callbacks, default
-   * values, and API documentation for generating FFI adapters.
+   * It contains symbols, parameter and return types, callbacks, struct
+   * definitions, default values, and API documentation for generating
+   * runtime-specific FFI adapters.
    */
   ffi: aarch64ffi,
 };
@@ -46,15 +46,16 @@ const aarch64 = {
  *
  * The library targets the generic x86-64 baseline and requires glibc 2.28 or
  * newer. Decode `data` from base64 and write it to `filename` before loading
- * it with `Deno.dlopen`.
+ * it using the filesystem and native FFI APIs provided by your runtime.
  */
 const x86_64 = {
   ...x86_64Library,
   /**
    * ASTrein-generated metadata describing the library's exported C API.
    *
-   * It contains symbols, parameter and return types, callbacks, default
-   * values, and API documentation for generating FFI adapters.
+   * It contains symbols, parameter and return types, callbacks, struct
+   * definitions, default values, and API documentation for generating
+   * runtime-specific FFI adapters.
    */
   ffi: x86_64ffi,
 };