koffi 2.9.1 → 2.10.0

package/CHANGELOG.md

@@ -1,9 +1,24 @@
-# Changelog
+# Version history
 
-## Version history
+> [!NOTE]
+> Consult the [migration guide](migration) to migrate between major Koffi versions.
+
+## Koffi 2
+
+### Koffi 2.10
+
+#### Koffi 2.10.0 (2024-12-22)
+
+- Allow [redefinition of opaque types](misc#circular-references) to concrete struct or union
+- Update documentation style
 
 ### Koffi 2.9
 
+#### Koffi 2.9.2 (2024-11-08)
+
+- Fix non-aligned pointers when pushing UTF-16 and UTF-32 string parameters
+- Various documentation fixes and improvements
+
 #### Koffi 2.9.1 (2024-09-23)
 
 - Fix x86 32-bit support regression in 2.9.0
@@ -21,9 +36,8 @@
 
 - Work around MSVC compiler bug introduced in Visual Studio 17.10
 
-```{warning}
-Use on platforms without pre-built binaries is broken in Koffi 2.8.10, skip this version.
-```
+> [!WARNING]
+> Use on platforms without pre-built binaries is broken in Koffi 2.8.10, skip this version.
 
 #### Koffi 2.8.9 (2024-05-17)
 
@@ -39,7 +53,7 @@ Use on platforms without pre-built binaries is broken in Koffi 2.8.10, skip this
 
 #### Koffi 2.8.6 (2024-04-12)
 
-- Support [loading library](functions.md#loading-options) with RTLD_DEEPBIND where supported
+- Support [loading library](functions#loading-options) with RTLD_DEEPBIND where supported
 
 #### Koffi 2.8.5 (2024-04-11)
 
@@ -51,13 +65,12 @@ Use on platforms without pre-built binaries is broken in Koffi 2.8.10, skip this
 
 - Use simpler workaround for Node 20.12+ and 21.6+ to avoid excessive memory use
 
-```{warning}
-Some pre-built binaries are missing in Koffi 2.8.3, skip this version.
-```
+> [!WARNING]
+> Some pre-built binaries are missing in Koffi 2.8.3, skip this version.
 
 #### Koffi 2.8.2 (2024-04-07)
 
-- Support [loading library](functions.md#loading-options) with RTLD_GLOBAL on POSIX platforms
+- Support [loading library](functions#loading-options) with RTLD_GLOBAL on POSIX platforms
 
 #### Koffi 2.8.1 (2024-04-04)
 
@@ -66,7 +79,7 @@ Some pre-built binaries are missing in Koffi 2.8.3, skip this version.
 #### Koffi 2.8.0 (2024-02-12)
 
 - Support pushing pointers for string arguments
-- Add `koffi.alloc()` for [stable pointers](output.md#stable-pointers)
+- Add `koffi.alloc()` for [stable pointers](output#stable-pointers)
 
 ### Koffi 2.7
 
@@ -89,13 +102,13 @@ Some pre-built binaries are missing in Koffi 2.8.3, skip this version.
 
 #### Koffi 2.7.1 (2024-01-02)
 
-- Support C-like `int[3]` syntax for [fixed array types](input.md#fixed-size-c-arrays)
+- Support C-like `int[3]` syntax for [fixed array types](input#fixed-size-c-arrays)
 - Refuse type specifiers with invalid tokens at the end (previously ignored)
 
 #### Koffi 2.7.0 (2023-12-21)
 
-- Support alternative [callback calling convention](callbacks.md#callback-types) in classic syntax
-- Change syntax for [calling conventions](functions.md#calling-conventions) with classic syntax
+- Support alternative [callback calling convention](callbacks#callback-types) in classic syntax
+- Change syntax for [calling conventions](functions#calling-conventions) with classic syntax
 - Drop unused "internal" property from Koffi
 
 ### Koffi 2.6
@@ -107,7 +120,7 @@ Some pre-built binaries are missing in Koffi 2.8.3, skip this version.
 #### Koffi 2.6.11 (2023-12-05)
 
 - Speed up resolving simple and often used type names
-- Fix use of optional length argument with [koffi.encode()](variables.md#encode-to-c-memory)
+- Fix use of optional length argument with [koffi.encode()](variables#encode-to-c-memory)
 
 #### Koffi 2.6.10 (2023-11-29)
 
@@ -120,9 +133,8 @@ Some pre-built binaries are missing in Koffi 2.8.3, skip this version.
 - Show detected version of Node when not adequate
 - Minor documentation fixes
 
-```{warning}
-Loading Win32 system libraries can fail in Koffi 2.6.8, skip this version.
-```
+> [!WARNING]
+> Loading Win32 system libraries can fail in Koffi 2.6.8, skip this version.
 
 #### Koffi 2.6.6 (2023-10-28)
 
@@ -141,9 +153,8 @@ Loading Win32 system libraries can fail in Koffi 2.6.8, skip this version.
 
 - Add indirect loading script to help some bundlers
 
-```{warning}
-Pre-built binaries don't work correctly in Koffi 2.6.2, skip this version.
-```
+> [!WARNING]
+> Pre-built binaries don't work correctly in Koffi 2.6.2, skip this version.
 
 #### Koffi 2.6.1 (2023-09-18)
 
@@ -154,9 +165,9 @@ Pre-built binaries don't work correctly in Koffi 2.6.2, skip this version.
 
 **New features:**
 
-- Use [koffi.symbol()](variables.md#variable-definitions) to make pointers to exported variables (or other symbols)
-- Use [koffi.encode()](variables.md#encode-to-c-memory) to explictly encode data from JS to C memory
-- Use shared library [lazy-loading](functions.md#loading-options) (RTLD_LAZY) on POSIX platforms
+- Use [koffi.symbol()](variables#variable-definitions) to make pointers to exported variables (or other symbols)
+- Use [koffi.encode()](variables#encode-to-c-memory) to explictly encode data from JS to C memory
+- Use shared library [lazy-loading](functions#loading-options) (RTLD_LAZY) on POSIX platforms
 
 **Other changes:**
 
@@ -173,7 +184,7 @@ Pre-built binaries don't work correctly in Koffi 2.6.2, skip this version.
 #### Koffi 2.5.19 (2023-08-29)
 
 - Create thread-safe function broker lazily
-- Add [koffi.reset()](misc.md#reset-internal-state) for type names and async broker
+- Add [koffi.reset()](misc#reset-internal-state) for type names and async broker
 
 #### Koffi 2.5.18 (2023-08-27)
 
@@ -185,9 +196,8 @@ Pre-built binaries don't work correctly in Koffi 2.6.2, skip this version.
 - Fix DLL error when using Koffi from NW.js on Windows
 - Simplify NW.js Koffi example
 
-```{warning}
-Pre-built binaries don't work correctly in Koffi 2.5.13 to 2.5.15, skip those versions.
-```
+> [!WARNING]
+> Pre-built binaries don't work correctly in Koffi 2.5.13 to 2.5.15, skip those versions.
 
 #### Koffi 2.5.12 (2023-08-21)
 
@@ -196,7 +206,7 @@ Pre-built binaries don't work correctly in Koffi 2.5.13 to 2.5.15, skip those ve
 
 #### Koffi 2.5.11 (2023-08-03)
 
-- Support casting function pointers with [koffi.as()](pointers.md#handling-void-pointers)
+- Support casting function pointers with [koffi.as()](pointers#handling-void-pointers)
 - Build in C++20 mode
 
 #### Koffi 2.5.10 (2023-08-01)
@@ -218,7 +228,7 @@ Pre-built binaries don't work correctly in Koffi 2.5.13 to 2.5.15, skip those ve
 #### Koffi 2.5.8 (2023-07-26)
 
 - Add more search paths for native Koffi modules
-- Add section [about bundling](start.md#bundling-koffi) to documentation
+- Add section [about bundling](start#bundling-koffi) to documentation
 
 #### Koffi 2.5.7 (2023-07-19)
 
@@ -255,7 +265,7 @@ Pre-built binaries don't work correctly in Koffi 2.5.13 to 2.5.15, skip those ve
 
 **New features:**
 
-- Support [union types](unions.md)
+- Support [union types](unions)
 
 **Other fixes:**
 
@@ -273,8 +283,8 @@ Pre-built binaries don't work correctly in Koffi 2.5.13 to 2.5.15, skip those ve
 
 **Main changes:**
 
-- Support [decoding function pointers](functions.md#decode-pointer-to-function) to callable functions
-- Support calling function pointers with [koffi.call()](functions.md#call-pointer-directly)
+- Support [decoding function pointers](functions#decode-pointer-to-function) to callable functions
+- Support calling function pointers with [koffi.call()](functions#call-pointer-directly)
 - Deprecate `koffi.callback` in favor of `koffi.proto`
 
 **Other changes:**
@@ -384,9 +394,9 @@ Pre-built binaries don't work correctly in Koffi 2.5.13 to 2.5.15, skip those ve
 
 **Main changes:**
 
-- Fix type parser issues (such as ignoring some [disposable qualifiers](pointers.md#disposable-types))
+- Fix type parser issues (such as ignoring some [disposable qualifiers](pointers#disposable-types))
 - Fix crash when using disposable types in output parameters
-- Add basic [koffi.stats()](misc.md#usage-statistics) interface
+- Add basic [koffi.stats()](misc#usage-statistics) interface
 
 **Other changes:**
 
@@ -404,8 +414,8 @@ Pre-built binaries don't work correctly in Koffi 2.5.13 to 2.5.15, skip those ve
 **Main changes:**
 
 - Allow buffers (TypedArray or ArrayBuffer) values for input and/or output pointer arguments (for polymorphic arguments)
-- Support opaque buffers (TypedArray or ArrayBuffer) values in `koffi.decode()` to [decode output buffers](output.md#output-buffers)
-- Decode non-string types as arrays when an [explicit length is passed to koffi.decode()](callbacks.md#decoding-pointer-arguments)
+- Support opaque buffers (TypedArray or ArrayBuffer) values in `koffi.decode()` to [decode output buffers](output#output-buffers)
+- Decode non-string types as arrays when an [explicit length is passed to koffi.decode()](callbacks#decoding-pointer-arguments)
 
 **Other changes:**
 
@@ -436,7 +446,7 @@ Pre-built binaries don't work correctly in Koffi 2.5.13 to 2.5.15, skip those ve
 
 **Main fixes:**
 
-- Support transparent [asynchronous callbacks](callbacks.md#asynchronous-callbacks)
+- Support transparent [asynchronous callbacks](callbacks#asynchronous-callbacks)
 - Expand from a maximum of 16+16 to 1024 callbacks running in parallel
 
 **Other fixes:**
@@ -454,8 +464,8 @@ Pre-built binaries don't work correctly in Koffi 2.5.13 to 2.5.15, skip those ve
 
 **New features:**
 
-- Add [koffi.decode()](callbacks.md#decoding-pointer-arguments) for callback pointer arguments
-- Support transparent [output string parameters](output.md#string-buffer-example)
+- Add [koffi.decode()](callbacks#decoding-pointer-arguments) for callback pointer arguments
+- Support transparent [output string parameters](output#string-buffer-example)
 - Add `koffi.offsetof()` utility function
 - Support optional *this* binding in `koffi.register()`
 
@@ -468,7 +478,7 @@ Pre-built binaries don't work correctly in Koffi 2.5.13 to 2.5.15, skip those ve
 
 #### Koffi 2.1.5 (2022-11-27)
 
-- Add missing README.md file to NPM package
+- Add missing README file to NPM package
 
 #### Koffi 2.1.4 (2022-11-25)
 
@@ -497,8 +507,8 @@ Pre-built binaries don't work correctly in Koffi 2.5.13 to 2.5.15, skip those ve
 
 **Main changes:**
 
-- Add [koffi.as()](pointers.md#handling-void-pointers) to support polymorphic APIs based on `void *` parameters
-- Add [endian-sensitive integer types](input.md#endian-sensitive-integers): `intX_le_t`, `intX_be_t`, `uintX_le_t`, `uintX_be_t`
+- Add [koffi.as()](pointers#handling-void-pointers) to support polymorphic APIs based on `void *` parameters
+- Add [endian-sensitive integer types](input#endian-sensitive-integers): `intX_le_t`, `intX_be_t`, `uintX_le_t`, `uintX_be_t`
 - Accept typed arrays for `void *` parameters
 - Introduce `koffi.opaque()` to replace `koffi.handle()` (which remains supported until Koffi 3.0)
 - Support JS Array and TypedArray to fill struct and array pointer members
@@ -521,8 +531,8 @@ Pre-built binaries don't work correctly in Koffi 2.5.13 to 2.5.15, skip those ve
 
 **Major new features:**
 
-- Add [disposable types](pointers.md#disposable-types) for automatic disposal of C values (such as heap-allocated strings)
-- Add support for [registered callbacks](callbacks.md#registered-callbacks), that can be called after the initial FFI call
+- Add [disposable types](pointers#disposable-types) for automatic disposal of C values (such as heap-allocated strings)
+- Add support for [registered callbacks](callbacks#registered-callbacks), that can be called after the initial FFI call
 - Support named pointer types
 - Support complex type specifications outside of prototype parser
 
@@ -539,7 +549,9 @@ Pre-built binaries don't work correctly in Koffi 2.5.13 to 2.5.15, skip those ve
 - Change handling of opaque handles, which must be used through pointers
 - Support all types in `koffi.introspect(type)`
 
-Consult the [migration guide](migration.md) for more information.
+Consult the [migration guide](migration) for more information.
+
+## Koffi 1
 
 ### Koffi 1.3
 
@@ -691,13 +703,14 @@ This entry documents changes since version 1.1.0.
 - Make sure we have a redzone below the stack for all architectures
 - Use slower allocation for big objects instead of failing
 
-## Todo list
+# Todo list
 
 The following features and improvements are planned, not necessarily in that order:
 
+- Port Koffi to Loong64 ISA and ABI
+- Port Koffi to PowerPC (POWER9+) ISA and ABI
 - Optimize passing of structs and arrays (with auto-generated JS)
 - Automate Windows/AArch64 (qemu) and macOS/AArch64 (how? ... thanks Apple) tests
 - Create a real-world example, using several libraries (Raylib, SQLite, libsodium) to illustrate various C API styles
 - Add simple struct type parser
-- Port Koffi to PowerPC (POWER9+) ABI
 - Fix assembly unwind and CFI directives for better debugging experience

package/doc/README.md

@@ -0,0 +1,27 @@
+# Install required dependencies
+
+On Debian and Ubuntu use the following commands:
+
+```sh
+sudo apt update
+sudo apt install build-essential
+```
+
+On RPM-based distributions such as Fedora or Rocky Linux, use:
+
+```sh
+sudo dnf groupinstall "Development Tools"
+sudo dnf install clang
+```
+
+# Run the develop script
+
+Run the development script from the website directory:
+
+```sh
+./develop.sh
+```
+
+Open the proposed link at `http://localhost:8000/`.
+
+Change page content at will and builds will happen automatically. You just need to refresh the page.

package/doc/assets.ini

@@ -0,0 +1,19 @@
+EsbuildPath = ../../vendor/esbuild/bin
+
+[favicon.png]
+Type = Copy
+From = static/koffi.png
+
+[static]
+Type = Copy
+From = static
+Ignore = favicon.png *.js *.css
+
+[static/site.min.js]
+Type = Bundle
+Source = static/koffi.js
+
+[static/site.min.css]
+Type = Bundle
+Source = static/koffi.css
+Options = --loader:.woff=file --loader:.woff2=file --loader:.png=file --loader:.webp=file

package/doc/develop.sh

@@ -0,0 +1,14 @@
+#!/bin/bash -e
+
+cd "$(dirname $0)"
+
+../../bootstrap.sh
+../../felix -pFast serf hodler
+
+trap 'kill $(jobs -p) 2>/dev/null' EXIT
+trap 'kill $(jobs -p) 2>/dev/null' SIGINT
+
+../../bin/Fast/serf dist/ &
+../../bin/Fast/hodler . -O dist --loop &
+
+wait $(jobs -p)

package/doc/flaat/flaat.css

@@ -0,0 +1,25 @@
+/* Copyright (C) 2024  Niels Martignène <niels.martignene@protonmail.com>
+
+   Permission is hereby granted, free of charge, to any person obtaining a copy of
+   this software and associated documentation files (the “Software”), to deal in
+   the Software without restriction, including without limitation the rights to use,
+   copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+   Software, and to permit persons to whom the Software is furnished to do so,
+   subject to the following conditions:
+
+   The above copyright notice and this permission notice shall be included in all
+   copies or substantial portions of the Software.
+
+   THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
+   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+   OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+   NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+   HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+   WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+   FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+   OTHER DEALINGS IN THE SOFTWARE. */
+
+@import url('../../../vendor/opensans/OpenSans.css');
+@import url('./normal.css');
+@import url('./small.css');
+@import url('./print.css');

package/doc/flaat/flaat.js

@@ -0,0 +1,150 @@
+// Copyright (C) 2024  Niels Martignène <niels.martignene@protonmail.com>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+window.addEventListener('load', e => {
+    initDeploy();
+    initMenu();
+    initSide();
+    initScroll();
+
+    document.documentElement.classList.remove('nojs');
+    document.documentElement.classList.add('js');
+});
+
+function initDeploy() {
+    let deploy = document.querySelector('#deploy');
+
+    deploy.addEventListener('click', e => {
+        let top = document.querySelector('nav#top');
+        top.classList.toggle('active');
+    });
+}
+
+function initMenu() {
+    let items = document.querySelectorAll('nav#top li');
+
+    document.body.addEventListener('click', e => {
+        if (e.target.tagName == 'DIV' && findParent(e.target, el => el.id == 'top'))
+            return;
+
+        // Expand top menu categories
+        {
+            let target = findParent(e.target, el => el.tagName == 'LI');
+
+            if (target?.querySelector('div') != null) {
+                for (let item of items) {
+                    if (item == target) {
+                        item.classList.toggle('active');
+                    } else {
+                        item.classList.remove('active');
+                    }
+                }
+            }
+        }
+
+        if (e.target.tagName == 'A' && e.target.getAttribute('href') == '#')
+            e.preventDefault();
+    });
+}
+
+function initSide() {
+    // Find all side menu items, and the pointed to elements
+    let links = [].slice.call(document.querySelectorAll('nav#side a'));
+    let items = [].slice.call(links).map(link => {
+        let anchor = document.querySelector(link.getAttribute('href'));
+        return [link, anchor];
+    });
+    if (!items.length)
+        return;
+
+    let pending_request = false;
+    let active_idx = null;
+    function highlight(idx) {
+        if (pending_request)
+            return;
+
+        window.requestAnimationFrame(() => {
+            pending_request = false;
+
+            if (idx !== active_idx) {
+                if (active_idx !== null)
+                    items[active_idx][0].classList.remove('active');
+                items[idx][0].classList.add('active');
+                active_idx = idx;
+            }
+        });
+        pending_request = true;
+    }
+
+    // Event handlers, for clicks
+    let ignore_scroll = false;
+    function highlightOnClick(idx) {
+        highlight(idx);
+        setTimeout(() => { ignore_scroll = false; }, 50);
+        ignore_scroll = true;
+    }
+    function highlightOnScroll() {
+        if (ignore_scroll)
+            return;
+
+        let idx;
+        for (idx = 0; idx < items.length; idx++) {
+            let rect = items[idx][1].getBoundingClientRect();
+            if (rect.top >= 50)
+                break;
+        }
+        if (idx)
+            idx--;
+
+        highlight(idx);
+    }
+
+    // The scroll handler is not enough because it does not work for
+    // small sections at the end of the page.
+    for (let i = 0; i < items.length; i++) {
+        items[i][0].addEventListener('click', highlightOnClick.bind(this, i));
+    }
+
+    // Enable only on big screens, when the side menu is fixed
+    let mql = window.matchMedia('(min-width: 801px)');
+    if (mql.matches) {
+        window.addEventListener('scroll', highlightOnScroll);
+        highlightOnScroll();
+    }
+    mql.addListener(mql => {
+        if (mql.matches) {
+            window.addEventListener('scroll', highlightOnScroll);
+            highlightOnScroll();
+        } else {
+            window.removeEventListener('scroll', highlightOnScroll);
+        }
+    });
+}
+
+function initScroll() {
+    window.addEventListener('scroll', adjust_top);
+    adjust_top();
+
+    function adjust_top() {
+        let top = document.querySelector('nav#top');
+        top.classList.toggle('border', window.pageYOffset >= 20);
+    }
+}
+
+function findParent(el, func) {
+    while (el && !func(el))
+        el = el.parentElement;
+    return el;
+}