rclnodejs 1.5.1 → 1.5.2

package/README.md

@@ -31,6 +31,26 @@ npm i rclnodejs
 
 - **Note:** to install rclnodejs from GitHub: add `"rclnodejs":"RobotWebTools/rclnodejs#<branch>"` to your `package.json` dependency section.
 
+### Prebuilt Binaries
+
+rclnodejs ships with prebuilt native binaries for common Linux configurations since `v1.5.2`, eliminating the need for compilation during installation. This significantly speeds up installation and reduces dependencies.
+
+**Supported Platforms:**
+
+- **Ubuntu 22.04 (Jammy)** - ROS 2 Humble
+- **Ubuntu 24.04 (Noble)** - ROS 2 Jazzy, Kilted
+- **Architectures:** x64, arm64
+- **Node.js:** >= 16.20.2 (N-API compatible)
+
+**Force Building from Source:**
+
+If you need to build from source even when a prebuilt binary is available, set the environment variable:
+
+```bash
+export RCLNODEJS_FORCE_BUILD=1
+npm install rclnodejs
+```
+
 ## Documentation
 
 API [documentation](https://robotwebtools.github.io/rclnodejs/docs/index.html) is available online.
@@ -73,9 +93,12 @@ See [TypeScript demos](https://github.com/RobotWebTools/rclnodejs/tree/develop/t
 
 Create rich, interactive desktop applications using Electron and web technologies like Three.js. Build 3D visualizations, monitoring dashboards, and control interfaces that run on Windows, macOS, and Linux.
 
-Try the `electron_demo/turtle_tf2` demo for real-time coordinate frame visualization with dynamic transforms and keyboard-controlled turtle movement. More examples in [electron_demo](https://github.com/RobotWebTools/rclnodejs/tree/develop/electron_demo).
+|                                                  Demo                                                   |                                                              Description                                                              |                                                           Screenshot                                                            |
+| :-----------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------: |
+|  **🐢 [turtle_tf2](https://github.com/RobotWebTools/rclnodejs/tree/develop/electron_demo/turtle_tf2)**  |  Real-time coordinate frame visualization with turtle control. Features TF2 transforms, keyboard control, and dynamic frame updates.  |  ![turtle_tf2](https://github.com/RobotWebTools/rclnodejs/blob/develop/electron_demo/turtle_tf2/turtle-tf2-demo.png?raw=true)   |
+| **🦾 [manipulator](https://github.com/RobotWebTools/rclnodejs/tree/develop/electron_demo/manipulator)** | Interactive two-joint robotic arm simulation. Features 3D joint visualization, manual/automatic control, and visual movement markers. | ![manipulator](https://github.com/RobotWebTools/rclnodejs/blob/develop/electron_demo/manipulator/manipulator-demo.png?raw=true) |
 
-![demo screenshot](https://github.com/RobotWebTools/rclnodejs/blob/develop/electron_demo/turtle_tf2/turtle-tf2-demo.gif?raw=true)
+Explore more examples in [electron_demo](https://github.com/RobotWebTools/rclnodejs/tree/develop/electron_demo).
 
 ## License
 

package/binding.gyp

@@ -42,9 +42,11 @@
         './src/rcl_timer_bindings.cpp',
         './src/rcl_utilities.cpp',
         './src/shadow_node.cpp',
+        './third_party/ref-napi/src/ref_napi_bindings.cpp',
       ],
       'include_dirs': [
         '.',
+        './third_party/ref-napi/src',
         '<(ros_include_root)',
         "<!@(node -p \"require('node-addon-api').include\")",
       ],

package/index.js

@@ -37,7 +37,7 @@ const {
 } = require('./lib/parameter.js');
 const path = require('path');
 const QoS = require('./lib/qos.js');
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./lib/native_loader.js');
 const tsdGenerator = require('./rostsd_gen/index.js');
 const validator = require('./lib/validator.js');
 const Time = require('./lib/time.js');

package/lib/action/client.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('../native_loader.js');
 const ActionInterfaces = require('./interfaces.js');
 const ActionUuid = require('./uuid.js');
 const ClientGoalHandle = require('./client_goal_handle.js');

package/lib/action/graph.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('../native_loader.js');
 
 /**
  * Get a list of action names and types for action clients associated with a node.

package/lib/action/server.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('../native_loader.js');
 const ActionInterfaces = require('./interfaces.js');
 const ActionUuid = require('./uuid.js');
 const DistroUtils = require('../distro.js');

package/lib/action/server_goal_handle.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('../native_loader.js');
 const ActionInterfaces = require('./interfaces.js');
 const Deferred = require('./deferred.js');
 const { GoalEvent } = require('./response.js');

package/lib/client.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 const DistroUtils = require('./distro.js');
 const Entity = require('./entity.js');
 const debug = require('debug')('rclnodejs:client');

package/lib/clock.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 const Time = require('./time.js');
 const ClockType = require('./clock_type.js');
 

package/lib/context.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 
 let defaultContext = null;
 

package/lib/duration.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 const S_TO_NS = 10n ** 9n;
 
 /**

package/lib/event_handler.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 const DistroUtils = require('./distro.js');
 const Entity = require('./entity.js');
 

package/lib/guard_condition.js

@@ -12,7 +12,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 const Entity = require('./entity.js');
 const Context = require('./context.js');
 

package/lib/lifecycle.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 const LifecyclePublisher = require('./lifecycle_publisher.js');
 const loader = require('./interface_loader.js');
 const Context = require('./context.js');

package/lib/lifecycle_publisher.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 const Logging = require('./logging.js');
 const Publisher = require('./publisher.js');
 

package/lib/logging.js

@@ -15,7 +15,7 @@
 'use strict';
 
 const path = require('path');
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 
 /**
  * Enum for LoggingSeverity

package/lib/native_loader.js

@@ -0,0 +1,173 @@
+// Copyright (c) 2025, The Robot Web Tools Contributors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const bindings = require('bindings');
+const debug = require('debug')('rclnodejs');
+const { detectUbuntuCodename } = require('./utils');
+
+let nativeModule = null;
+
+// Simplified loader: only use prebuilt binaries with exact Ubuntu/ROS2/arch match
+// Note: Prebuilt binaries are only supported on Linux (Ubuntu) platform
+function customFallbackLoader() {
+  // Prebuilt binaries are only for Linux platform
+  if (process.platform !== 'linux') {
+    debug('Prebuilt binaries are only supported on Linux platform');
+    return null;
+  }
+
+  const rosDistro = process.env.ROS_DISTRO;
+  const arch = process.arch;
+  const ubuntuCodename = detectUbuntuCodename();
+
+  // Require all three components for exact match
+  if (!rosDistro || !ubuntuCodename || !arch) {
+    debug(
+      `Missing environment info - ROS: ${rosDistro}, Ubuntu: ${ubuntuCodename}, Arch: ${arch}`
+    );
+    return null;
+  }
+
+  const prebuildDir = path.join(
+    __dirname,
+    '..',
+    'prebuilds',
+    `${process.platform}-${arch}`
+  );
+
+  if (!fs.existsSync(prebuildDir)) {
+    debug('No prebuilds directory found');
+    return null;
+  }
+
+  try {
+    // Look for exact match binary: {ros_distro}-{ubuntu_codename}-{arch}-rclnodejs.node
+    const exactMatchFilename = `${rosDistro}-${ubuntuCodename}-${arch}-rclnodejs.node`;
+    const exactMatchPath = path.join(prebuildDir, exactMatchFilename);
+
+    if (fs.existsSync(exactMatchPath)) {
+      debug(`Found exact match binary: ${exactMatchFilename}`);
+      return require(exactMatchPath);
+    }
+
+    debug(`No exact match found for: ${exactMatchFilename}`);
+    return null;
+  } catch (e) {
+    debug('Error in simplified prebuilt loader:', e.message);
+  }
+
+  return null;
+}
+
+// Simplified prebuilt binary loader: exact match or build from source
+function loadNativeAddon() {
+  if (nativeModule) {
+    return nativeModule;
+  }
+
+  // Environment variable to force building from source
+  if (process.env.RCLNODEJS_FORCE_BUILD === '1') {
+    debug('Forcing build from source (RCLNODEJS_FORCE_BUILD=1)');
+
+    // Trigger actual compilation
+    try {
+      debug('Running forced node-gyp rebuild...');
+      execSync('npm run rebuild', {
+        stdio: 'inherit',
+        cwd: path.join(__dirname, '..'),
+        timeout: 300000, // 5 minute timeout
+      });
+
+      // Load the newly built binary
+      nativeModule = bindings('rclnodejs');
+      debug('Successfully force compiled and loaded from source');
+      return nativeModule;
+    } catch (compileError) {
+      debug('Forced compilation failed:', compileError.message);
+      throw new Error(
+        `Failed to force build rclnodejs from source: ${compileError.message}`
+      );
+    }
+  }
+
+  const rosDistro = process.env.ROS_DISTRO;
+  const ubuntuCodename = detectUbuntuCodename();
+
+  debug(
+    `Platform: ${process.platform}, Arch: ${process.arch}, Ubuntu: ${ubuntuCodename || 'unknown'}, ROS: ${rosDistro || 'unknown'}`
+  );
+
+  // Prebuilt binaries are only supported on Linux (Ubuntu)
+  if (process.platform === 'linux') {
+    // Try exact match prebuilt binary first
+    try {
+      const prebuiltModule = customFallbackLoader();
+      if (prebuiltModule) {
+        nativeModule = prebuiltModule;
+        return nativeModule;
+      }
+    } catch (e) {
+      debug('Exact match prebuilt loading failed:', e.message);
+    }
+
+    debug(
+      'No exact match prebuilt binary found, falling back to build from source'
+    );
+  } else {
+    debug(
+      `Platform ${process.platform} does not support prebuilt binaries, will try existing build or compile from source`
+    );
+  }
+
+  try {
+    // Try to find existing built binary first (works on all platforms)
+    // The 'bindings' module will search standard locations like:
+    // - build/Release/rclnodejs.node
+    // - build/Debug/rclnodejs.node
+    // - compiled/{node_version}/{platform}/{arch}/rclnodejs.node
+    // etc.
+    nativeModule = bindings('rclnodejs');
+    debug('Found and loaded existing built binary');
+    return nativeModule;
+  } catch {
+    debug('No existing built binary found, triggering compilation...');
+
+    // Trigger actual compilation
+    try {
+      debug('Running node-gyp rebuild...');
+      execSync('npm run rebuild', {
+        stdio: 'inherit',
+        cwd: path.join(__dirname, '..'),
+        timeout: 300000, // 5 minute timeout
+      });
+
+      // Try to load the newly built binary
+      nativeModule = bindings('rclnodejs');
+      debug('Successfully compiled and loaded from source');
+      return nativeModule;
+    } catch (compileError) {
+      debug('Compilation failed:', compileError.message);
+      throw new Error(
+        `Failed to build rclnodejs from source: ${compileError.message}`
+      );
+    }
+  }
+}
+
+module.exports = loadNativeAddon();

package/lib/node.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 
 const ActionInterfaces = require('./action/interfaces.js');
 const Client = require('./client.js');

package/lib/publisher.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 const debug = require('debug')('rclnodejs:publisher');
 const Entity = require('./entity.js');
 

package/lib/serialization.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 
 class Serialization {
   /**

package/lib/service.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 const DistroUtils = require('./distro.js');
 const Entity = require('./entity.js');
 const debug = require('debug')('rclnodejs:service');

package/lib/subscription.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 const Entity = require('./entity.js');
 const debug = require('debug')('rclnodejs:subscription');
 

package/lib/time.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 const Duration = require('./duration.js');
 const ClockType = require('./clock_type.js');
 const S_TO_NS = 10n ** 9n;

package/lib/time_source.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 const { Clock, ROSClock } = require('./clock.js');
 const { ClockType } = Clock;
 const { Parameter, ParameterType } = require('./parameter.js');

package/lib/timer.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 const DistroUtils = require('./distro.js');
 
 /**

package/lib/type_description_service.js

@@ -15,7 +15,7 @@
 'use strict';
 
 const loader = require('./interface_loader.js');
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 const Service = require('./service.js');
 
 const {

package/lib/utils.js

@@ -0,0 +1,37 @@
+// Copyright (c) 2025, The Robot Web Tools Contributors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+const fs = require('fs');
+
+/**
+ * Detect Ubuntu codename from /etc/os-release
+ * @returns {string|null} Ubuntu codename (e.g., 'noble', 'jammy') or null if not detectable
+ */
+function detectUbuntuCodename() {
+  if (process.platform !== 'linux') {
+    return null;
+  }
+
+  try {
+    const osRelease = fs.readFileSync('/etc/os-release', 'utf8');
+    const match = osRelease.match(/^VERSION_CODENAME=(.*)$/m);
+    return match ? match[1].trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+module.exports = {
+  detectUbuntuCodename,
+};

package/lib/validator.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 
 /**
  * An object - Representing a validator in ROS.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rclnodejs",
-  "version": "1.5.1",
+  "version": "1.5.2",
   "description": "ROS2.0 JavaScript client with Node.js",
   "main": "index.js",
   "types": "types/index.d.ts",
@@ -22,7 +22,7 @@
     "generate-messages:dev": "node scripts/generate_messages.js --debug && npx --yes prettier --ignore-path --write generated/**/*.js",
     "generate-tsd-messages": "node scripts/generate_tsd.js",
     "clean": "node-gyp clean && npx rimraf ./generated",
-    "install": "npm run rebuild",
+    "install": "node scripts/install.js",
     "postinstall": "npm run generate-messages",
     "docs": "cd docs && make",
     "test": "nyc node --expose-gc ./scripts/run_test.js && tsd",
@@ -30,13 +30,14 @@
     "lint": "eslint && node ./scripts/cpplint.js",
     "format": "clang-format -i -style=file ./src/*.cpp ./src/*.h && npx --yes prettier --write \"{lib,rosidl_gen,rostsd_gen,rosidl_parser,types,example,test,scripts,benchmark,rostsd_gen}/**/*.{js,md,ts}\" ./*.{js,md,ts}",
     "prepare": "husky",
-    "coverage": "cat ./coverage/lcov.info | ./node_modules/coveralls/bin/coveralls.js"
+    "coverage": "cat ./coverage/lcov.info | ./node_modules/coveralls/bin/coveralls.js",
+    "prebuild": "prebuildify --napi --strip --target 16.20.2 --target electron@23.0.0 && node scripts/tag_prebuilds.js"
   },
   "bin": {
     "generate-ros-messages": "./scripts/generate_messages.js"
   },
   "authors": [
-    "Minggang Wang <minggang.wang@intel.com>",
+    "Minggang Wang <minggangw@gmail.com>",
     "Kenny Yuan <kaining.yuan@intel.com>",
     "Wanming Lin <wanming.lin@intel.com>",
     "Zhong Qiu <zhongx.qiu@intel.com>"
@@ -47,8 +48,8 @@
     "url": "git+https://github.com/RobotWebTools/rclnodejs.git"
   },
   "devDependencies": {
-    "@eslint/js": "^10.0.0",
-    "@types/node": "^22.13.9",
+    "@eslint/js": "^9.36.0",
+    "@types/node": "^24.5.2",
     "@typescript-eslint/eslint-plugin": "^8.18.0",
     "@typescript-eslint/parser": "^8.18.0",
     "clang-format": "^1.8.0",
@@ -61,18 +62,18 @@
     "globals": "^16.0.0",
     "husky": "^9.1.7",
     "jsdoc": "^4.0.4",
-    "lint-staged": "^15.2.10",
+    "lint-staged": "^16.2.0",
     "mocha": "^11.0.2",
     "nyc": "^17.1.0",
+    "prebuildify": "^6.0.1",
     "rimraf": "^6.0.1",
-    "sinon": "^19.0.2",
+    "sinon": "^21.0.0",
     "tree-kill": "^1.2.2",
-    "tsd": "^0.31.2",
+    "tsd": "^0.33.0",
     "typescript": "^5.7.2"
   },
   "dependencies": {
     "@rclnodejs/ref-array-di": "^1.2.2",
-    "@rclnodejs/ref-napi": "^4.0.0",
     "@rclnodejs/ref-struct-di": "^1.1.1",
     "bindings": "^1.5.0",
     "compare-versions": "^6.1.1",
@@ -81,9 +82,9 @@
     "fs-extra": "^11.2.0",
     "is-close": "^1.3.3",
     "json-bigint": "^1.0.0",
+    "node-addon-api": "^8.3.1",
     "terser": "^5.39.0",
-    "walk": "^2.3.15",
-    "node-addon-api": "^8.3.1"
+    "walk": "^2.3.15"
   },
   "husky": {
     "hooks": {

package/rosidl_gen/deallocator.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('../lib/native_loader.js');
 
 let deallocator = {
   delayFreeStructMember(refObj, type, name) {

package/rosidl_gen/generator.json

@@ -4,7 +4,7 @@
   "description": "Generate JavaScript object from ROS IDL(.msg/.srv/.action/.idl) files",
   "main": "index.js",
   "authors": [
-    "Minggang Wang <minggang.wang@intel.com>",
+    "Minggang Wang <minggangw@gmail.com>",
     "Kenny Yuan <kaining.yuan@intel.com>"
   ],
   "license": "Apache-2.0"

package/rosidl_gen/primitive_types.js

@@ -14,9 +14,9 @@
 
 'use strict';
 
-const ref = require('@rclnodejs/ref-napi');
+const ref = require('../third_party/ref-napi');
 const StructType = require('@rclnodejs/ref-struct-di')(ref);
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('../lib/native_loader.js');
 
 const StringRefStruct = StructType({
   data: ref.types.CString,

package/rosidl_gen/templates/message.dot

@@ -224,9 +224,9 @@ function extractMemberNames(fields) {
 }}
 
 {{? willUseTypedArray}}
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('../../lib/native_loader.js');
 {{?}}
-const ref = require('@rclnodejs/ref-napi');
+const ref = require('../../third_party/ref-napi');
 const StructType = require('@rclnodejs/ref-struct-di')(ref);
 const ArrayType = require('@rclnodejs/ref-array-di')(ref);
 const primitiveTypes = require('../../rosidl_gen/primitive_types.js');