Add mis-deleted docs (#1227)

minggangw · minggangw · commit cc7583e2e4be · 2025-09-10T18:16:28.000+08:00
Fix: #1228
diff --git a/docs/BUILDING.md b/docs/BUILDING.md
@@ -0,0 +1,77 @@
+# Build rclnodejs
+
+### Get ready for ROS 2
+
+1.Install ROS 2 from binary package.
+
+ROS 2 is a cross-platform system, which covers Linux, macOS and Windows, and the `rclnodejs` module is developed against the [`master`](https://github.com/ros2/ros2/blob/master/ros2.repos) branch of ROS 2. You can download the latest binary packages from [ROS 2 build farm](http://ci.ros2.org/view/packaging/) and follow the instructions of [Linux](https://docs.ros.org/en/rolling/Installation/Ubuntu-Install-Debians.html)/[Windows](https://docs.ros.org/en/rolling/Installation/Windows-Install-Binary.html) to setup the environment (If you want to run your apps on a stable release of ROS 2, e.g. crystal-clemmys, please see the section `Running on Stable Release of ROS 2).
+
+2.Build ROS 2 from scratch.
+
+Alternatively, you can build ROS 2 from scratch. Please select the platform you want to work on, then reference the instructions of [Linux](https://docs.ros.org/en/rolling/Installation/Alternatives/Ubuntu-Development-Setup.html#)/[Windows](https://docs.ros.org/en/rolling/Installation/Alternatives/Windows-Development-Setup.html) to build ROS 2 (please build with flag `--merge-install`).
+
+### Install `Node.js`
+
+**Notice:**
+`rclnodejs` should only be used with node versions between 10.23.1 - 19.x. The lowest LTS Node.js we used to verify the unit tests is `10.23.1`.
+
+I install Nodejs from either:
+
+- Node.js official [website](https://nodejs.org/en/)
+- Node Version Manager ([nvm](https://github.com/creationix/nvm))
+
+### Get Code
+
+Open a terminal, and input:
+
+```bash
+git clone https://github.com/RobotWebTools/rclnodejs.git
+```
+
+### Build Module
+
+Before you build the module, you should make sure the ROS2 environments were loaded. You can check if the `AMENT_PREFIX_PATH` environment variable was set:
+
+- For Windows: `echo %AMENT_PREFIX_PATH%` in the command prompt.
+
+- For Linux and macOS: `echo $AMENT_PREFIX_PATH` in the terminal.
+
+If the `AMENT_PREFIX_PATH` is unset, you should load the ROS2 environments:
+
+- For Windows, open the command prompt and run
+
+```bash
+  call <path\to\ros2>\install\local_setup.bat
+```
+
+- For Linux and macOS, open the terminal and run:
+
+```bash
+  source <path/to/ros2>/install/local_setup.bash
+```
+
+This `Node.js` module is built by [node-gyp](https://www.npmjs.com/package/node-gyp), all you have to do is just to run the following command:
+
+```javascript
+npm install
+```
+
+**Windows-specific**: make sure Python 2.x interpreter is first searched in your `PATH` before running the command. You can change it temporarily by:
+
+```bash
+  set PATH=<path\to\python 2.x>;%PATH%
+```
+
+## Run Unit Tests
+
+The test suite is implemented using the [mocha](https://www.npmjs.com/package/mocha) JavaScript test framework for node.js. Run the unit tests:
+
+```javascript
+npm run test
+```
+
+**Windows-specific**: the tests requires in a `Microsoft Visual Studio Native Tools command prompt`, and also make sure Python 3.x interpreter is first searched in your `PATH` before running te test. You can change it temporarily by:
+
+```bash
+  set PATH=<path\to\python 3.x>;%PATH%
+```
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -0,0 +1,36 @@
+# Contributing to rclnodejs
+
+Thank you for considering contributing to rclnodejs. All help appreciated.
+
+## Bugs and Feature Requests
+
+If you've noticed a bug or have a feature request, [make one](https://github.com/RobotWebTools/rclnodejs/issues/new)! It's generally best if you get confirmation of your bug or approval for your feature request this way before starting to code.
+
+## Getting Started
+
+### Communications and Coordination
+
+If there is a bug or feature request you would like to work on begin by communicating your interest in resolving it. A project maintainer will assign the issue to you.
+
+### Process
+
+Here's the process to follow once a bug or feature request has been assigned to you:
+
+#### Setting up your rclnodejs codebase
+
+1. Fork the rclnodejs project. Refer to the [Building from Scratch Guide](BUILDING.md).
+2. Build your the base project and ensure the test suite runs.
+3. Make a branch for your new code.
+
+#### Coding your Fix or Feature
+
+1. Code your fix or new feature on your new branch.
+2. Code new tests or modify existing tests to cover your changes.
+3. Check for coding style compliance: `npm run lint`. Fix any coding style issues.
+4. Run the test suite and ensure all tests pass.
+5. Commit your changes to your cloned repo.
+
+#### Submitting your Code
+
+1. Submit your changes for review by opening a Pull Request (PR) on the rclnodejs project. Fix any CI failures resulting from your code changes.
+2. The PR will be reviewed by the project team members. Please keep the PR updated to reflect reviewer comments and requests. You may also be requested to rebase the PR and fix any conflicts. When the PR has gained "Looks Good To Me (LGTM)" status, the project maintainers will merge the PR.
diff --git a/docs/EFFICIENCY.md b/docs/EFFICIENCY.md
@@ -0,0 +1,68 @@
+# Tips for efficent use of rclnodejs
+
+While our benchmarks place rclnodejs performance at or above that of [rclpy](https://github.com/ros2/rclpy) we recommend applying efficient coding and configuration practices where applicable.
+
+## Tip-1: Disable Parameter Services
+
+The typical ROS 2 node creation process includes creating an internal parameter service who's job is to fulfill requests for parameter meta-data and to set and update node parameters. If your ROS 2 node does not support public parameters then you can save the resources consumed by the parameter service. Disable the node parameter service by setting the `NodeOption.startParameterServices` property to false as shown below:
+
+```
+let options = new NodeOptions(false);
+// or
+options.startParameterServices = false;
+
+let node = new Node(nodeName, namespace, Context.defaultContext(), options);
+```
+
+## Tip-2: Disable LifecycleNode Lifecycle Services
+
+The LifecycleNode constructor creates 5 life-cycle services to support the ROS 2 lifecycle specification. If your LifecycleNode instance will not be operating in a managed-node context consider disabling the lifecycle services via the LifecycleNode constructor as shown:
+
+```
+let enableLifecycleCommInterface = false;
+
+let node = new LifecycleNode(
+  nodeName,
+  namespace,
+  Context.defaultContext,
+  NodeOptions.defaultOptions,
+  enableLifecycleCommInterface
+);
+```
+
+## Tip-3: Use Content-filtering Subscriptions
+
+The ROS Humble release introduced content-filtering topics
+which enable a subscription to limit the messages it receives
+to a subset of interest. While the application of the a content-filter
+is specific to the DDS/RMW vendor, the general approach is to apply
+filtering on the publisher side. This can reduce network bandwidth
+for pub-sub communications and message processing and memory
+overhead of rclnodejs nodes.
+
+Note: Be sure to confirm that your RMW implementation supports
+content-filter before attempting to use it. In cases where content-filtering
+is not supported your Subscription will simply ignore your filter and
+continue operating with no filtering.
+
+Example:
+
+```
+  // create a content-filter to limit incoming messages to
+  // only those with temperature > 75C.
+  const options = rclnodejs.Node.getDefaultOptions();
+  options.contentFilter = {
+    expression: 'temperature > %0',
+    parameters: [75],
+  };
+
+  node.createSubscription(
+    'sensor_msgs/msg/Temperature',
+    'temperature',
+    options,
+    (temperatureMsg) => {
+      console.log(`EMERGENCY temperature detected: ${temperatureMsg.temperature}`);
+    }
+  );
+
+```
diff --git a/docs/FAQ.md b/docs/FAQ.md
@@ -0,0 +1,79 @@
+# FAQ and Known Issues
+
+Have a question or issue that should be included in this document? Consider opening an issue or discussion with the [rclnodejs project team](https://github.com/RobotWebTools/rclnodejs).
+
+## Undefined or missing JavaScript message file
+
+The most common reasons for this error are:
+
+- Misspelling of a message name in your code
+- The ROS package containing the target message is not installed in your ROS environment
+- The ROS package containing the target message was installed after the `rclnodejs` package was installed in your ROS2-nodejs environment.
+
+#### Verify the ROS package is installed
+
+The first step is to verify that your ROS environment includes the package containing the target message. Using the `ros2` cli list all of the packages in your ROS environment and inspect the output for the package.
+
+```
+ros2 pkg list
+```
+
+If the package containing your target message is not listed then install it.
+
+Next, inspect the generated JavaScript message files by viewing the `./node_modules/rclnodejs/generated/` folder of your project for your target message. If you are unable to locate the message file then use the `generate-messages` script:
+
+```
+<your_project>/node_modules/.bin/generate-messages
+```
+
+## Maximum call stack size exceeded error when running in Jest
+
+When running tests in Jest, you may see an error like this:
+
+```
+RangeError: Maximum call-stack size exceeded
+
+      at debug (../node_modules/ref/node_modules/debug/src/debug.js:1:1)
+      at Object.writePointer [as _writePointer] (../node_modules/ref/lib/ref.js:746:3)
+      at Object.writePointer [as _writePointer] (../node_modules/ref/lib/ref.js:747:11)
+      at Object.writePointer [as _writePointer] (../node_modules/
+      ...
+```
+
+This is caused by a bug in `ref` which happens when you `require` it multiple times. There is a fix available for `ref` but it's no longer being maintained and the author has not published it.
+
+If it is required to use Jest, a solution would be to fork `ref` and use npm shrinkwrap to installed a patched version.
+
+## Running with ASAN
+
+#### Linux
+
+To run with google's AddressSanitizer tool, build with `-fsanitize=address` flag,
+
+```sh
+CXXFLAGS=-fsanitize=address node-gyp build --debug
+```
+
+ASAN needs to be loaded at the start of the process, since rclnodejs is a dynamically loaded library, it will not do so by default. To workaround this, run node with `LD_PRELOAD` to force ASAN to be loaded.
+
+```sh
+LD_PRELOAD=$(g++ -print-file-name=libasan.so) node node_modules/.bin/mocha test/test-publisher.js
+```
+
+Due to v8's garbage collector, there may be false positives in the leak test, to remove them as much as possible, there is a simple helper script to run gc on exit. To use it, the `--expose-gc` flag needs to be set in node, then run mocha with `-r test/gc-on-exit.js` e.g.
+
+```sh
+LD_PRELOAD=$(g++ -print-file-name=libasan.so) node --expose-gc node_modules/.bin/mocha -r test/gc-on-exit.js test/test-publisher.js
+```
+
+**Note**: Tests that forks the current process like `test-array.js` will not run gc when they exit. They may report many false positive leaks.
+
+ASAN may report leaks in ref-napi and other modules, there is a suppression file you can use to hide them
+
+```sh
+LSAN_OPTIONS=suppressions=suppr.txt node --expose-gc node_modules/.bin/mocha -r test/gc-on-exit.js test/test-publisher.js
+```
+
+## FastDDS requirements for multiple node processes on the same machine running under different users
+
+When running multiple ROS 2 node processes configured to use FastDDS ROS middleware (rmw), you can experience a communications failure when the ROS nodes are run under different Linux user accounts. The issue has to do with FastDDS use of shared memory and Linux restrictions on accessing such memory. The workaround is to disable the use of FastDDS shared memory via a configuration file as outlined [here](https://github.com/eProsima/Fast-DDS/issues/1750).
