diff --git a/README.md b/README.md index 1fbc1d8a8..89107f8fb 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,43 @@ 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) -### Install rclnodejs +Before installing, building, or running rclnodejs, source your ROS 2 environment: + +```bash +source /opt/ros//setup.bash +``` + +### 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. + +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# +``` + +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 +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 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 the published npm package. **Supported Platforms:** @@ -74,25 +101,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 +131,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 +193,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 +207,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..0c74391ee 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 the published npm package. **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: