koffi 2.5.7 → 2.5.9

package/CHANGELOG.md

@@ -4,54 +4,51 @@
 
 ### Koffi 2.5
 
-#### Koffi 2.5.7
+#### 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
+
 - 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
 
@@ -70,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
@@ -97,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
 
@@ -172,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
 
@@ -216,8 +179,6 @@
 
 #### Koffi 2.3.4
 
-**Main fixes:**
-
 - Fix error when installing Koffi on Windows (2.3.2)
 
 #### Koffi 2.3.2
@@ -235,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
@@ -262,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
@@ -302,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
@@ -324,8 +269,6 @@
 
 #### Koffi 2.1.5
 
-**Main fixes:**
-
 - Add missing README.md file to NPM package
 
 #### Koffi 2.1.4
@@ -341,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
@@ -379,8 +316,6 @@
 
 #### Koffi 2.0.1
 
-**Main changes:**
-
 - Return `undefined` (instead of null) for `void` functions
 
 #### Koffi 2.0.0
@@ -411,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
@@ -435,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
@@ -489,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
@@ -507,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
@@ -538,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
@@ -577,11 +496,9 @@ This entry documents changes since version 1.1.0.
 
 The following features and improvements are planned, not necessarily in that order:
 
-- Optimize passing of structs and arrays (avoid setting named properties one by one? separate HFA-specific helper functions?)
+- 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
-- Add more ways to manually encode and decode various types to and from byte arrays
-- Add support for unions
 - Port Koffi to PowerPC (POWER9+) ABI
 - Fix assembly unwind and CFI directives for better debugging experience

package/doc/conf.py

@@ -56,22 +56,29 @@ html_static_path = ['static']
 
 html_theme_options = {
     'light_css_variables': {
-        'color-brand-primary': '#FF6600',
-        'color-brand-content': '#FF6600'
+        'font-stack': 'Open Sans',
+        'color-content-foreground': '#383838',
+        'color-brand-primary': '#383838',
+        'color-brand-content': '#e97713'
     },
     'dark_css_variables': {
-        'color-brand-primary': '#FF6600',
-        'color-brand-content': '#FF6600'
+        'font-stack': 'Open Sans',
+        'color-content-foreground': '#ffffffdd',
+        'color-brand-primary': '#ffffffdd',
+        'color-brand-content': '#e97713'
     }
 }
 
 html_link_suffix = ''
 
-html_css_files = ['custom.css']
+html_css_files = [
+    'opensans/OpenSans.css',
+    'custom.css'
+]
 
 html_sidebars = {
     "**": [
-        "sidebar/brand.html",
+        "logo.html",
         "sidebar/search.html",
         "sidebar/scroll-start.html",
         "sidebar/navigation.html",
@@ -105,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/contribute.md

@@ -2,9 +2,9 @@
 
 ## Bugs and feature requests
 
-Use the official repository (named Rygel, because this is a monorepo containing multiple projects) for bugs, ideas and features requests.
+Use the official repository for bugs, ideas and features requests: https://github.com/Koromix/koffi
 
-Go here: https://github.com/Koromix/rygel/
+Please note that the source code is not in this repository, instead it lives in a monorepo: https://github.com/Koromix/rygel/ (in the *src/koffi* subdirectory).
 
 ## Build from source
 

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/pyproject.toml

@@ -1,5 +1,5 @@
 [tool.poetry]
-name = "koffi"
+name = "koffi.dev"
 version = "0.1.0"
 description = ""
 authors = ["Niels Martignène <niels.martignene@protonmail.com>"]

package/doc/start.md

@@ -1,4 +1,4 @@
-# Quick start
+# Get started
 
 ## Install Koffi
 
@@ -18,12 +18,14 @@ const koffi = require('koffi');
 import koffi from 'koffi';
 ```
 
+## Simple examples
+
 Below you can find three examples:
 
 * The first one runs on Linux. The functions are declared with the C-like prototype language.
 * The second one runs on Windows, and uses the node-ffi like syntax to declare functions.
 
-## Small Linux example
+### For Linux
 
 This is a small example for Linux systems, which uses `gettimeofday()`, `localtime_r()` and `printf()` to print the current time.
 
@@ -74,7 +76,7 @@ printf('Hello World!\n');
 printf('Local time: %02d:%02d:%02d\n', 'int', now.tm_hour, 'int', now.tm_min, 'int', now.tm_sec);
 ```
 
-## Small Windows example
+### For Windows
 
 This is a small example targeting the Win32 API, using `MessageBox()` to show a *Hello World!* message to the user.
 
@@ -104,3 +106,7 @@ let ret = MessageBoxA(null, 'Do you want another message box?', 'Koffi', MB_YESN
 if (ret == IDYES)
     MessageBoxW(null, 'Hello World!', 'Koffi', MB_ICONINFORMATION);
 ```
+
+## Bundling Koffi
+
+Please read the [dedicated page](packaging.md) for information about bundling and packaging applications using Koffi.

package/doc/static/custom.css

@@ -23,8 +23,48 @@ aside.footnote {
     display: flex;
     margin-top: 6px;
 }
-
 aside.footnote > p {
     margin: 0;
     margin-left: 1rem;
 }
+
+.toctree-l1 > a {
+    font-size: 1.1em;
+}
+
+h1 {
+    font-size: 2rem;
+    text-transform: uppercase;
+    font-weight: normal;
+    margin-bottom: 1.2rem;
+}
+
+h2 {
+    display: table;
+    margin-left: 0;
+    margin-bottom: 1.2rem;
+    padding: 3px 12px 3px 30px;
+    background: var(--color-brand-primary) !important;
+    border-right: 32px solid var(--color-background-primary);
+    border-radius: 0;
+    font-size: 1.6rem;
+    font-weight: normal;
+    text-transform: uppercase;
+    color: var(--color-background-primary) !important;
+    position: relative;
+}
+h2 > a {
+    filter: none !important;
+    position: absolute;
+    left: calc(100% - 32px);
+}
+
+h3 {
+    font-size: 1.4rem;
+    font-weight: normal;
+    margin-bottom: 1.2rem;
+    font-style: italic;
+    padding-left: 50px;
+}
+
+:target > h1, :target > h3 { background: none !important; }