From fd19f0a48d00ab24d82ddec9cdfaff8555293304 Mon Sep 17 00:00:00 2001 From: Minggang Wang Date: Wed, 25 Mar 2026 13:26:27 +0800 Subject: [PATCH 1/2] [Doc] Clarify README install and quick start guidance --- README.md | 57 ++++++++++++++++++++++++++++++----------- scripts/npmjs-readme.md | 25 +++++++++++++++--- 2 files changed, 63 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 1fbc1d8a8..3edb944ad 100644 --- a/README.md +++ b/README.md @@ -20,12 +20,14 @@ rclnodejs.init().then(() => { }); ``` +This example assumes your ROS 2 environment is already sourced. + ## Documentation - Get started: [Installation](#installation), [Quick Start](#quick-start), [Tutorials](./tutorials/) - Reference: - [API Documentation](#api-documentation), [Using TypeScript](#using-rclnodejs-with-typescript), [ROS2 Interface Message Generation](#ros2-interface-message-generation) + [API Documentation](#api-documentation), [Using TypeScript](#using-rclnodejs-with-typescript), [ROS 2 Interface Message Generation](#ros-2-interface-message-generation) - Features and examples: [rclnodejs-cli](#rclnodejs-cli), [Electron-based Visualization](#electron-based-visualization), [Observable Subscriptions](#observable-subscriptions), [Performance Benchmarks](#performance-benchmarks) - Project docs: @@ -33,18 +35,41 @@ rclnodejs.init().then(() => { ## Installation +Choose the path that matches how you plan to use rclnodejs: + +- Install from npm: add rclnodejs to your own application. +- Quick Start: run the examples from this repository checkout. + ### Prerequisites - [Node.js](https://nodejs.org/en/) version >= 16.13.0 -- [ROS 2 SDK](https://docs.ros.org/en/jazzy/Installation.html) - **Don't forget to [source the setup file](https://docs.ros.org/en/jazzy/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.html#source-the-setup-files)** +- [ROS 2 SDK](https://docs.ros.org/en/jazzy/Installation.html) + +Before installing, building, or running rclnodejs, source your ROS 2 environment: + +```bash +source /opt/ros//setup.bash +``` -### Install rclnodejs +### Install from npm + +Use this path if you want to depend on rclnodejs from your own ROS 2 Node.js application. ```bash npm i rclnodejs ``` -> **Note:** To install rclnodejs from GitHub: add `"rclnodejs":"RobotWebTools/rclnodejs#"` to your `package.json` dependency section. +After installation, use the example at the top of this README as a minimal publisher, or continue with [Quick Start](#quick-start) to run the examples in this repository. + +### Install from GitHub + +Use this path only if you need a branch or commit that is not yet published to npm. + +```bash +npm install RobotWebTools/rclnodejs# +``` + +Or add `"rclnodejs":"RobotWebTools/rclnodejs#"` to your `package.json` dependency section. > **Docker:** For containerized development, see the included [Dockerfile](./Dockerfile) for building and testing with different ROS distributions and Node.js versions. @@ -52,7 +77,7 @@ See the [features](./docs/FEATURES.md) and try the [examples](https://github.com ### 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. +rclnodejs ships with prebuilt native binaries for common Linux configurations since `v1.5.2`, eliminating the need for compilation during installation. This applies to supported Linux environments when installing from npm or GitHub. **Supported Platforms:** @@ -74,25 +99,27 @@ npm install rclnodejs ## Quick Start -1. Source your ROS 2 environment. +Use these steps if you are working from this repository checkout and want to run one of the included examples. -```bash -source /opt/ros//setup.bash -``` +These steps assume the [installation prerequisites](#prerequisites) are already satisfied and your ROS 2 environment has been sourced. -2. Install the repository dependencies. +1. Install the repository dependencies from the project root. ```bash npm install ``` -3. Run a publisher example from this checkout. +2. Run a publisher example from this checkout. ```bash node example/topics/publisher/publisher-example.js ``` -You should see messages being published once per second. Explore more runnable examples in [example/](https://github.com/RobotWebTools/rclnodejs/tree/develop/example) and step-by-step guides in [tutorials/](./tutorials/). +You should see messages being published once per second. + +If you want to build an application instead of running the repository examples, install rclnodejs into your own project with [Install from npm](#install-from-npm) and start from the sample code near the top of this README. + +Explore more runnable examples in [example/](https://github.com/RobotWebTools/rclnodejs/tree/develop/example) and step-by-step guides in [tutorials/](./tutorials/). ## rclnodejs-cli @@ -102,7 +129,7 @@ See the rclnodejs-cli repository for installation instructions and the current c ## API Documentation -API documentation is available [online](https://robotwebtools.github.io/rclnodejs/docs/index.html) or generate locally with `npm run docs`. +API documentation is available [online](https://robotwebtools.github.io/rclnodejs/docs/index.html). To generate it locally from this repository checkout, run `npm run docs`. ## Electron-based Visualization @@ -164,7 +191,7 @@ obsSub.observable See the [Observable Subscriptions Tutorial](./tutorials/observable-subscriptions.md) for more details. -## ROS2 Interface Message Generation +## ROS 2 Interface Message Generation ROS client libraries convert IDL message descriptions into target language source code. rclnodejs provides the `generate-ros-messages` script to generate JavaScript message interface files and TypeScript declarations. @@ -178,7 +205,7 @@ stringMsgObject.data = 'hello world'; ### Running Message Generation -Run the message generation script when new ROS packages are installed: +Run the message generation script in your project when new ROS packages are installed: ```bash npx generate-ros-messages diff --git a/scripts/npmjs-readme.md b/scripts/npmjs-readme.md index dcad53de7..633c57c5f 100644 --- a/scripts/npmjs-readme.md +++ b/scripts/npmjs-readme.md @@ -14,12 +14,20 @@ rclnodejs.init().then(() => { }); ``` +This example assumes your ROS 2 environment is already sourced. + ## Installation ### Prerequisites - [Node.js](https://nodejs.org/en/) version >= 16.13.0 -- [ROS 2 SDK](https://docs.ros.org/en/jazzy/Installation.html) - **Don't forget to [source the setup file](https://docs.ros.org/en/jazzy/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.html#source-the-setup-files)** +- [ROS 2 SDK](https://docs.ros.org/en/jazzy/Installation.html) + +Before installing or running rclnodejs, source your ROS 2 environment: + +```bash +source /opt/ros//setup.bash +``` ### Install rclnodejs @@ -27,11 +35,17 @@ rclnodejs.init().then(() => { npm i rclnodejs ``` -- **Note:** To install rclnodejs from GitHub, add `"rclnodejs":"RobotWebTools/rclnodejs#"` to your `package.json` dependencies. +To install from GitHub instead of npm, run: + +```bash +npm install RobotWebTools/rclnodejs# +``` + +Or add `"rclnodejs":"RobotWebTools/rclnodejs#"` to your `package.json` dependencies. ### Prebuilt Binaries -rclnodejs ships with prebuilt native binaries for common Linux configurations since `v1.5.2`, eliminating the need for compilation during installation. +rclnodejs ships with prebuilt native binaries for common Linux configurations since `v1.5.2`, eliminating the need for compilation during installation. This applies to supported Linux environments when installing from npm or GitHub. **Supported Platforms:** @@ -52,6 +66,7 @@ npm install rclnodejs ## Documentation and Examples - API documentation: [robotwebtools.github.io/rclnodejs/docs](https://robotwebtools.github.io/rclnodejs/docs/index.html) +- Tutorials: [tutorials/](https://github.com/RobotWebTools/rclnodejs/tree/develop/tutorials) - JavaScript examples: [example/](https://github.com/RobotWebTools/rclnodejs/tree/develop/example) - TypeScript demos: [ts_demo/](https://github.com/RobotWebTools/rclnodejs/tree/develop/ts_demo) - Electron demos: [electron_demo/](https://github.com/RobotWebTools/rclnodejs/tree/develop/electron_demo) @@ -59,7 +74,7 @@ npm install rclnodejs ## Message Generation -rclnodejs generates JavaScript message interfaces and TypeScript declarations during installation for `rclnodejs > 1.5.0`. If you install additional ROS packages later, rerun: +rclnodejs generates JavaScript message interfaces and TypeScript declarations during installation for `rclnodejs > 1.5.0`. If you install additional ROS packages later, rerun the generator in your project: ```bash npx generate-ros-messages @@ -67,6 +82,8 @@ npx generate-ros-messages Generated files are written to `/node_modules/rclnodejs/generated/`. +This step is only needed after adding ROS packages that were not present when rclnodejs was installed. + ## Using rclnodejs with TypeScript TypeScript declaration files are included in the package. In most projects, configuring your `tsconfig.json` is sufficient: From 3cd4fa75d826c6da0ea28f42099fbc28be85d04a Mon Sep 17 00:00:00 2001 From: Minggang Wang Date: Wed, 25 Mar 2026 14:53:32 +0800 Subject: [PATCH 2/2] Address comments --- README.md | 4 +++- scripts/npmjs-readme.md | 2 +- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3edb944ad..89107f8fb 100644 --- a/README.md +++ b/README.md @@ -65,6 +65,8 @@ After installation, use the example at the top of this README as a minimal publi Use this path only if you need a branch or commit that is not yet published to npm. +GitHub installs normally build from source. The published npm package includes prebuilt binaries for supported Linux targets, but this repository does not track those prebuilt artifacts. + ```bash npm install RobotWebTools/rclnodejs# ``` @@ -77,7 +79,7 @@ See the [features](./docs/FEATURES.md) and try the [examples](https://github.com ### Prebuilt Binaries -rclnodejs ships with prebuilt native binaries for common Linux configurations since `v1.5.2`, eliminating the need for compilation during installation. This applies to supported Linux environments when installing from npm or GitHub. +rclnodejs ships with prebuilt native binaries for common Linux configurations since `v1.5.2`, eliminating the need for compilation during installation. This applies to supported Linux environments when installing the published npm package. **Supported Platforms:** diff --git a/scripts/npmjs-readme.md b/scripts/npmjs-readme.md index 633c57c5f..0c74391ee 100644 --- a/scripts/npmjs-readme.md +++ b/scripts/npmjs-readme.md @@ -45,7 +45,7 @@ Or add `"rclnodejs":"RobotWebTools/rclnodejs#"` to your `package.json` d ### Prebuilt Binaries -rclnodejs ships with prebuilt native binaries for common Linux configurations since `v1.5.2`, eliminating the need for compilation during installation. This applies to supported Linux environments when installing from npm or GitHub. +rclnodejs ships with prebuilt native binaries for common Linux configurations since `v1.5.2`, eliminating the need for compilation during installation. This applies to supported Linux environments when installing the published npm package. **Supported Platforms:**