From cdf2d1f44b8a69a5518b9aea5a4416beb1693f3d Mon Sep 17 00:00:00 2001 From: Katze719 Date: Mon, 31 Aug 2026 10:53:48 +0200 Subject: [PATCH 1/8] docs: document JSR binary exports --- jsr/src/bin/index.ts | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/jsr/src/bin/index.ts b/jsr/src/bin/index.ts index e73e809..88e8d2b 100644 --- a/jsr/src/bin/index.ts +++ b/jsr/src/bin/index.ts @@ -24,13 +24,38 @@ import aarch64ffi from "../../bin/aarch64/ffi.json" with { type: "json" }; import x86_64Library from "../../bin/x86_64/library.json" with { type: "json" }; 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`. + */ 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. + */ ffi: aarch64ffi, }; +/** + * The serialized `x86_64-linux-gnu` shared library and its FFI metadata. + * + * 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`. + */ 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. + */ ffi: x86_64ffi, }; From b7e68af80f86718c40a0e5ffb06c71dd69f79fcd Mon Sep 17 00:00:00 2001 From: Katze719 Date: Mon, 31 Aug 2026 10:58:15 +0200 Subject: [PATCH 2/8] docs: describe runtime-agnostic FFI usage --- README.md | 17 +++++++++++++---- jsr/README.md | 26 ++++++++++++++++++-------- jsr/jsr.json | 2 +- jsr/src/bin/index.ts | 27 ++++++++++++++------------- 4 files changed, 46 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 22ebb03..a1ec780 100644 --- a/README.md +++ b/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 diff --git a/jsr/README.md b/jsr/README.md index 228a6e7..9a0f92c 100644 --- a/jsr/README.md +++ b/jsr/README.md @@ -7,6 +7,11 @@ 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. @@ -14,8 +19,8 @@ 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 @@ -23,19 +28,24 @@ 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 diff --git a/jsr/jsr.json b/jsr/jsr.json index c805bb8..8dd42b0 100644 --- a/jsr/jsr.json +++ b/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" diff --git a/jsr/src/bin/index.ts b/jsr/src/bin/index.ts index 88e8d2b..340d443 100644 --- a/jsr/src/bin/index.ts +++ b/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, }; From b64c0cfd972303a4cbbd4d169ea06a7bfb1957b6 Mon Sep 17 00:00:00 2001 From: Katze719 Date: Mon, 31 Aug 2026 11:08:46 +0200 Subject: [PATCH 3/8] docs: remove glibc distribution version details from compatibility table --- README.md | 25 +++++++++++++++++++++++++ jsr/README.md | 25 +++++++++++++++++++++++++ 2 files changed, 50 insertions(+) diff --git a/README.md b/README.md index a1ec780..823ab76 100644 --- a/README.md +++ b/README.md @@ -42,6 +42,31 @@ Official release and JSR artifacts are built for these GNU/Linux targets: | `x86_64-linux-gnu` | generic x86-64 | 2.28 | | `aarch64-linux-gnu` | ARMv8-A | 2.28 | +### Binary compatibility + +The prebuilt binaries require **glibc 2.28 or newer**. Compatibility depends on +the installed glibc version rather than the distribution name. Common release +baselines are shown below for orientation: + +| Distribution | Release baseline | +| --- | --- | +| Debian | 10+ | +| Ubuntu | 20.04 LTS+ | +| RHEL / Rocky Linux / AlmaLinux | 8+ | +| Fedora | 29+ | +| openSUSE Leap | 15.x (not compatible by default) | + +Check the installed version with: + +```sh +ldd --version +``` + +These versions indicate binary compatibility and do not imply that the listed +distribution releases are still supported by their vendors. + +### Portable release builds + The release builds statically include the GNU C++ and compiler runtimes. They still use the target system's glibc and therefore require glibc 2.28 or newer. To reproduce the portable release configuration for the host architecture: diff --git a/jsr/README.md b/jsr/README.md index 9a0f92c..424a5fc 100644 --- a/jsr/README.md +++ b/jsr/README.md @@ -16,6 +16,31 @@ 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. +## Binary compatibility + +The prebuilt binaries require **glibc 2.28 or newer**. Compatibility depends on +the installed glibc version rather than the distribution name. Common release +baselines are shown below for orientation: + +| Distribution | Release baseline | +| --- | --- | +| Debian | 10+ | +| Ubuntu | 20.04 LTS+ | +| RHEL / Rocky Linux / AlmaLinux | 8+ | +| Fedora | 29+ | +| openSUSE Leap | 15.x (not compatible by default) | + +Check the installed version with: + +```sh +ldd --version +``` + +These versions indicate binary compatibility and do not imply that the listed +distribution releases are still supported by their vendors. + +## FFI metadata + 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 From c981099eeeb9bdaaef123d2cebba1988cb7d3b24 Mon Sep 17 00:00:00 2001 From: Katze719 Date: Mon, 31 Aug 2026 11:49:38 +0200 Subject: [PATCH 4/8] docs: add JavaScript runtime usage examples --- jsr/README.md | 128 +++++++++++++++++++++++++++++++++++++++---- jsr/src/bin/index.ts | 84 +++++++++++++++++++++++++--- 2 files changed, 195 insertions(+), 17 deletions(-) diff --git a/jsr/README.md b/jsr/README.md index 424a5fc..6f419b0 100644 --- a/jsr/README.md +++ b/jsr/README.md @@ -7,10 +7,10 @@ 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. +This package targets server-side JavaScript runtimes that can write files and +load GNU/Linux shared libraries. Deno can consume it directly from JSR; Bun and +Node.js use JSR's npm compatibility layer. Browser and edge runtimes cannot use +the native library because they do not expose native FFI access. 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 @@ -54,19 +54,127 @@ independently. ## Usage Select the export matching the host architecture. Each export contains the -base64-encoded shared library and its matching FFI metadata: +base64-encoded shared library and its matching FFI metadata. The following +examples write the library to disk, load it, and release it again. + +### Deno + +Deno provides native JSR imports and the built-in `Deno.dlopen` FFI API. Save +this as `example.ts`: ```ts +import { aarch64, x86_64 } from "jsr:@serial/cpp-bindings-linux/bin"; + +const binary = Deno.build.arch === "aarch64" ? aarch64 : x86_64; +const path = `./${binary.filename}`; + +Deno.writeFileSync(path, Uint8Array.fromBase64(binary.data)); + +const library = Deno.dlopen(path, { + serialClose: { + parameters: ["i64", "pointer"], + result: "i32", + }, +}); +library.close(); +``` + +Run it with write and FFI permissions: + +```sh +deno run --allow-write --allow-ffi example.ts +``` + +### Bun + +Add the package through JSR's npm compatibility layer: + +```sh +bunx jsr add @serial/cpp-bindings-linux +``` + +Then use Bun's built-in `bun:ffi` and `Bun.write` APIs: + +```ts +import { dlopen } from "bun:ffi"; +import { resolve } from "node:path"; +import { aarch64, x86_64 } from "@serial/cpp-bindings-linux/bin"; + +const binary = process.arch === "arm64" + ? aarch64 + : process.arch === "x64" + ? x86_64 + : undefined; + +if (!binary) { + throw new Error(`Unsupported architecture: ${process.arch}`); +} + +const path = resolve(binary.filename); +await Bun.write(path, Buffer.from(binary.data, "base64")); + +const library = dlopen(path, { + serialClose: { + args: ["i64", "ptr"], + returns: "i32", + }, +}); +library.close(); +``` + +```sh +bun run example.ts +``` + +> [!WARNING] +> Bun currently marks its built-in +> [`bun:ffi` API](https://bun.sh/docs/runtime/ffi) as experimental. + +### Node.js + +Node.js does not provide a general-purpose C FFI API. This example uses +[Koffi](https://koffi.dev/), together with JSR's npm compatibility layer: + +```sh +npx jsr add @serial/cpp-bindings-linux +npm install koffi +``` + +Save this as `example.mjs`: + +```js +import { writeFileSync } from "node:fs"; +import { resolve } from "node:path"; +import koffi from "koffi"; import { aarch64, x86_64 } from "@serial/cpp-bindings-linux/bin"; -// Select this with the architecture API provided by your runtime. -const binary = x86_64; +const binary = process.arch === "arm64" + ? aarch64 + : process.arch === "x64" + ? x86_64 + : undefined; + +if (!binary) { + throw new Error(`Unsupported architecture: ${process.arch}`); +} + +const path = resolve(binary.filename); +writeFileSync(path, Buffer.from(binary.data, "base64")); -// 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. +const library = koffi.load(path); +library.func("int serialClose(int64_t handle, void *error_callback)"); +library.unload(); ``` +```sh +node example.mjs +``` + +These examples verify that the native library can be loaded and that its +`serialClose` symbol can be resolved. The matching `binary.ffi` value describes +the complete set of symbols and structs for generating or configuring +runtime-specific bindings. + 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). diff --git a/jsr/src/bin/index.ts b/jsr/src/bin/index.ts index 340d443..bdbca6b 100644 --- a/jsr/src/bin/index.ts +++ b/jsr/src/bin/index.ts @@ -1,19 +1,89 @@ /** * Module that provides serialized binaries and FFI metadata. * - * @example - * Import the corresponding binary and write the file to disk. + * @example Deno * * ```ts + * import { aarch64, x86_64 } from "jsr:@serial/cpp-bindings-linux/bin"; + * + * const binary = Deno.build.arch === "aarch64" ? aarch64 : x86_64; + * const path = `./${binary.filename}`; + * + * Deno.writeFileSync(path, Uint8Array.fromBase64(binary.data)); + * + * const library = Deno.dlopen(path, { + * serialClose: { + * parameters: ["i64", "pointer"], + * result: "i32", + * }, + * }); + * library.close(); + * ``` + * + * Run with `deno run --allow-write --allow-ffi example.ts`. + * + * @example Bun + * + * Install with `bunx jsr add @serial/cpp-bindings-linux`, then: + * + * ```ts + * import { dlopen } from "bun:ffi"; + * import { resolve } from "node:path"; * import { aarch64, x86_64 } from "@serial/cpp-bindings-linux/bin"; * - * // Select this with the architecture API provided by your runtime. - * const binary = x86_64; + * const binary = process.arch === "arm64" + * ? aarch64 + * : process.arch === "x64" + * ? x86_64 + * : undefined; + * + * if (!binary) { + * throw new Error(`Unsupported architecture: ${process.arch}`); + * } + * + * const path = resolve(binary.filename); + * await Bun.write(path, Buffer.from(binary.data, "base64")); * - * // 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`. + * const library = dlopen(path, { + * serialClose: { + * args: ["i64", "ptr"], + * returns: "i32", + * }, + * }); + * library.close(); * ``` + * + * @example Node.js + * + * Install with `npx jsr add @serial/cpp-bindings-linux` and + * `npm install koffi`, then: + * + * ```js + * import { writeFileSync } from "node:fs"; + * import { resolve } from "node:path"; + * import koffi from "koffi"; + * import { aarch64, x86_64 } from "@serial/cpp-bindings-linux/bin"; + * + * const binary = process.arch === "arm64" + * ? aarch64 + * : process.arch === "x64" + * ? x86_64 + * : undefined; + * + * if (!binary) { + * throw new Error(`Unsupported architecture: ${process.arch}`); + * } + * + * const path = resolve(binary.filename); + * writeFileSync(path, Buffer.from(binary.data, "base64")); + * + * const library = koffi.load(path); + * library.func("int serialClose(int64_t handle, void *error_callback)"); + * library.unload(); + * ``` + * + * The matching C API metadata, including struct definitions, is available as + * `binary.ffi` in every runtime. * @module */ From 232a226751ba8e06021280f80728dc8891f18d70 Mon Sep 17 00:00:00 2001 From: Katze719 Date: Mon, 31 Aug 2026 12:00:09 +0200 Subject: [PATCH 5/8] docs: use serialOpen in runtime examples --- jsr/README.md | 23 +++++++++++++++-------- jsr/src/bin/index.ts | 21 ++++++++++++++------- 2 files changed, 29 insertions(+), 15 deletions(-) diff --git a/jsr/README.md b/jsr/README.md index 6f419b0..322e815 100644 --- a/jsr/README.md +++ b/jsr/README.md @@ -71,9 +71,9 @@ const path = `./${binary.filename}`; Deno.writeFileSync(path, Uint8Array.fromBase64(binary.data)); const library = Deno.dlopen(path, { - serialClose: { - parameters: ["i64", "pointer"], - result: "i32", + serialOpen: { + parameters: ["pointer", "i32", "i32", "i32", "i32", "pointer"], + result: "i64", }, }); library.close(); @@ -114,9 +114,9 @@ const path = resolve(binary.filename); await Bun.write(path, Buffer.from(binary.data, "base64")); const library = dlopen(path, { - serialClose: { - args: ["i64", "ptr"], - returns: "i32", + serialOpen: { + args: ["ptr", "i32", "i32", "i32", "i32", "ptr"], + returns: "i64", }, }); library.close(); @@ -162,7 +162,14 @@ const path = resolve(binary.filename); writeFileSync(path, Buffer.from(binary.data, "base64")); const library = koffi.load(path); -library.func("int serialClose(int64_t handle, void *error_callback)"); +library.func("serialOpen", "int64_t", [ + "void *", + "int", + "int", + "int", + "int", + "void *", +]); library.unload(); ``` @@ -171,7 +178,7 @@ node example.mjs ``` These examples verify that the native library can be loaded and that its -`serialClose` symbol can be resolved. The matching `binary.ffi` value describes +`serialOpen` symbol can be resolved. The matching `binary.ffi` value describes the complete set of symbols and structs for generating or configuring runtime-specific bindings. diff --git a/jsr/src/bin/index.ts b/jsr/src/bin/index.ts index bdbca6b..2ab698b 100644 --- a/jsr/src/bin/index.ts +++ b/jsr/src/bin/index.ts @@ -12,9 +12,9 @@ * Deno.writeFileSync(path, Uint8Array.fromBase64(binary.data)); * * const library = Deno.dlopen(path, { - * serialClose: { - * parameters: ["i64", "pointer"], - * result: "i32", + * serialOpen: { + * parameters: ["pointer", "i32", "i32", "i32", "i32", "pointer"], + * result: "i64", * }, * }); * library.close(); @@ -45,9 +45,9 @@ * await Bun.write(path, Buffer.from(binary.data, "base64")); * * const library = dlopen(path, { - * serialClose: { - * args: ["i64", "ptr"], - * returns: "i32", + * serialOpen: { + * args: ["ptr", "i32", "i32", "i32", "i32", "ptr"], + * returns: "i64", * }, * }); * library.close(); @@ -78,7 +78,14 @@ * writeFileSync(path, Buffer.from(binary.data, "base64")); * * const library = koffi.load(path); - * library.func("int serialClose(int64_t handle, void *error_callback)"); + * library.func("serialOpen", "int64_t", [ + * "void *", + * "int", + * "int", + * "int", + * "int", + * "void *", + * ]); * library.unload(); * ``` * From 064c2336cfa6daa4b1a0db4fd070d7dbc880e2b6 Mon Sep 17 00:00:00 2001 From: Mqx <62719703+Mqxx@users.noreply.github.com> Date: Mon, 31 Aug 2026 14:25:12 +0200 Subject: [PATCH 6/8] fix: JSDoc Changed title of examples and formatting --- jsr/src/bin/index.ts | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/jsr/src/bin/index.ts b/jsr/src/bin/index.ts index 2ab698b..4efe5ca 100644 --- a/jsr/src/bin/index.ts +++ b/jsr/src/bin/index.ts @@ -1,7 +1,8 @@ /** * Module that provides serialized binaries and FFI metadata. * - * @example Deno + * @example + * Usage with Deno * * ```ts * import { aarch64, x86_64 } from "jsr:@serial/cpp-bindings-linux/bin"; @@ -20,11 +21,8 @@ * library.close(); * ``` * - * Run with `deno run --allow-write --allow-ffi example.ts`. - * - * @example Bun - * - * Install with `bunx jsr add @serial/cpp-bindings-linux`, then: + * @example + * Usage with Bun * * ```ts * import { dlopen } from "bun:ffi"; @@ -53,10 +51,8 @@ * library.close(); * ``` * - * @example Node.js - * - * Install with `npx jsr add @serial/cpp-bindings-linux` and - * `npm install koffi`, then: + * @example + * Usage with Node.js * * ```js * import { writeFileSync } from "node:fs"; From 5f4665dbb02870b80d268a1f5b0aaa0258895dfd Mon Sep 17 00:00:00 2001 From: Katze719 Date: Mon, 31 Aug 2026 18:33:06 +0200 Subject: [PATCH 7/8] ci: set up ASTrein with dedicated action --- .github/workflows/build_binary.yml | 32 ++++++------------------------ 1 file changed, 6 insertions(+), 26 deletions(-) diff --git a/.github/workflows/build_binary.yml b/.github/workflows/build_binary.yml index 9bdb0c0..cff3e48 100644 --- a/.github/workflows/build_binary.yml +++ b/.github/workflows/build_binary.yml @@ -17,7 +17,6 @@ jobs: runs-on: ${{ matrix.runner }} env: ASTREIN_VERSION: '2.0.0' - ASTREIN_SHA256: ${{ matrix.astrein-sha256 }} strategy: fail-fast: false @@ -26,14 +25,10 @@ jobs: - target: x86_64-linux-gnu arch: x86_64 runner: ubuntu-24.04 - astrein-archive: astrein-linux-x86_64.tar.gz - astrein-sha256: 'c024f62f8bb4c7b5342249de5844d19276ae92293bf8cc7edf7475280503168e' - target: aarch64-linux-gnu arch: aarch64 runner: ubuntu-24.04-arm - astrein-archive: astrein-linux-aarch64.tar.gz - astrein-sha256: 'bab7501555d91f355bca797a38af16d9e01067591abf20b0147a8a0985558e33' steps: - name: 'Checkout repository' @@ -41,13 +36,6 @@ jobs: with: fetch-depth: 0 - - name: 'Validate ASTrein checksum' - run: | - if [[ ! "${ASTREIN_SHA256}" =~ ^[[:xdigit:]]{64}$ ]]; then - echo "Set the SHA-256 for ${{ matrix.astrein-archive }} after ASTrein v${ASTREIN_VERSION} is released." >&2 - exit 1 - fi - - name: 'Install native compiler' run: | sudo apt-get update @@ -55,19 +43,11 @@ jobs: gcc-14 \ g++-14 - - name: 'Download ASTrein' - run: | - curl --fail --location \ - --output "${RUNNER_TEMP}/${{ matrix.astrein-archive }}" \ - "https://github.com/Katze719/ASTrein/releases/download/v${ASTREIN_VERSION}/${{ matrix.astrein-archive }}" - echo "${ASTREIN_SHA256} ${RUNNER_TEMP}/${{ matrix.astrein-archive }}" \ - | sha256sum --check - - - mkdir -p "${RUNNER_TEMP}/astrein" - tar -xzf "${RUNNER_TEMP}/${{ matrix.astrein-archive }}" \ - -C "${RUNNER_TEMP}/astrein" \ - --strip-components=1 - "${RUNNER_TEMP}/astrein/bin/astrein" --version + - name: 'Setup ASTrein' + id: astrein + uses: Katze719/setup-astrein@v1 + with: + version: ${{ env.ASTREIN_VERSION }} - name: 'Setup CMake' uses: jwlawson/actions-setup-cmake@v2 @@ -81,7 +61,7 @@ jobs: -DCMAKE_C_COMPILER=gcc-14 \ -DCMAKE_CXX_COMPILER=g++-14 \ -DCPP_BINDINGS_LINUX_ENABLE_FFI_JSON_EXPORT=ON \ - -DCPP_BINDINGS_LINUX_ASTREIN_EXECUTABLE="${RUNNER_TEMP}/astrein/bin/astrein" \ + -DCPP_BINDINGS_LINUX_ASTREIN_EXECUTABLE="${{ steps.astrein.outputs.path }}" \ -DCPP_BINDINGS_LINUX_FFI_JSON_OUTPUT="${GITHUB_WORKSPACE}/dist/ffi/${{ matrix.arch }}.ffi.json" - name: 'Generate metadata' From 5b92142d54d9e4272b7d79aa5398a9c12bab0e2e Mon Sep 17 00:00:00 2001 From: Katze719 <38188106+Katze719@users.noreply.github.com> Date: Mon, 31 Aug 2026 18:40:42 +0200 Subject: [PATCH 8/8] Apply suggestion from @Mqxx Co-authored-by: Mqx <62719703+Mqxx@users.noreply.github.com> --- jsr/src/bin/index.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jsr/src/bin/index.ts b/jsr/src/bin/index.ts index 4efe5ca..642fae9 100644 --- a/jsr/src/bin/index.ts +++ b/jsr/src/bin/index.ts @@ -5,7 +5,7 @@ * Usage with Deno * * ```ts - * import { aarch64, x86_64 } from "jsr:@serial/cpp-bindings-linux/bin"; + * import { aarch64, x86_64 } from "@serial/cpp-bindings-linux/bin"; * * const binary = Deno.build.arch === "aarch64" ? aarch64 : x86_64; * const path = `./${binary.filename}`;