some settings required to work in this project

Author: sailingKieler

.github/workflows/build.yml

@@ -28,16 +28,13 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        os: [ macos-10.15, macos-11, macos-12, ubuntu-18.04, ubuntu-20.04, ubuntu-22.04, windows-2019, windows-2022 ]
-        node: [ 14, 16, 18 ]
-        exclude:
-          - os: ubuntu-18.04
-            node: 18
+        os: [ macos-12, macos-13, macos-14, ubuntu-20.04, ubuntu-22.04, windows-2019, windows-2022 ] # ubuntu-24.04 does not bring LLVM 14
+        node: [ 18, 20, 22 ]
     steps:
       - name: Fetch Codebase
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: Setup Node.js
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node }}
           check-latest: true
@@ -46,6 +43,7 @@ jobs:
         run: |
           brew update
           brew install llvm@${{ env.LLVM_VERSION_MAJOR }} ninja
+          echo "cmake_LLVM_DIR=$($(brew --prefix llvm@${{ env.LLVM_VERSION_MAJOR }})/bin/llvm-config --cmakedir)" > .npmrc
       - name: Install LLVM and Ninja on Ubuntu
         if: startsWith(matrix.os, 'ubuntu')
         run: |
@@ -61,7 +59,7 @@ jobs:
           curl -sLO https://github.com/ApsarasX/llvm-windows/releases/download/llvmorg-$LLVM_VERSION/$LLVM_PREBUILT_FILE
           Expand-Archive -Path $LLVM_PREBUILT_FILE -DestinationPath .
           $LLVM_CMAKE_DIR = "$pwd\\LLVM-$LLVM_VERSION-win64\\lib\\cmake\\llvm"
-          npm config set cmake_LLVM_DIR $LLVM_CMAKE_DIR
+          echo "cmake_LLVM_DIR=$LLVM_CMAKE_DIR"> .npmrc
       - name: Install Dependencies
         run: npm install --ignore-scripts
       - name: CMake Build Debug and Test
@@ -74,4 +72,4 @@ jobs:
         run: |
           npm run clear
           npm run build:release
-          npm test
+          npm test

.gitignore

@@ -1,5 +1,9 @@
+.npmrc
+
 .idea/
-.vscode/
+.vscode/*
+!.vscode/launch.json
+!.vscode/settings.json
 
 cmake-build-*/
 

.npmrc.template

@@ -0,0 +1 @@
+cmake_LLVM_DIR=/opt/homebrew/opt/llvm@14/lib/cmake/llvm/

.vscode/launch.json

@@ -0,0 +1,56 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Jest: Run tests in current file",
+            "type": "node",
+            "request": "launch",
+            "runtimeExecutable": "npx",
+            "program": "jest",
+            "args": [
+                "${relativeFile}",
+            ],
+            "console": "integratedTerminal",
+            "skipFiles": [
+                "<node_internals>/**"
+            ],
+            "outFiles": [
+                "${workspaceFolder}/**/*.js"
+            ]
+        },
+        {
+            "name": "Vitest: Run tests in current file",
+            "type": "node",
+            "request": "launch",
+            "runtimeExecutable": "npx",
+            "program": "vitest",
+            "args": [
+                "run",
+                "${relativeFile}",
+            ],
+            "console": "integratedTerminal",
+            "skipFiles": [
+                "<node_internals>/**"
+            ],
+            "outFiles": [
+                "${workspaceFolder}/**/*.js"
+            ]
+        },
+        {
+            /* execute npm build:debug before running this! */
+            "name": "LLDB: Debug LLVM-binding native parts during Vitest execution",
+            "type": "lldb",
+            "request": "launch",
+            "program": "node",
+            "sourceLanguages": ["cpp", "javascript"],
+            "args": [
+                "${workspaceFolder}/node_modules/vitest/dist/cli-wrapper.js",
+                "run",
+                "${relativeFile}",
+            ],
+        },
+    ]
+}

.vscode/settings.json

@@ -0,0 +1,18 @@
+{
+    "C_Cpp.default.cStandard": "c17",
+    "C_Cpp.default.cppStandard": "c++17",
+    "C_Cpp.default.includePath": [
+        "/opt/homebrew/opt/llvm@14/include",
+        "${userHome}/.cmake-js/node-*/v*/include/node",
+        "${workspaceFolder}/node_modules/node-addon-api",
+        "${workspaceFolder}/include",
+    ],
+    "clangd.fallbackFlags": [
+        "-std=c++17",
+        "-xc++-header",
+        "-I/opt/homebrew/opt/llvm@14/include",
+        "-I${userHome}/.cmake-js/node-arm64/v18.18.2/include/node/", /* switch to your arch & version here! */
+        "-I${workspaceFolder}/node_modules/node-addon-api",
+        "-I${workspaceFolder}/include",
+    ]
+}

README.md

@@ -29,9 +29,21 @@ listed in the [TypeScript definition file](./llvm-bindings.d.ts).
 
 ### Install on macOS
 
+Make sure `llvm@14` as well as `cmake` are available, e.g. via
 ```shell
 # install cmake and llvm by homebrew
 brew install cmake llvm@14
+```
+
+Tell the extra build tool used here (`cmake-js`) where to find some cmake-specific integration setup of LLVM 14, then `npm install` the package.
+1. First create the required new file named `.npmrc`
+   * alternatively, copy `.npmrc.template` to `.npmrc` and adapt the configured path if needed, `brew --prefix llvm@14` gives you the install dir of LLVM14.
+2. Then run `npm install llvm-bindings`
+
+```shell
+# specify the LLVM cmake directory for cmake-js
+#  also see '.npmrc.template' for reference
+echo "cmake_LLVM_DIR=$($(brew --prefix llvm@14)/bin/llvm-config --cmakedir)" > .npmrc
 
 # install llvm-bindings by npm
 npm install llvm-bindings
@@ -54,15 +66,18 @@ npm install llvm-bindings
 
 ### Install on Windows
 
+_Update:_ Use LLVM in version `14.0.6` sequently.
+
 First, please refer to [Build LLVM from sources on Windows 10](https://github.com/ApsarasX/llvm-bindings/wiki/Build-LLVM-from-source-code-on-Windows-10) to build LLVM. An alternative is to download [prebuilt LLVM binary](https://github.com/ApsarasX/llvm-windows/releases).
 
-Then, find the `llvm-config` command in your LLVM build directory and execute `llvm-config --cmakedir` to get LLVM cmake directory, assuming `C:\Users\dev\llvm-13.0.1.src\build\lib\cmake\llvm`.
+Then, find the `llvm-config` command in your LLVM build directory and execute `llvm-config --cmakedir` to get LLVM cmake directory, assuming `C:\Users\dev\llvm-14.0.6.src\build\lib\cmake\llvm`.
 
 Finally, execute the following commands.
 
 ```shell
 # specify the LLVM cmake directory for cmake-js
-npm config set cmake_LLVM_DIR C:\Users\dev\llvm-13.0.1.src\build\lib\cmake\llvm
+#  also see '.npmrc.template' for reference
+echo "cmake_LLVM_DIR=C:\Users\dev\llvm-13.0.1.src\build\lib\cmake\llvm" > .npmrc
 
 # install llvm-bindings by npm
 npm install llvm-bindings
@@ -72,10 +87,14 @@ npm install llvm-bindings
 
 ### Custom LLVM Installation
 You can use the npm configuration options to set the path to the LLVM cmake directory. This is needed if you don't want to use the system default LLVM installation.
+(Formerly, `npm config` was used here. Meanwhile npm validates the config keys for being known and valid, and rejects custom keys.)
+
 
 ```shell
 # specify the llvm cmake directory by npm and cmake-js
-npm config set cmake_LLVM_DIR $(path-to-llvm/bin/llvm-config --cmakedir)
+#  also see '.npmrc.template' for reference
+# on macos `path-to-llvm` can be obtained via `brew --prefix llvm@14`
+echo "cmake_LLVM_DIR=$(path-to-llvm/bin/llvm-config --cmakedir)" > .npmrc
 
 # install llvm-bindings by npm
 npm install llvm-bindings

tsconfig.json

@@ -5,11 +5,13 @@
         "tests/**/*.ts",
     ],
     "compilerOptions": {
+        "noEmit": true,
         "target": "ES5",
         "module": "commonjs",
         "strict": true,
         "moduleResolution": "node",
         "esModuleInterop": true,
-        "forceConsistentCasingInFileNames": true
+        "forceConsistentCasingInFileNames": true,
+        "skipLibCheck": true
     }
 }

vitest.config.mts

@@ -0,0 +1,20 @@
+//import { defineConfig } from "vitest/config"
+
+export default /*defineConfig*/({
+    test: {
+        deps: {
+            interopDefault: true
+        },
+        include: ['**/*.{test,spec}.ts'],
+        exclude: ['**/node_modules/**', '**/dist/**'],
+        globals: true,
+        typecheck: {
+            //enabled: false
+        },
+        poolOptions: {
+            threads: {
+                singleThread: true
+            }
+        }
+    }
+});