koffi 1.3.11 → 2.0.1

package/CMakeLists.txt

@@ -113,8 +113,13 @@ endif()
 if(NOT MSVC OR CMAKE_C_COMPILER_ID MATCHES "[Cc]lang")
     # Restore C/C++ compiler sanity
 
-    target_compile_options(koffi PRIVATE -fno-exceptions -fno-strict-aliasing -fwrapv
-                                         -fno-delete-null-pointer-checks)
+    if(NOT MSVC)
+        target_compile_options(koffi PRIVATE -fno-exceptions -fno-strict-aliasing -fwrapv
+                                             -fno-delete-null-pointer-checks)
+    else()
+        target_compile_options(koffi PRIVATE -fno-strict-aliasing /clang:-fwrapv
+                                             -fno-delete-null-pointer-checks)
+    endif()
 
     check_cxx_compiler_flag(-fno-finite-loops use_no_finite_loops)
     if(use_no_finite_loops)

package/ChangeLog.md

@@ -1,12 +1,50 @@
 # Changelog
 
-## Koffi 1.3.11
+## History
+
+### Koffi 2.0.1
+
+**Main changes:**
+
+- Return `undefined` (instead of null) for `void` functions
+
+### Koffi 2.0.0
+
+**Major new features:**
+
+- Add [disposable types](functions.md#heap-allocated-values) for automatic disposal of C values (such as heap-allocated strings)
+- Add support for [registered callbacks](functions.md#registered-callbacks), that can be called after the initial FFI call
+- Support named pointer types
+- Support complex type specifications outside of prototype parser
+
+**Minor new features:**
+
+- Support type aliases with `koffi.alias()`
+- Add `koffi.resolve()` to resolve type strings
+- Expose all primitive type aliases in `koffi.types`
+- Correctly pass exceptions thrown in JS callbacks
+
+**Breaking API changes:**
+
+- Change handling of callback types, which must be used through pointers
+- Change handling of opaque handles, which must be used through pointers
+- Support all types in `koffi.introspect(type)`
+
+Consult the [migration guide](changes.md#migration-guide) for more information.
+
+### Koffi 1.3.12
+
+**Main fixes:**
+
+- Fix support for Yarn package manager
+
+### Koffi 1.3.11
 
 **Main fixes:**
 
 - Fix broken parsing of `void *` when used for first parameter
 
-## Koffi 1.3.10
+### Koffi 1.3.10
 
 **Main fixes:**
 
@@ -18,13 +56,13 @@
 
 - Various documentation fixes and improvements
 
-## Koffi 1.3.9
+### Koffi 1.3.9
 
 **Main fixes:**
 
 - Fix prebuild compatibility with Electron on Windows x64
 
-## Koffi 1.3.8
+### Koffi 1.3.8
 
 **Main changes:**
 
@@ -35,7 +73,7 @@
 
 - Fix and harmonize a few error messages
 
-## Koffi 1.3.7
+### Koffi 1.3.7
 
 **Main fixes:**
 
@@ -48,7 +86,7 @@
 - Add str/str16 type aliases for string/string16
 - Various documentation fixes and improvements
 
-## Koffi 1.3.6
+### Koffi 1.3.6
 
 **Main fixes:**
 
@@ -60,7 +98,7 @@
 - Prebuild with Clang for Windows x64 and Linux x64 binaries
 - Various documentation improvements
 
-## Koffi 1.3.5
+### Koffi 1.3.5
 
 **Main changes:**
 
@@ -72,13 +110,13 @@
 - Reduce default async memory stack and heap size
 - Various documentation improvements
 
-## Koffi 1.3.4
+### Koffi 1.3.4
 
 **Main fixes:**
 
 - Fix possible OpenBSD i386 crash with `(void)` functions
 
-## Koffi 1.3.3
+### Koffi 1.3.3
 
 **Main fixes:**
 
@@ -90,20 +128,20 @@
 - Disable unsafe compiler optimizations
 - Various documentation improvements
 
-## Koffi 1.3.2
+### Koffi 1.3.2
 
 **Main fixes:**
 
 - Support compilation in C++14 mode (graceful degradation)
 - Support older toolchains on Linux (tested on Debian 9)
 
-## Koffi 1.3.1
+### Koffi 1.3.1
 
 **Main fixes:**
 
 - The prebuilt binary is tested when Koffi is installed, and a rebuild happens if it fails to load
 
-## Koffi 1.3.0
+### Koffi 1.3.0
 
 **Major changes:**
 
@@ -119,19 +157,19 @@
 - Detect floating-point ABI before using prebuilt binaries (ARM32, RISC-V)
 - Forbid duplicate member names in struct types
 
-## Koffi 1.2.4
+### Koffi 1.2.4
 
 **New features:**
 
 - Windows ARM64 is now supported
 
-## Koffi 1.2.3
+### Koffi 1.2.3
 
 **New features:**
 
 - A prebuilt binary for macOS ARM64 (M1) is now included
 
-## Koffi 1.2.1
+### Koffi 1.2.1
 
 This entry documents changes since version 1.1.0.
 

package/README.md

@@ -23,6 +23,12 @@ RISC-V 64 [^3]     | ⬜️ *N/A*    | ✅ Yes   | ⬜️ *N/A*    | 🟨 Probab
 
 Go to the web site for more information: https://koffi.dev/
 
+# Project history
+
+You can consult the [changelog](https://koffi.dev/changes) on the official website.
+
+Major version increments can include breaking API changes, use the [migration guide](https://koffi.dev/changes#migration-guide) for more information.
+
 # License
 
 This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

package/doc/changes.md

@@ -1,2 +1,157 @@
 ```{include} ../ChangeLog.md
-```
+```
+
+## Migration guide
+
+### Koffi 1.x to 2.x
+
+The API was changed in 2.x in a few ways, in order to reduce some excessively "magic" behavior and reduce the syntax differences between C and the C-like prototypes.
+
+You may need to change your code if you use:
+
+- Callback functions
+- Opaque handles
+- `koffi.introspect()`
+
+#### Callback types
+
+In Koffi 1.x, callbacks were defined in a way that made them usable directly as parameter and return types, obscuring the underlying pointer. Now, you must use them through a pointer: `void CallIt(CallbackType func)` in Koffi 1.x becomes `void CallIt(CallbackType *func)` in version 2.0 and newer.
+
+Given the following C code:
+
+```c
+#include <string.h>
+
+int TransferToJS(const char *name, int age, int (*cb)(const char *str, int age))
+{
+    char buf[64];
+    snprintf(buf, sizeof(buf), "Hello %s!", str);
+    return cb(buf, age);
+}
+```
+
+The two versions below illustrate the API difference between Koffi 1.x and Koffi 2.x:
+
+```js
+// Koffi 1.x
+
+const TransferCallback = koffi.callback('int TransferCallback(const char *str, int age)');
+
+const TransferToJS = lib.func('TransferToJS', 'int', ['str', 'int', TransferCallback]);
+// Equivalent to: const TransferToJS = lib.func('int TransferToJS(str s, int x, TransferCallback cb)');
+
+let ret = TransferToJS('Niels', 27, (str, age) => {
+    console.log(str);
+    console.log('Your age is:', age);
+    return 42;
+});
+console.log(ret);
+```
+
+```js
+// Koffi 2.x
+
+const TransferCallback = koffi.callback('int TransferCallback(const char *str, int age)');
+
+const TransferToJS = lib.func('TransferToJS', 'int', ['str', 'int', koffi.pointer(TransferCallback)]);
+// Equivalent to: const TransferToJS = lib.func('int TransferToJS(str s, int x, TransferCallback *cb)');
+
+let ret = TransferToJS('Niels', 27, (str, age) => {
+    console.log(str);
+    console.log('Your age is:', age);
+    return 42;
+});
+console.log(ret);
+```
+
+Koffi 1.x only supported [transient callbacks](functions.md#javascript-callbacks), you must use Koffi 2.x for registered callbacks.
+
+#### Opaque handles
+
+In Koffi 1.x, opaque handles were defined in a way that made them usable directly as parameter and return types, obscuring the underlying pointer. Now, you must use them through a pointer, and use an array for output parameters.
+
+For functions that return handles or pass them by parameter:
+
+```js
+// Koffi 1.x
+
+const FILE = koffi.handle('FILE');
+const fopen = lib.func('fopen', 'FILE', ['str', 'str']);
+const fopen = lib.func('fclose', 'int', ['FILE']);
+
+let fp = fopen('EMPTY', 'wb');
+if (!fp)
+    throw new Error('Failed to open file');
+fclose(fp);
+```
+
+```js
+// Koffi 2.x
+
+const FILE = koffi.handle('FILE');
+const fopen = lib.func('fopen', 'FILE *', ['str', 'str']);
+const fopen = lib.func('fclose', 'int', ['FILE *']);
+
+let fp = fopen('EMPTY', 'wb');
+if (!fp)
+    throw new Error('Failed to open file');
+fclose(fp);
+```
+
+For functions that set opaque handles through output parameters (such as `sqlite3_open_v2`), you must now use a single element array as shown below:
+
+```js
+// Koffi 1.x
+
+const sqlite3 = koffi.handle('sqlite3');
+
+const sqlite3_open_v2 = lib.func('int sqlite3_open_v2(const char *, _Out_ sqlite3 *db, int, const char *)');
+const sqlite3_close_v2 = lib.func('int sqlite3_close_v2(sqlite3 db)');
+
+const SQLITE_OPEN_READWRITE = 0x2;
+const SQLITE_OPEN_CREATE = 0x4;
+
+let db = {};
+
+if (sqlite3_open_v2(':memory:', db, SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE, null) != 0)
+    throw new Error('Failed to open database');
+
+sqlite3_close_v2(db);
+```
+
+```js
+// Koffi 2.x
+
+const sqlite3 = koffi.handle('sqlite3');
+
+const sqlite3_open_v2 = lib.func('int sqlite3_open_v2(const char *, _Out_ sqlite3 **db, int, const char *)');
+const sqlite3_close_v2 = lib.func('int sqlite3_close_v2(sqlite3 *db)');
+
+const SQLITE_OPEN_READWRITE = 0x2;
+const SQLITE_OPEN_CREATE = 0x4;
+
+let db = null;
+
+let ptr = [null];
+if (sqlite3_open_v2(':memory:', ptr, SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE, null) != 0)
+    throw new Error('Failed to open database');
+db = ptr[0];
+
+sqlite3_close_v2(db);
+```
+
+#### koffi.introspect()
+
+In Koffi 1.x, `koffi.introspect()` would only work with struct types, and return the object passed to `koffi.struct()` to initialize the type. Now this function works with all types.
+
+You can still get the list of struct members:
+
+```js
+const StructType = koffi.struct('StructType', { dummy: 'int' });
+
+// Koffi 1.x
+let members = koffi.introspect(StructType);
+
+// Koffi 2.x
+let members = koffi.introspect(StructType).members;
+```

package/doc/conf.py

@@ -21,7 +21,7 @@ extensions = [
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ['templates']
 
 exclude_patterns = []
 
@@ -48,6 +48,19 @@ html_link_suffix = ''
 
 html_css_files = ['custom.css']
 
+html_sidebars = {
+    "**": [
+        "sidebar/brand.html",
+        "sidebar/search.html",
+        "sidebar/scroll-start.html",
+        "sidebar/navigation.html",
+        "sidebar/ethical-ads.html",
+        "badges.html",
+        "sidebar/scroll-end.html",
+        "sidebar/variant-selector.html"
+    ]
+}
+
 # -- MyST parser options -------------------------------------------------
 
 myst_enable_extensions = [

package/doc/contribute.md

@@ -111,7 +111,6 @@ node qemu.js info debian_x64
 
 The following features and improvements are planned, not necessarily in that order:
 
-- Provide better ways to automatically deal with caller/heap-allocated memory (strings, etc.)
 - Optimize passing of structs and arrays (avoid setting named properties one by one? separate HFA-specific helper functions?)
 - 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

package/doc/dist/html/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 3958eced2fda3c6c0751ec1a88d416ca
+config: 176d11a9c5f53cb77e2388cfd78b9cee
 tags: 645f666f9bcd5a90fca523b33c5a78b7

package/doc/dist/html/_sources/benchmarks.md.txt

@@ -10,8 +10,8 @@ Here is a quick overview of the execution time of Koffi calls on three benchmark
 
 <table style="margin: 0 auto;">
     <tr>
-        <td><a href="static/perf_linux_20220628.png" target="_blank"><img src="static/perf_linux_20220628.png" alt="Linux x86_64 performance" style="width: 350px;"/></a></td>
-        <td><a href="static/perf_windows_20220628.png" target="_blank"><img src="static/perf_windows_20220628.png" alt="Windows x86_64 performance" style="width: 350px;"/></a></td>
+        <td><a href="_static/perf_linux_20220628.png" target="_blank"><img src="_static/perf_linux_20220628.png" alt="Linux x86_64 performance" style="width: 350px;"/></a></td>
+        <td><a href="_static/perf_windows_20220628.png" target="_blank"><img src="_static/perf_windows_20220628.png" alt="Windows x86_64 performance" style="width: 350px;"/></a></td>
     </tr>
 </table>
 

package/doc/dist/html/_sources/changes.md.txt

@@ -1,2 +1,157 @@
 ```{include} ../ChangeLog.md
-```
+```
+
+## Migration guide
+
+### Koffi 1.x to 2.x
+
+The API was changed in 2.x in a few ways, in order to reduce some excessively "magic" behavior and reduce the syntax differences between C and the C-like prototypes.
+
+You may need to change your code if you use:
+
+- Callback functions
+- Opaque handles
+- `koffi.introspect()`
+
+#### Callback types
+
+In Koffi 1.x, callbacks were defined in a way that made them usable directly as parameter and return types, obscuring the underlying pointer. Now, you must use them through a pointer: `void CallIt(CallbackType func)` in Koffi 1.x becomes `void CallIt(CallbackType *func)` in version 2.0 and newer.
+
+Given the following C code:
+
+```c
+#include <string.h>
+
+int TransferToJS(const char *name, int age, int (*cb)(const char *str, int age))
+{
+    char buf[64];
+    snprintf(buf, sizeof(buf), "Hello %s!", str);
+    return cb(buf, age);
+}
+```
+
+The two versions below illustrate the API difference between Koffi 1.x and Koffi 2.x:
+
+```js
+// Koffi 1.x
+
+const TransferCallback = koffi.callback('int TransferCallback(const char *str, int age)');
+
+const TransferToJS = lib.func('TransferToJS', 'int', ['str', 'int', TransferCallback]);
+// Equivalent to: const TransferToJS = lib.func('int TransferToJS(str s, int x, TransferCallback cb)');
+
+let ret = TransferToJS('Niels', 27, (str, age) => {
+    console.log(str);
+    console.log('Your age is:', age);
+    return 42;
+});
+console.log(ret);
+```
+
+```js
+// Koffi 2.x
+
+const TransferCallback = koffi.callback('int TransferCallback(const char *str, int age)');
+
+const TransferToJS = lib.func('TransferToJS', 'int', ['str', 'int', koffi.pointer(TransferCallback)]);
+// Equivalent to: const TransferToJS = lib.func('int TransferToJS(str s, int x, TransferCallback *cb)');
+
+let ret = TransferToJS('Niels', 27, (str, age) => {
+    console.log(str);
+    console.log('Your age is:', age);
+    return 42;
+});
+console.log(ret);
+```
+
+Koffi 1.x only supported [transient callbacks](functions.md#javascript-callbacks), you must use Koffi 2.x for registered callbacks.
+
+#### Opaque handles
+
+In Koffi 1.x, opaque handles were defined in a way that made them usable directly as parameter and return types, obscuring the underlying pointer. Now, you must use them through a pointer, and use an array for output parameters.
+
+For functions that return handles or pass them by parameter:
+
+```js
+// Koffi 1.x
+
+const FILE = koffi.handle('FILE');
+const fopen = lib.func('fopen', 'FILE', ['str', 'str']);
+const fopen = lib.func('fclose', 'int', ['FILE']);
+
+let fp = fopen('EMPTY', 'wb');
+if (!fp)
+    throw new Error('Failed to open file');
+fclose(fp);
+```
+
+```js
+// Koffi 2.x
+
+const FILE = koffi.handle('FILE');
+const fopen = lib.func('fopen', 'FILE *', ['str', 'str']);
+const fopen = lib.func('fclose', 'int', ['FILE *']);
+
+let fp = fopen('EMPTY', 'wb');
+if (!fp)
+    throw new Error('Failed to open file');
+fclose(fp);
+```
+
+For functions that set opaque handles through output parameters (such as `sqlite3_open_v2`), you must now use a single element array as shown below:
+
+```js
+// Koffi 1.x
+
+const sqlite3 = koffi.handle('sqlite3');
+
+const sqlite3_open_v2 = lib.func('int sqlite3_open_v2(const char *, _Out_ sqlite3 *db, int, const char *)');
+const sqlite3_close_v2 = lib.func('int sqlite3_close_v2(sqlite3 db)');
+
+const SQLITE_OPEN_READWRITE = 0x2;
+const SQLITE_OPEN_CREATE = 0x4;
+
+let db = {};
+
+if (sqlite3_open_v2(':memory:', db, SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE, null) != 0)
+    throw new Error('Failed to open database');
+
+sqlite3_close_v2(db);
+```
+
+```js
+// Koffi 2.x
+
+const sqlite3 = koffi.handle('sqlite3');
+
+const sqlite3_open_v2 = lib.func('int sqlite3_open_v2(const char *, _Out_ sqlite3 **db, int, const char *)');
+const sqlite3_close_v2 = lib.func('int sqlite3_close_v2(sqlite3 *db)');
+
+const SQLITE_OPEN_READWRITE = 0x2;
+const SQLITE_OPEN_CREATE = 0x4;
+
+let db = null;
+
+let ptr = [null];
+if (sqlite3_open_v2(':memory:', ptr, SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE, null) != 0)
+    throw new Error('Failed to open database');
+db = ptr[0];
+
+sqlite3_close_v2(db);
+```
+
+#### koffi.introspect()
+
+In Koffi 1.x, `koffi.introspect()` would only work with struct types, and return the object passed to `koffi.struct()` to initialize the type. Now this function works with all types.
+
+You can still get the list of struct members:
+
+```js
+const StructType = koffi.struct('StructType', { dummy: 'int' });
+
+// Koffi 1.x
+let members = koffi.introspect(StructType);
+
+// Koffi 2.x
+let members = koffi.introspect(StructType).members;
+```