wstp-node 0.4.0 → 0.4.1

package/InstallationWindows.md

@@ -0,0 +1,171 @@
+# Building wstp-node on Windows
+
+This guide walks through compiling the native WSTP addon (`wstp.node`) on a
+Windows 10 / 11 x64 machine so that the
+[Wolfbook VS Code extension](https://github.com/vanbaalon/wolfbook) can use it
+without any build step on the end-user's machine.
+
+---
+
+## Prerequisites
+
+### 1. Wolfram Engine (or Mathematica)
+
+Download the free **Wolfram Engine** from:  
+https://wolfram.com/engine/
+
+Default installation path after setup:
+```
+C:\Program Files\Wolfram Research\Wolfram Engine\14.x\
+```
+
+Verify the WSTP DeveloperKit is present:
+```
+C:\Program Files\Wolfram Research\Wolfram Engine\14.x\SystemFiles\Links\WSTP\DeveloperKit\Windows-x86-64\CompilerAdditions\
+```
+The key files needed are `wstp64i4s.lib` and `wstp.h` inside that folder.
+
+> If your Wolfram version or install path differs, set the `WSTP_DIR` environment
+> variable to the `CompilerAdditions` folder before building:
+> ```powershell
+> $env:WSTP_DIR = "C:\Program Files\Wolfram Research\Wolfram Engine\14.x\SystemFiles\Links\WSTP\DeveloperKit\Windows-x86-64\CompilerAdditions"
+> ```
+
+---
+
+### 2. Visual Studio Build Tools (C++ compiler)
+
+Run the following in **PowerShell as Administrator**:
+
+```powershell
+winget install Microsoft.VisualStudio.2022.BuildTools
+```
+
+Then open **Visual Studio Installer** → **Modify** → select the
+**"Desktop development with C++"** workload.  Make sure these components
+are checked:
+
+- ✅ MSVC v143 – VS 2022 C++ x64/x86 build tools
+- ✅ Windows 11 SDK (or Windows 10 SDK)
+- ✅ C++ CMake tools (optional but useful)
+
+---
+
+### 3. Node.js ≥ 18 (LTS)
+
+```powershell
+winget install OpenJS.NodeJS.LTS
+```
+
+Restart your shell after installation, then verify:
+
+```powershell
+node --version   # 20.x or 22.x
+npm  --version
+```
+
+---
+
+### 4. Git
+
+```powershell
+winget install Git.Git
+```
+
+---
+
+## Build
+
+Open a **Developer PowerShell for VS 2022** (or a regular PowerShell — `node-gyp`
+finds MSVC automatically if the Build Tools are installed correctly).
+
+```powershell
+git clone https://github.com/vanbaalon/mathematica-wstp-node.git
+cd mathematica-wstp-node
+
+npm install
+npm run build
+```
+
+A successful build prints:
+```
+Build succeeded: build\Release\wstp.node
+```
+
+### Verify the build
+
+```powershell
+node -e "const {WstpSession}=require('./build/Release/wstp.node'); const s=new WstpSession(); s.evaluate('1+1').then(r=>{console.log(r.result.value); s.close()})"
+```
+Expected output: `2`
+
+---
+
+## Contributing the binary to the Wolfbook extension
+
+After building, copy the binary to the extension's `wstp/prebuilt/` folder and
+commit it so CI can package the Windows VSIX:
+
+```powershell
+# from inside the mathematica-wstp-node directory:
+copy build\Release\wstp.node ..\wolfbook\wstp\prebuilt\wstp-win32-x64.node
+```
+
+Then on macOS / Linux, run the deploy script to build both platform VSIXs:
+
+```bash
+bash deploy-extension.sh package
+```
+
+---
+
+## Setting up a self-hosted GitHub Actions runner (optional)
+
+If you want CI to build the Windows binary automatically on every release tag:
+
+**In your browser:** go to  
+`https://github.com/vanbaalon/mathematica-wstp-node` →  
+Settings → Actions → Runners → **New self-hosted runner** → Windows x64
+
+GitHub shows you a unique token and the exact download URL. Run those commands
+in **PowerShell as Administrator**:
+
+```powershell
+mkdir C:\actions-runner; cd C:\actions-runner
+
+# Replace the URL and token with what GitHub shows you:
+Invoke-WebRequest -Uri https://github.com/actions/runner/releases/download/v2.x.x/actions-runner-win-x64-2.x.x.zip -OutFile runner.zip
+Add-Type -AssemblyName System.IO.Compression.FileSystem
+[System.IO.Compression.ZipFile]::ExtractToDirectory("$PWD\runner.zip", "$PWD")
+
+.\config.cmd --url https://github.com/vanbaalon/mathematica-wstp-node --token YOUR_TOKEN_HERE
+
+# Install as a Windows service so it runs even when you are logged out:
+.\svc.cmd install
+.\svc.cmd start
+```
+
+Verify the runner is online: GitHub → Settings → Actions → Runners → green dot.
+
+Once both the macOS and Windows runners are registered, push a version tag from
+your Mac to trigger a full build:
+
+```bash
+git tag v0.5.0 && git push origin v0.5.0
+```
+
+The workflow builds both binaries and publishes them as assets on the
+`mathematica-wstp-node` GitHub Release. The `wolfbook` workflow then downloads
+those assets and packages the platform-specific VSIXs automatically.
+
+---
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| `gyp ERR! find VS` | Open Developer PowerShell for VS 2022, or run `npm config set msvs_version 2022` |
+| `LINK : fatal error LNK1181: cannot open input file 'wstp64i4s.lib'` | WSTP DeveloperKit not found — set `WSTP_DIR` (see Prerequisites) |
+| `node.exe` crashes on `require('./build/Release/wstp.node')` | Node.js architecture mismatch — ensure you installed 64-bit Node |
+| Runner shows offline | `cd C:\actions-runner && .\svc.cmd status`, then `.\svc.cmd start` |
+| `error MSB8036: The Windows SDK version X was not found` | Install the matching Windows SDK via Visual Studio Installer |

package/README.md

@@ -54,11 +54,16 @@ const { WstpSession, WstpReader, setDiagHandler } = require('./build/Release/wst
 
 | Requirement | Notes |
 |-------------|-------|
-| macOS | Tested on macOS 13+; Linux should work with minor path changes |
+| macOS | Tested on macOS 13+ (ARM64 and x86-64) |
+| Windows 10/11 x64 | See [InstallationWindows.md](InstallationWindows.md) for the full Windows guide |
+| Linux x86-64 / ARM64 | Should work with standard `node-gyp` toolchain |
 | Node.js ≥ 18 | Earlier versions may work but are untested |
-| Clang / Xcode Command Line Tools | `xcode-select --install` |
+| Clang / Xcode Command Line Tools (macOS) | `xcode-select --install` |
+| MSVC Build Tools with C++ workload (Windows) | Visual Studio 2019+ or Build Tools |
 | Wolfram Mathematica or Wolfram Engine | Provides `WolframKernel` and the WSTP SDK headers/libraries |
 
+> **Windows users:** follow [InstallationWindows.md](InstallationWindows.md) instead of the steps below.
+
 ### 1. Clone
 
 ```bash
@@ -92,7 +97,7 @@ The script automatically locates the WSTP SDK inside the default Wolfram install
 node test.js
 ```
 
-Expected last line: `All 28 tests passed.`
+Expected last line: `All 36 tests passed.`
 
 A more comprehensive suite (both modes + In/Out + comparison) lives in `tmp/tests_all.js`:
 

package/binding.gyp

@@ -1,8 +1,9 @@
 {
   "variables": {
-    # Detect arch: arm64 → MacOSX-ARM64, x86_64 → MacOSX-x86-64
-    # Override the whole path by setting WSTP_DIR in the environment.
-    "wstp_dir%": "<!(echo \"${WSTP_DIR:-/Applications/Wolfram 3.app/Contents/SystemFiles/Links/WSTP/DeveloperKit/$(uname -m | sed 's/x86_64/MacOSX-x86-64/;s/arm64/MacOSX-ARM64/')/CompilerAdditions}\")"
+    # Cross-platform WSTP DeveloperKit path.
+    # Override by setting WSTP_DIR in the environment.
+    # See scripts/wstp_dir.js for auto-detection logic.
+    "wstp_dir%": "<!@(node scripts/wstp_dir.js)"
   },
   "targets": [
     {
@@ -16,13 +17,9 @@
 
       "defines": ["NAPI_DISABLE_CPP_EXCEPTIONS"],
 
-      "libraries": [
-        # The static library ships as libWSTPi4.a in the macOS DeveloperKit.
-        "<(wstp_dir)/libWSTPi4.a"
-      ],
-
       "conditions": [
         ["OS=='mac'", {
+          "libraries": ["<(wstp_dir)/libWSTPi4.a"],
           "xcode_settings": {
             "GCC_ENABLE_CPP_EXCEPTIONS": "YES",
             "MACOSX_DEPLOYMENT_TARGET": "11.0",
@@ -37,8 +34,9 @@
           }
         }],
         ["OS=='linux'", {
+          "libraries": ["<(wstp_dir)/libWSTPi4.a"],
           "cflags_cc": ["-std=c++17", "-Wall", "-Wextra"],
-          "libraries": ["-lrt", "-lpthread", "-ldl", "-lm"]
+          "link_settings": { "libraries": ["-lrt", "-lpthread", "-ldl", "-lm"] }
         }],
         ["OS=='win'", {
           "msvs_settings": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wstp-node",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Native Node.js addon for Wolfram/Mathematica WSTP — kernel sessions with evaluation queue, streaming Print/messages, Dialog subsessions, and side-channel WstpReader",
   "main": "build/Release/wstp.node",
   "types": "index.d.ts",
@@ -20,16 +20,19 @@
   "license": "MIT",
   "os": [
     "darwin",
-    "linux"
+    "linux",
+    "win32"
   ],
   "engines": {
     "node": ">=18"
   },
   "files": [
     "src/addon.cc",
+    "scripts/wstp_dir.js",
     "build.sh",
     "binding.gyp",
     "index.d.ts",
+    "InstallationWindows.md",
     "examples/",
     "test.js",
     "test_interrupt_dialog.js"

package/scripts/wstp_dir.js

@@ -0,0 +1,78 @@
+/**
+ * wstp_dir.js
+ * Cross-platform helper used by binding.gyp to locate the WSTP DeveloperKit.
+ *
+ * Usage in binding.gyp:  "wstp_dir%": "<!@(node scripts/wstp_dir.js)"
+ *
+ * Precedence:
+ *   1. WSTP_DIR environment variable  (always wins)
+ *   2. Platform-specific auto-detect below
+ */
+
+'use strict';
+
+const path = require('path');
+const fs   = require('fs');
+
+function resolve () {
+  // ── 1. Explicit override ────────────────────────────────────────────────
+  if (process.env.WSTP_DIR) {
+    return process.env.WSTP_DIR;
+  }
+
+  // ── 2. Windows ──────────────────────────────────────────────────────────
+  if (process.platform === 'win32') {
+    const base = 'C:\\Program Files\\Wolfram Research\\Wolfram Engine';
+    let versions;
+    try {
+      versions = fs.readdirSync(base)
+        .filter(d => /^\d/.test(d))
+        .sort()
+        .reverse();
+    } catch (e) {
+      throw new Error(
+        `WSTP DeveloperKit not found at "${base}".\n` +
+        `Install Wolfram Engine or set WSTP_DIR to the CompilerAdditions folder.`
+      );
+    }
+    if (!versions.length) throw new Error(`No Wolfram Engine version found under "${base}"`);
+    return path.join(
+      base, versions[0],
+      'SystemFiles', 'Links', 'WSTP', 'DeveloperKit',
+      'Windows-x86-64', 'CompilerAdditions'
+    );
+  }
+
+  // ── 3. macOS ────────────────────────────────────────────────────────────
+  if (process.platform === 'darwin') {
+    const { execSync } = require('child_process');
+    const machine = execSync('uname -m').toString().trim();
+    const archDir  = machine === 'arm64' ? 'MacOSX-ARM64' : 'MacOSX-x86-64';
+    return path.join(
+      '/Applications/Wolfram 3.app/Contents/SystemFiles/Links/WSTP/DeveloperKit',
+      archDir, 'CompilerAdditions'
+    );
+  }
+
+  // ── 4. Linux ────────────────────────────────────────────────────────────
+  {
+    const { execSync } = require('child_process');
+    const machine = execSync('uname -m').toString().trim();
+    const archDir  = machine === 'aarch64' ? 'Linux-ARM64' : 'Linux-x86-64';
+    const candidates = [
+      path.join(process.env.HOME || '/root', 'Wolfram', 'WolframEngine',
+                'SystemFiles', 'Links', 'WSTP', 'DeveloperKit', archDir, 'CompilerAdditions'),
+      path.join('/usr/local/Wolfram/WolframEngine',
+                'SystemFiles', 'Links', 'WSTP', 'DeveloperKit', archDir, 'CompilerAdditions'),
+    ];
+    for (const c of candidates) {
+      if (fs.existsSync(c)) return c;
+    }
+    throw new Error(
+      'WSTP DeveloperKit not found for Linux.\n' +
+      'Set WSTP_DIR to the CompilerAdditions directory.'
+    );
+  }
+}
+
+process.stdout.write(resolve());