native-dawn 0.1.0 → 0.1.2

package/CMakeLists.txt

@@ -77,6 +77,14 @@ if(NATIVE_DAWN_NODE)
     set_target_properties(dawn_node PROPERTIES INSTALL_RPATH "@loader_path" BUILD_WITH_INSTALL_RPATH ON)
   elseif(UNIX)
     set_target_properties(dawn_node PROPERTIES INSTALL_RPATH "$ORIGIN" BUILD_WITH_INSTALL_RPATH ON)
+  elseif(WIN32)
+    # Node-API is imported from node.exe. Delay-load it and resolve it to the
+    # module providing Node-API in the loading process (src/node/
+    # win_delay_load_hook.cc), so programs that embed Node under another name
+    # can load the addon too, as node-gyp addons do.
+    target_sources(dawn_node PRIVATE src/node/win_delay_load_hook.cc)
+    target_link_options(dawn_node PRIVATE "/DELAYLOAD:node.exe")
+    target_link_libraries(dawn_node PRIVATE delayimp)
   endif()
 
   # The addon sits next to the shared library: lib/ on Linux and macOS, bin/ on

package/README.md

@@ -5,7 +5,7 @@ Prebuilt [Dawn](https://dawn.googlesource.com/dawn), Google's WebGPU implementat
 - **Native code.** A shared `webgpu_dawn` library, the WebGPU C and C++ headers, and a CMake package, so a C or C++ program can use WebGPU without building Dawn.
 - **Node.js.** Dawn's own Node-API bindings, built against that same library, plus a swap chain for native windows.
 
-It is the WebGPU counterpart of [native-gles](https://github.com/monteslu/native-gles): the native layer, kept separate from the browser-style JavaScript API that sits on top of it (webgpu-node, as [webgl-node](https://github.com/monteslu/webgl-node) is for native-gles).
+It is the WebGPU counterpart of [native-gles](https://github.com/monteslu/native-gles): the native layer, kept separate from the browser-style JavaScript API that sits on top of it, [webgpu-node](https://github.com/monteslu/webgpu-node), as [webgl-node](https://github.com/monteslu/webgl-node) is for native-gles. If you want `navigator.gpu`, a canvas, or to run Three.js and other browser WebGPU code in Node, install webgpu-node; it depends on this package and installs it for you.
 
 Because the Node addon links the shared library instead of carrying its own copy of Dawn, JavaScript and native code in one process use the same Dawn. A `GPUDevice` created in JavaScript can be handed to a C++ addon as a `WGPUDevice`.
 
@@ -15,19 +15,29 @@ Because the Node addon links the shared library instead of carrying its own copy
 npm install native-dawn
 ```
 
-Installation downloads the archive for your platform from this repository's GitHub releases, checks its SHA-256 and version, and loads the addon once to make sure it works.
+Installation downloads the archive for your platform from this repository's GitHub releases, checks its SHA-256 and version, and loads the addon once to make sure it works. If that fails (an unsupported platform, no network, a C library too old for the binary), the install prints a warning and still succeeds, so packages that depend on native-dawn install everywhere; importing native-dawn then throws. A corrupt or mismatched archive is never installed. Set `NATIVE_DAWN_STRICT_INSTALL=1` to make install failures fatal.
 
 | Platform | Architectures | Backend |
 | --- | --- | --- |
-| Linux (glibc; release builds run on Ubuntu 22.04 and newer) | x64, arm64 | Vulkan |
+| Linux (glibc 2.34+: Ubuntu 22.04, Debian 12 and newer) | x64, arm64 | Vulkan |
 | macOS 11+ | x64, arm64 | Metal |
 | Windows | x64, arm64 | D3D12 |
 | Android 8.0+ (API 26), C SDK only | arm64 | Vulkan, OpenGL ES |
 
 Linux builds support X11 and Wayland windows and also include the OpenGL ES backend (see [OpenGL ES](#opengl-es-compatibility-mode)). The Node addon needs Node.js 22 or newer.
 
+The addon also loads into programs that embed Node, statically or as `libnode.dll`. On Linux and macOS it finds Node-API in the process that loads it. On Windows it delay-loads Node-API from `node.exe` and resolves that to the loading program, as node-gyp addons do, so a program under another name only has to export the Node-API functions.
+
 ## Using it from Node
 
+This package is the low-level layer: Dawn's WebGPU objects and a window swap chain. For the browser-style API (`navigator.gpu`, a canvas and `GPUCanvasContext`, `installGlobals()` for libraries such as Three.js, and SDL window presentation), use [webgpu-node](https://github.com/monteslu/webgpu-node) instead:
+
+```sh
+npm install webgpu-node   # installs native-dawn too
+```
+
+To use native-dawn directly:
+
 ```js
 import { create, globals } from 'native-dawn'
 
@@ -38,7 +48,7 @@ const device = await adapter.requestDevice()
 const buffer = device.createBuffer({ size: 16, usage: globals.GPUBufferUsage.COPY_DST | globals.GPUBufferUsage.MAP_READ })
 ```
 
-`gpu`, `adapter` and `device` are standard WebGPU objects. `globals` holds the WebGPU classes and constants (`GPUBufferUsage`, `GPUDevice`, `GPUValidationError`, ...). Nothing is installed on `globalThis` or `navigator`; webgpu-node does that, along with a canvas and `GPUCanvasContext`.
+`gpu`, `adapter` and `device` are standard WebGPU objects. `globals` holds the WebGPU classes and constants (`GPUBufferUsage`, `GPUDevice`, `GPUValidationError`, ...). Nothing is installed on `globalThis` or `navigator`; [webgpu-node](https://github.com/monteslu/webgpu-node) does that, along with a canvas and `GPUCanvasContext`.
 
 Adapters and devices stay valid even if the `gpu` object is garbage collected. Call `device.destroy()` when you are done to release GPU memory promptly. Only pending asynchronous work (a `mapAsync`, `onSubmittedWorkDone`, pipeline creation and the like) keeps Node running; an idle device does not, and it costs no CPU. Dawn notices a lost device (a driver reset, for example) on the next WebGPU call or asynchronous operation, and `device.lost` settles then.
 
@@ -229,6 +239,7 @@ Environment variables:
 | `NATIVE_DAWN_BUILD_FROM_SOURCE=1` | Make `npm install` build instead of downloading |
 | `NATIVE_DAWN_BINARY=/path/to/archive.tar.gz` | Install a local archive (with its `.sha256` beside it) |
 | `NATIVE_DAWN_SKIP_INSTALL=1` | Skip the install step entirely |
+| `NATIVE_DAWN_STRICT_INSTALL=1` | Fail `npm install` when no native build can be installed |
 
 ## Tests
 
@@ -246,7 +257,7 @@ Tests need a working adapter, hardware or software (Mesa's lavapipe on Linux, WA
 
 ## CI and releases
 
-[CI](.github/workflows/ci.yml) builds the six desktop targets on native runners and runs every suite above on each one, on Node 22 and 24, against the runner's software adapter. Linux also runs the C tests on OpenGL ES in compatibility mode. The window tests run everywhere except Windows ARM64, which has no @kmamal/sdl build. Android is cross-compiled on Linux and its C tests run on an x86_64 Android emulator, through Android's ARM translation.
+[CI](.github/workflows/ci.yml) builds the six desktop targets on native runners and runs every suite above on each one, on Node 22 and 24, against the runner's software adapter. Linux also runs the C tests on OpenGL ES in compatibility mode. The window tests run everywhere except Windows ARM64, which has no @kmamal/sdl build. On Windows, CI also checks that the addon delay-loads `node.exe` and resolves Node-API from a test program that is not `node.exe` (`npm run test:win-host`). Android is cross-compiled on Linux and its C tests run on an x86_64 Android emulator, through Android's ARM translation.
 
 Pushing a `v<version>` tag that matches `package.json` runs the same jobs, and if all seven pass, creates a GitHub release with the seven archives and their checksums. npm publishing is a separate, manual step after that, since `npm install` downloads from the release.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "native-dawn",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Prebuilt Dawn WebGPU for Node.js and native code: shared library, C headers, and Node-API bindings",
   "type": "module",
   "main": "index.js",
@@ -45,6 +45,7 @@
     "test:c": "node scripts/test-c.mjs",
     "test:window": "node test/window.mjs",
     "test:package": "node scripts/test-package.mjs",
+    "test:win-host": "node scripts/test-win-host.mjs",
     "package:binary": "node scripts/package-binary.mjs",
     "test:types": "tsc -p test/tsconfig.json",
     "test:android": "node scripts/test-android.mjs"

package/scripts/install.mjs

@@ -69,9 +69,14 @@ export async function install() {
   }
 }
 
+// A failed install leaves native-dawn without a native build but never fails
+// the surrounding npm install: packages that depend on it (webgpu-node, and
+// through it wasmcart) must still install on platforms native-dawn does not
+// cover, and only error when WebGPU is actually used. A bad archive is never
+// installed either way. NATIVE_DAWN_STRICT_INSTALL=1 makes failures fatal.
 try {
   await install()
 } catch (error) {
-  console.error(`native-dawn: ${error.message}\nTo build from source instead, install the toolchain in README.md and set NATIVE_DAWN_BUILD_FROM_SOURCE=1.`)
-  process.exitCode = 1
+  console.warn(`native-dawn: no native build installed: ${error.message}\nWebGPU will not be available on this machine; importing native-dawn will throw. To build from source, install the toolchain in README.md and set NATIVE_DAWN_BUILD_FROM_SOURCE=1.`)
+  if (process.env.NATIVE_DAWN_STRICT_INSTALL === '1') process.exitCode = 1
 }

package/scripts/pe.mjs

@@ -0,0 +1,73 @@
+// Reads the import, delay-load import and export tables of a Windows PE file
+// (PE32 or PE32+), for checks that must not depend on dumpbin's text format.
+import fs from 'node:fs'
+
+/**
+ * @param {string} file
+ * @returns {{ imports: Map<string, string[]>, delayImports: Map<string, string[]>, exports: string[] }}
+ *   DLL names are as written in the file; functions imported by ordinal are '#<n>'.
+ */
+export function readPe(file) {
+  const b = fs.readFileSync(file)
+  if (b.readUInt16LE(0) !== 0x5a4d) throw new Error(`${file}: not a PE file`)
+  const pe = b.readUInt32LE(0x3c)
+  if (b.readUInt32LE(pe) !== 0x4550) throw new Error(`${file}: no PE signature`)
+  const sectionCount = b.readUInt16LE(pe + 6)
+  const optional = pe + 24
+  const pe32plus = b.readUInt16LE(optional) === 0x20b
+  const dirs = optional + (pe32plus ? 112 : 96)
+  const dir = i => ({ rva: b.readUInt32LE(dirs + i * 8), size: b.readUInt32LE(dirs + i * 8 + 4) })
+  const sectionTable = optional + b.readUInt16LE(pe + 20)
+  const sections = []
+  for (let i = 0; i < sectionCount; i++) {
+    const s = sectionTable + i * 40
+    sections.push({ va: b.readUInt32LE(s + 12), vsize: Math.max(b.readUInt32LE(s + 8), b.readUInt32LE(s + 16)), raw: b.readUInt32LE(s + 20) })
+  }
+  const off = rva => {
+    const s = sections.find(s => rva >= s.va && rva < s.va + s.vsize)
+    if (!s) throw new Error(`${file}: RVA 0x${rva.toString(16)} is in no section`)
+    return rva - s.va + s.raw
+  }
+  const str = rva => { const o = off(rva); return b.toString('latin1', o, b.indexOf(0, o)) }
+  const thunkSize = pe32plus ? 8 : 4
+  const names = tableRva => {
+    const out = []
+    for (let o = off(tableRva); ; o += thunkSize) {
+      const t = pe32plus ? b.readBigUInt64LE(o) : BigInt(b.readUInt32LE(o))
+      if (t === 0n) break
+      const byOrdinal = pe32plus ? t >> 63n : t >> 31n
+      out.push(byOrdinal ? `#${Number(t & 0xffffn)}` : str(Number(t & 0x7fffffffn) + 2))
+    }
+    return out
+  }
+
+  const imports = new Map()
+  const imp = dir(1)
+  if (imp.rva) {
+    for (let o = off(imp.rva); b.readUInt32LE(o + 12); o += 20) {
+      imports.set(str(b.readUInt32LE(o + 12)), names(b.readUInt32LE(o) || b.readUInt32LE(o + 16)))
+    }
+  }
+  const delayImports = new Map()
+  const delay = dir(13)
+  if (delay.rva) {
+    for (let o = off(delay.rva); b.readUInt32LE(o + 4); o += 32) {
+      delayImports.set(str(b.readUInt32LE(o + 4)), names(b.readUInt32LE(o + 16)))
+    }
+  }
+  const exports = []
+  const exp = dir(0)
+  if (exp.rva) {
+    const o = off(exp.rva)
+    const count = b.readUInt32LE(o + 24)
+    const nameTable = off(b.readUInt32LE(o + 32))
+    for (let i = 0; i < count; i++) exports.push(str(b.readUInt32LE(nameTable + i * 4)))
+  }
+  return { imports, delayImports, exports }
+}
+
+/** The map key for a DLL name, matched case-insensitively as Windows does. */
+export function findDll(map, name) {
+  for (const [key, value] of map) if (key.toLowerCase() === name.toLowerCase()) return value
+  return null
+}

package/scripts/test-win-host.mjs

@@ -0,0 +1,75 @@
+// Windows: dawn.node loads into node.exe and into a program that only
+// exports Node-API (as one that embeds Node under another name does).
+//
+// 1. Its import table: Node-API comes from node.exe, delay-loaded, and nothing
+//    is imported from node.exe the ordinary way.
+// 2. node.exe loads it.
+// 3. A host built here (not node.exe, no Node in it) exports every function
+//    dawn.node takes from node.exe, each a stub that reports its name and ends
+//    the process. Calling the addon's napi_register_module_v1 makes its first
+//    Node-API call, which the delay-load hook must resolve to that host. Without
+//    the hook the delay-load helper looks for a node.exe file and the host dies
+//    with an exception (or reaches a node.exe on PATH, which is not the host).
+//
+// Run from an MSVC developer environment (cl.exe), after `npm run build`.
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { root, target, distDir, run } from './common.mjs'
+import { readPe, findDll } from './pe.mjs'
+
+if (!target.startsWith('win32-')) throw new Error(`test-win-host is for win32 targets, not ${target}`)
+const addon = path.join(distDir, 'bin', 'dawn.node')
+
+const { imports, delayImports } = readPe(addon)
+if (findDll(imports, 'node.exe')) throw new Error('dawn.node imports node.exe directly; it must be delay-loaded (/DELAYLOAD:node.exe)')
+const napi = findDll(delayImports, 'node.exe')
+if (!napi?.length) throw new Error(`dawn.node does not delay-load node.exe (delay-loaded: ${[...delayImports.keys()].join(', ') || 'nothing'})`)
+const bad = napi.filter(n => !/^(napi|node_api)_[a-z0-9_]+$/.test(n))
+if (bad.length) throw new Error(`dawn.node takes more than Node-API from node.exe: ${bad.join(', ')}`)
+console.log(`dawn.node delay-loads ${napi.length} Node-API functions from node.exe`)
+
+const node = spawnSync(process.execPath, ['-e', `
+  const dawn = require(${JSON.stringify(addon)});
+  if (typeof dawn.create !== 'function') throw new Error('dawn.node has no create()');
+`], { encoding: 'utf8' })
+if (node.status !== 0) throw new Error(`node.exe could not load dawn.node:\n${node.stdout}${node.stderr}`)
+console.log('node.exe loads dawn.node')
+
+const dir = path.join(root, 'build', 'win-host-test')
+fs.rmSync(dir, { recursive: true, force: true })
+fs.mkdirSync(dir, { recursive: true })
+fs.writeFileSync(path.join(dir, 'host.c'), `// Generated by scripts/test-win-host.mjs
+#define WIN32_LEAN_AND_MEAN
+#include <windows.h>
+#include <stdio.h>
+
+static void reached(const char* name) {
+  printf("first Node-API call resolved to the host: %s\\n", name);
+  fflush(stdout);
+  TerminateProcess(GetCurrentProcess(), 0);
+}
+${napi.map(n => `__declspec(dllexport) void* ${n}(void) { reached("${n}"); return 0; }`).join('\n')}
+
+typedef void* (*register_fn)(void* env, void* exports);
+
+int wmain(int argc, wchar_t** argv) {
+  if (argc != 2) return 2;
+  HMODULE addon = LoadLibraryExW(argv[1], NULL, LOAD_WITH_ALTERED_SEARCH_PATH);
+  if (!addon) { printf("LoadLibraryExW failed: %lu\\n", GetLastError()); return 1; }
+  register_fn reg = (register_fn)GetProcAddress(addon, "napi_register_module_v1");
+  if (!reg) { printf("no napi_register_module_v1\\n"); return 1; }
+  reg((void*)1, (void*)2);
+  printf("napi_register_module_v1 returned without calling Node-API\\n");
+  return 1;
+}
+`)
+run('cl', ['/nologo', '/W3', 'host.c', '/Fe:host.exe'], { cwd: dir })
+const host = spawnSync(path.join(dir, 'host.exe'), [addon], { encoding: 'utf8' })
+const out = `${host.stdout}${host.stderr}`
+if (host.status !== 0 || !out.includes('resolved to the host')) {
+  const code = host.status === null ? host.signal : `0x${(host.status >>> 0).toString(16)}`
+  throw new Error(`dawn.node did not resolve Node-API from a host that is not node.exe (exit ${code}):\n${out}`)
+}
+console.log(out.trim())
+fs.rmSync(dir, { recursive: true, force: true })

package/src/node/win_delay_load_hook.cc

@@ -0,0 +1,36 @@
+// Windows: lets dawn.node load into any program that exports Node-API, not
+// only one named node.exe.
+//
+// The addon's Node-API imports name the module node.exe (Dawn's generated
+// NapiSymbols.lib), and CMakeLists.txt links them with /DELAYLOAD:node.exe.
+// When the first one is resolved, this hook answers the load of node.exe with
+// the module that already provides Node-API in this process: libnode.dll when
+// a program embeds Node through it, otherwise the program itself (node.exe,
+// Electron, or an executable with libnode linked in that exports the
+// napi_* symbols). This is the mechanism node-gyp builds into every addon
+// (its win_delay_load_hook.cc).
+
+#ifdef _MSC_VER
+
+#ifndef WIN32_LEAN_AND_MEAN
+#define WIN32_LEAN_AND_MEAN
+#endif
+#include <windows.h>
+
+#include <delayimp.h>
+#include <string.h>
+
+static FARPROC WINAPI native_dawn_load_host(unsigned int event, DelayLoadInfo* info) {
+    if (event != dliNotePreLoadLibrary || _stricmp(info->szDll, "node.exe") != 0) {
+        return nullptr;
+    }
+    HMODULE host = GetModuleHandleA("libnode.dll");
+    if (host == nullptr) {
+        host = GetModuleHandleA(nullptr);
+    }
+    return reinterpret_cast<FARPROC>(host);
+}
+
+decltype(__pfnDliNotifyHook2) __pfnDliNotifyHook2 = native_dawn_load_host;
+
+#endif  // _MSC_VER