koffi 2.5.8 → 2.5.9

package/CHANGELOG.md

@@ -4,61 +4,51 @@
 
 ### Koffi 2.5
 
-#### Koffi 2.5.8
+#### Koffi 2.5.9
 
 **Main changes:**
 
+- Use bundler-friendly static require calls in Koffi
+- Add packaging examples to documentation
+
+**Other changes:**
+
+- Add missing unload() export to TS file
+- Add export for koffi.types in TS file
+
+#### Koffi 2.5.8
+
 - Add more search paths for native Koffi modules
 - Add section [about bundling](start.md#bundling-koffi) to documentation
 
 #### Koffi 2.5.7
 
-**Main changes:**
-
 - Point package to new repository
 
 #### Koffi 2.5.6
 
-**Main changes:**
-
 - Increase limit of output parameters from 16 to 32
 
 #### Koffi 2.5.5
 
-**Main changes:**
-
 - Support decoding non-char null-terminated arrays
 
 #### Koffi 2.5.4
 
-**Main changes:**
-
 - Fix `koffi.pointer()` not accepting disposable types
-
-**Other changes:**
-
 - Fix potential issues when making pointers to anonymous types
 
 #### Koffi 2.5.3
 
-**Main changes:**
-
 - Add missing union exports in TS definition file
-
-**Other changes:**
-
 - Fix some parameter names in TS definition file
 
 #### Koffi 2.5.2
 
-**Main changes:**
-
 - Default initialize unset object/struct members
 
 #### Koffi 2.5.1
 
-**Main changes:**
-
 - Fix crash with some struct types in System V 64 ABI
 - Always use direct passthrough for buffer arguments
 
@@ -77,12 +67,7 @@
 
 #### Koffi 2.4.2
 
-**Main changes:**
-
 - Support calling variadic function pointers
-
-**Other changes:**
-
 - Add documentation for function pointers
 
 #### Koffi 2.4.1
@@ -104,64 +89,43 @@
 
 #### Koffi 2.3.20
 
-**Main fixes:**
-
 - Support explicit library unloading with `lib.unload()`
 
 #### Koffi 2.3.19
 
-**Main fixes:**
-
 - Actually allow non-ambiguous [string] values for `void *` arguments
 
 #### Koffi 2.3.18
 
-**Main fixes:**
-
 - Fix possible crash on exit caused by unregistered callbacks
 
 #### Koffi 2.3.17
 
-**Main changes:**
-
 - Allow strings for input `void *`, `int8_t *` and `int16_t *` pointer arguments
 - Support using `[string]` (single-element string arrays) for polymorphic input/output arguments
 
 #### Koffi 2.3.16
 
-**Main changes:**
-
 - Fix Windows ARM64 build to work with official Node.js version
 - Compile Windows builds with Visual Studio 2022 17.5.3
-
-**Other changes:**
-
 - Support null in `koffi.free()` and `koffi.address()`
 
 #### Koffi 2.3.15
 
-**Main changes:**
-
 - Improve manual decoding of 0-terminated strings
 - Add checks around array conversion hints
 
 #### Koffi 2.3.14
 
-**Main changes:**
-
 - Add `koffi.errno()` function to get and set current errno value
 - Add `koffi.os.errno` object with valid errno codes
 
 #### Koffi 2.3.13
 
-**Main changes:**
-
 - Add `koffi.address()` to get the raw value of a wrapper pointer
 
 #### Koffi 2.3.12
 
-**Main fixes:**
-
 - Fix broken syntax in TS definition file
 - Add missing exported properties in TS file
 
@@ -179,29 +143,21 @@
 
 #### Koffi 2.3.9
 
-**Main changes:**
-
 - Relicense under MIT license
 
 #### Koffi 2.3.8
 
-**Main fixes:**
-
 - Disable non-ready union support
 - Simplify Windows stack allocation and drop NOACCESS and GUARD pages
 - Adjust Windows TEB SEH chain and GuaranteedStackBytes for Koffi calls
 
 #### Koffi 2.3.7
 
-**Main fixes:**
-
 - Fix missing require in index.js ([@gastonFrecceroNapse](https://github.com/gastonFrecceroNapse))
 - Reduce NPM package bloat (from 65 MB to 20 MB) caused by changes in 2.3.6
 
 #### Koffi 2.3.6
 
-**Main changes:**
-
 - Fix broken TS definition file
 - Keep all prebuilt binaries and load correct one at runtime
 
@@ -223,8 +179,6 @@
 
 #### Koffi 2.3.4
 
-**Main fixes:**
-
 - Fix error when installing Koffi on Windows (2.3.2)
 
 #### Koffi 2.3.2
@@ -242,8 +196,6 @@
 
 #### Koffi 2.3.1
 
-**Main changes:**
-
 - Error out when trying to use ambiguous `void *` arguments (input and/or output)
 - Adjust TypeScript definitions ([@insraq](https://github.com/insraq))
 - Fix possible crash when parsing invalid prototype
@@ -269,28 +221,16 @@
 
 #### Koffi 2.2.5
 
-**Main changes:**
-
 - Relicense Koffi under LGPL 3.0
 
 #### Koffi 2.2.4
 
-**Main fixes:**
-
 - Fix memory leak on Windows (in Koffi 2.2.3) when running many async calls
-
-**Other changes:**
-
 - Reorganize documentation pages
 
 #### Koffi 2.2.3
 
-**Main fixes:**
-
 - Support native code that uses [Structured Exception Handling (SEH)](https://learn.microsoft.com/en-us/cpp/cpp/structured-exception-handling-c-cpp) on Windows (x86, x64 and ARM64)
-
-**Other changes:**
-
 - Try to use ebp/rbp as frame pointer in x86/x64 ASM code
 
 #### Koffi 2.2.2
@@ -309,8 +249,6 @@
 
 #### Koffi 2.2.1
 
-**Main fixes:**
-
 - Fix crash when [calling callback again after FFI call inside previous callback](https://github.com/Koromix/rygel/issues/15)
 
 #### Koffi 2.2.0
@@ -331,8 +269,6 @@
 
 #### Koffi 2.1.5
 
-**Main fixes:**
-
 - Add missing README.md file to NPM package
 
 #### Koffi 2.1.4
@@ -348,20 +284,14 @@
 
 #### Koffi 2.1.3
 
-**Main changes:**
-
 - Support up to 16 output parameters (instead of 8)
 
 #### Koffi 2.1.2
 
-**Main changes:**
-
 - Support up to 8 output parameters (instead of 4)
 
 #### Koffi 2.1.1
 
-**Main fixes:**
-
 - Fix potential memory allocation bugs
 
 #### Koffi 2.1.0
@@ -386,8 +316,6 @@
 
 #### Koffi 2.0.1
 
-**Main changes:**
-
 - Return `undefined` (instead of null) for `void` functions
 
 #### Koffi 2.0.0
@@ -418,14 +346,10 @@ Consult the [migration guide](migration.md) 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
@@ -442,8 +366,6 @@ Consult the [migration guide](migration.md) for more information.
 
 #### Koffi 1.3.9
 
-**Main fixes:**
-
 - Fix prebuild compatibility with Electron on Windows x64
 
 #### Koffi 1.3.8
@@ -496,8 +418,6 @@ Consult the [migration guide](migration.md) for more information.
 
 #### Koffi 1.3.4
 
-**Main fixes:**
-
 - Fix possible OpenBSD i386 crash with `(void)` functions
 
 #### Koffi 1.3.3
@@ -514,15 +434,11 @@ Consult the [migration guide](migration.md) for more information.
 
 #### 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
 
-**Main fixes:**
-
 - The prebuilt binary is tested when Koffi is installed, and a rebuild happens if it fails to load
 
 #### Koffi 1.3.0
@@ -545,14 +461,10 @@ Consult the [migration guide](migration.md) for more information.
 
 #### Koffi 1.2.4
 
-**New features:**
-
 - Windows ARM64 is now supported
 
 #### Koffi 1.2.3
 
-**New features:**
-
 - A prebuilt binary for macOS ARM64 (M1) is now included
 
 #### Koffi 1.2.1

package/doc/conf.py

@@ -112,5 +112,6 @@ myst_number_code_blocks = ['c', 'js', 'sh', 'batch']
 # -- Redirections -------------------------------------------------
 
 rediraffe_redirects = {
-    "changes.md": "changelog.md"
+    "changes.md": "changelog.md",
+    "bundling.md": "packaging.md"
 }

package/doc/index.rst

@@ -30,6 +30,7 @@ Table of contents
    parameters
    callbacks
    misc
+   packaging
    benchmarks
    contribute
    changelog

package/doc/packaging.md

@@ -0,0 +1,60 @@
+# Packaging
+
+## Bundling and native modules
+
+*Simplified in Koffi 2.5.9*
+
+Koffi uses native modules to work. The NPM package contains binaries for various platforms and architectures, and the appropriate module is selected at runtime.
+
+In theory, the bundlers should be able to find recorgnize all native modules because they are explictly listed in the Javascript file, as static strings.
+
+If that is not the case, you can manually arrange to copy the `node_modules/koffi/build/koffi` directory next to your bundled script.
+
+Here is an example that would work:
+
+```
+    koffi/
+        win32_x64/
+            koffi.node
+        linux_x64/
+            koffi.node
+        ...
+    MyBundle.js
+```
+
+When running in Electron, Koffi will also try to find the native module in `process.resourcesPath`. For an Electron app you could do something like this
+
+```
+    locales/
+    resources/
+        koffi/
+            darwin_arm64/
+                koffi.node
+            darwin_x64/
+                koffi.node
+    MyApp.exe
+```
+
+## Packaging examples
+
+### Electron with electron-builder
+
+Packaging with electron-builder should work as-is:
+
+You can also go take a look at the full [working example in the repository](https://github.com/Koromix/rygel/tree/master/src/koffi/examples/electron-builder).
+
+### Electron Forge
+
+Packaging with Electron Force should work as-is, even when using webpack as configured initially when you run:
+
+```sh
+npm init electron-app@latest my-app -- --template=webpack
+```
+
+You can also go take a look at the full [working example in the repository](https://github.com/Koromix/rygel/tree/master/src/koffi/examples/electron-forge).
+
+### NW.js
+
+Packagers such as nw-builder should work as-is.
+
+You can find a full [working example in the repository](https://github.com/Koromix/rygel/tree/master/src/koffi/examples/nwjs).

package/doc/start.md

@@ -109,39 +109,4 @@ if (ret == IDYES)
 
 ## Bundling Koffi
 
-*Improved in Koffi 2.5.8*
-
-Koffi uses native modules to work. The NPM package contains binaries for various platforms and architectures, and the appropriate module is selected at runtime.
-
-If you use a bundler, you must make sure that the {{ "`node_modules/koffi/build/" ~ stable ~ "`" }} directory is available in your bundled script.
-
-Here is an example that would work:
-
-```{eval-rst}
-.. parsed-literal::
-    koffi/
-        |version|/
-            win32_x64/
-                koffi.node
-            linux_x64/
-                koffi.node
-            ...
-    MyBundle.js
-```
-
-When running in Electron, Koffi will also try to find the native module in `process.resourcesPath`. For an Electron app you could do something like this
-
-```{eval-rst}
-.. parsed-literal::
-    locales/
-    resources/
-        koffi/
-            |version|/
-                darwin_arm64/
-                    koffi.node
-                darwin_x64/
-                    koffi.node
-    MyApp.exe
-```
-
-You must configure your bundler and/or your packager to make this work.
+Please read the [dedicated page](packaging.md) for information about bundling and packaging applications using Koffi.

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "koffi",
-    "version": "2.5.8",
-    "stable": "2.5.8",
+    "version": "2.5.9",
+    "stable": "2.5.9",
     "description": "Fast and simple C FFI (foreign function interface) for Node.js",
     "keywords": [
         "foreign",

package/src/cnoke/assets/FindCNoke.cmake

@@ -48,8 +48,12 @@ if(USE_UNITY_BUILDS)
         set(unity_file_cpp "${CMAKE_CURRENT_BINARY_DIR}/${TARGET}_unity.cpp")
         file(REMOVE ${unity_file_c} ${unity_file_cpp})
 
+        set(c_definitions "")
+        set(cpp_definitions "")
+
         foreach(src ${sources})
             get_source_file_property(language ${src} LANGUAGE)
+            get_property(definitions SOURCE ${src} PROPERTY COMPILE_DEFINITIONS)
             if(IS_ABSOLUTE ${src})
                 set(src_full ${src})
             else()
@@ -58,17 +62,29 @@ if(USE_UNITY_BUILDS)
             if(language STREQUAL "C")
                 set_source_files_properties(${src} PROPERTIES HEADER_FILE_ONLY 1)
                 file(APPEND ${unity_file_c} "#include \"${src_full}\"\n")
+                if (definitions)
+                    set(c_definitions "${c_definitions} ${definitions}")
+                endif()
             elseif(language STREQUAL "CXX")
                 set_source_files_properties(${src} PROPERTIES HEADER_FILE_ONLY 1)
                 file(APPEND ${unity_file_cpp} "#include \"${src_full}\"\n")
+                if (definitions)
+                    set(cpp_definitions "${cpp_definitions} ${definitions}")
+                endif()
             endif()
         endforeach()
 
         if(EXISTS ${unity_file_c})
             target_sources(${TARGET} PRIVATE ${unity_file_c})
+            if(c_definitions)
+                set_source_files_properties(${unity_file_c} PROPERTIES COMPILE_DEFINITIONS ${c_definitions})
+            endif()
         endif()
         if(EXISTS ${unity_file_cpp})
             target_sources(${TARGET} PRIVATE ${unity_file_cpp})
+            if(cpp_definitions)
+                set_source_files_properties(${unity_file_cpp} PROPERTIES COMPILE_DEFINITIONS ${cpp_definitions})
+            endif()
         endif()
 
         target_compile_definitions(${TARGET} PRIVATE -DUNITY_BUILD=1)

package/src/index.d.ts

@@ -79,6 +79,8 @@ declare module 'koffi' {
 
         thiscall(definition: string): KoffiFunction;
         thiscall(name: string, result: TypeSpec, arguments: TypeSpec[]): KoffiFunction;
+
+        unload(): void;
     }
 
     export function struct(name: string, def: Record<string, TypeSpecWithAlignment>): IKoffiCType;
@@ -149,4 +151,6 @@ declare module 'koffi' {
     export const os: {
         errno: Record<string, number>
     };
+
+    export const types: Record<string, IKoffiCType>;
 }

package/src/index.js

@@ -38,32 +38,61 @@ if (process.versions.napi == null || process.versions.napi < pkg.cnoke.napi) {
 }
 
 let arch = cnoke.determine_arch();
+let triplet = `${process.platform}_${arch}`;
 
-let filenames = [
-    __dirname + `/../build/${pkg.version}/${process.platform}_${arch}/koffi.node`,
-    __dirname + `/build/koffi/${pkg.version}/${process.platform}_${arch}/koffi.node`,
-    __dirname + `/koffi/${pkg.version}/${process.platform}_${arch}/koffi.node`,
-    __dirname + `/../build/${pkg.version}/koffi_${process.platform}_${arch}/koffi.node`,
-    __dirname + `/build/koffi/${pkg.version}/koffi_${process.platform}_${arch}/koffi.node`,
-    __dirname + `/koffi/${pkg.version}/koffi_${process.platform}_${arch}/koffi.node`
-];
+let native = null;
 
-if (process.resourcesPath != null) {
-    filenames.push(
-        process.resourcesPath + `/build/${pkg.version}/${process.platform}_${arch}/koffi.node`,
-        process.resourcesPath + `/build/koffi/${pkg.version}/${process.platform}_${arch}/koffi.node`,
-        process.resourcesPath + `/koffi/${pkg.version}/${process.platform}_${arch}/koffi.node`,
-        process.resourcesPath + `/build/${pkg.version}/koffi_${process.platform}_${arch}/koffi.node`,
-        process.resourcesPath + `/build/koffi/${pkg.version}/koffi_${process.platform}_${arch}/koffi.node`,
-        process.resourcesPath + `/koffi/${pkg.version}/koffi_${process.platform}_${arch}/koffi.node`
-    );
+// Try an explicit list with static strings to help bundlers
+try {
+    switch (triplet) {
+        case 'darwin_arm64': { native = require('../build/koffi/darwin_arm64/koffi.node'); } break;
+        case 'darwin_x64': { native = require('../build/koffi/darwin_x64/koffi.node'); } break;
+        case 'freebsd_arm46': { native = require('../build/koffi/freebsd_arm46/koffi.node'); } break;
+        case 'freebsd_ia32': { native = require('../build/koffi/freebsd_ia32/koffi.node'); } break;
+        case 'freebsd_x64': { native = require('../build/koffi/freebsd_x64/koffi.node'); } break;
+        case 'linux_arm32hf': { native = require('../build/koffi/linux_arm32hf/koffi.node'); } break;
+        case 'linux_arm64': { native = require('../build/koffi/linux_arm64/koffi.node'); } break;
+        case 'linux_ia32': { native = require('../build/koffi/linux_ia32/koffi.node'); } break;
+        case 'linux_risc64hf64': { native = require('../build/koffi/linux_risc64hf64/koffi.node'); } break;
+        case 'linux_x64': { native = require('../build/koffi/linux_x64/koffi.node'); } break;
+        case 'openbsd_ia32': { native = require('../build/koffi/openbsd_ia32/koffi.node'); } break;
+        case 'openbsd_x64': { native = require('../build/koffi/openbsd_x64/koffi.node'); } break;
+        case 'win32_arm64': { native = require('../build/koffi/win32_arm64/koffi.node'); } break;
+        case 'win32_ia32': { native = require('../build/koffi/win32_ia32/koffi.node'); } break;
+        case 'win32_x64': { native = require('../build/koffi/win32_x64/koffi.node'); } break;
+    }
+} catch (err) {
+    // Go on!
 }
 
-let filename = filenames.find(filename => fs.existsSync(filename));
-if (filename == null)
-    throw new Error('Cannot find the native Koffi module; did you bundle it correctly?');
+// And now, search everywhere we know
+if (native == null) {
+    let names = [
+        `/koffi/${process.platform}_${arch}/koffi.node`,
+        `/node_modules/koffi/build/koffi/${process.platform}_${arch}/koffi.node`
+    ];
+
+    for (let name of names) {
+        if (fs.existsSync(__dirname + name)) {
+            native = require(__dirname + name);
+            break;
+        }
+    }
 
-let native = require(filename);
+    if (native == null && process.resourcesPath != null) {
+        for (let name of names) {
+            if (fs.existsSync(process.resourcesPath + name)) {
+                native = require(process.resourcesPath + name);
+                break;
+            }
+        }
+    }
+}
+
+if (native == null)
+    throw new Error('Cannot find the native Koffi module; did you bundle it correctly?');
+if (native.version != pkg.version)
+    throw new Error('Mismatched native Koffi modules');
 
 module.exports = {
     ...native,

package/src/koffi/CMakeLists.txt

@@ -47,6 +47,12 @@ endif()
 
 # ---- Koffi ----
 
+file(READ ${CMAKE_CURRENT_SOURCE_DIR}/package.json PKG)
+string(REGEX MATCH "\"version\": \"([^\"]+)\"" XX "${PKG}")
+set(KOFFI_VERSION ${CMAKE_MATCH_1})
+
+set_source_files_properties(src/ffi.cc PROPERTIES COMPILE_DEFINITIONS VERSION=${KOFFI_VERSION})
+
 set(KOFFI_SRC
     src/call.cc
     src/ffi.cc

package/src/koffi/examples/electron-builder/README.md

@@ -0,0 +1,23 @@
+This is a simple example shows:
+
+- How to communicate with Koffi from a renderer window
+- How to use electron-builder with an application that uses Koffi
+
+One of the important piece for the packaging is in `package.json`, specifically this part:
+
+```json
+  "build": {
+    "extraResources": [
+      { "from": "node_modules/koffi/build", "to": "koffi" }
+    ]
+  }
+```
+
+This instructs electron-builder to copy the native koffi modules to a place where your application will find them.
+
+Use the following commands to package the app for your system:
+
+```sh
+npm install
+npm run dist
+```