You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Reduce README length by dividing into smaller documents
README.md
- added Documents section with TOC
./docs/BUILD.md
- build instructions
./CONTRIBUTORS.md
- list of contributors and short description of each contributors work.
./docs/CONTRIBUTING.md
- short guide for how to contribute to the project
./docs/FAQ.md
- faq topics and known issues
Fix#761
Update README.md
Added contributing guidelines.
`rclnodejs` is a Node.js client for the Robot Operating System (ROS 2). It provides a simple and easy JavaScript API for ROS 2 programming. TypeScript declarations are included to support use of rclnodejs in TypeScript projects.
8
+
`rclnodejs` is a Node.js client library for the Robot Operating System (ROS 2). It provides a JavaScript API and TypeScript declarations for ROS 2 programming.
9
9
10
10
Here's an example for how to create a ROS 2 node that publishes a string message in a few lines of JavaScript.
The API documentation is generated by `jsdoc`. To create a local copy run `npm run docs`. Alternatively you can use the prebuilt api documentation found in the `docs/` folder or view the [on-line version](http://robotwebtools.org/rclnodejs/docs/index.html) in your browser.
64
+
API documentation is generated by `jsdoc` and can be viewed in the `docs/` folder or [on-line](http://robotwebtools.org/rclnodejs/docs/index.html). To create a local copy of the documentation run `npm run docs`.
59
65
60
66
## Using TypeScript
61
67
62
-
TypeScript declaration files (\*.d.ts) are included to support developers that wish to use rclnodejs in TypeScript projects.
63
-
64
-
In your node project, in addition to installing the rclnodejs package, you will need to install the TypeScript compiler and node typings.
65
-
66
-
```
67
-
npm install typescript @types/node -D
68
-
```
68
+
`rclnodejs` API can be used in TypeScript projects. You can find the TypeScript declaration files (\*.d.ts) in the `types/` folder.
69
69
70
-
Your tsconfig.json file should include the following compiler options:
70
+
Your project `tsconfig.json` file should include the following compiler options:
71
71
72
72
```jsonc
73
73
{
@@ -80,177 +80,34 @@ Your tsconfig.json file should include the following compiler options:
80
80
}
81
81
```
82
82
83
-
Here's a simple example implemented in TypeScript.
The benefits of using TypeScript become evident when working with more complex use-cases. The ROS 2 messages are defined in the `types/interfaces.d.ts` module. This module is updated as part of the `generate_messages` process. Here's a trivial example of working with a String msg.
95
+
The benefits of using TypeScript become evident when working with more complex use-cases. The ROS 2 messages in your environment are defined in the `types/interfaces.d.ts` module. This module is updated as part of the `generate-ros-messages` process. Here's a trivial example of working with a String msg.
96
96
97
97
```typescript
98
98
const msg:rclnodejs.std_msgs.msg.String= {
99
99
data: 'hello ROS2 from rclnodejs',
100
100
};
101
101
```
102
102
103
-
## Build from Scratch
104
-
105
-
### Get ready for ROS 2
106
-
107
-
1.Install ROS 2 from binary package.
108
-
109
-
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://index.ros.org/doc/ros2/Installation/Linux-Install-Binary/)/[macOS](https://index.ros.org/doc/ros2/Installation/OSX-Install-Binary/)/[Windows](https://index.ros.org/doc/ros2/Installation/Windows-Install-Binary/) 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).
110
-
111
-
2.Build ROS 2 from scratch.
112
-
113
-
Alternatively, you can build ROS 2 from scratch. Please select the platform you want to work on, then reference the instructions of [Linux](https://index.ros.org/doc/ros2/Installation/Linux-Development-Setup/)/[macOS](https://index.ros.org/doc/ros2/Installation/OSX-Development-Setup/)/[Windows](https://index.ros.org/doc/ros2/Installation/Windows-Development-Setup/) to build ROS 2 (please build wiht flag `--merge-install`).
114
-
115
-
### Install `Node.js`
116
-
117
-
**Notice:**
118
-
`rclnodejs` should only be used with node versions between 8.12 - 12.99. The lowest LTS Node.js we used to verify the unit tests is `8.12.0`. And there is a known issue installing rclnodejs with versions of node >= 13.0.
119
-
120
-
The `Node.js` version we selected is the LTS [`Erbium`](https://nodejs.org/download/release/latest-erbium/) (12.x). You can install it:
121
-
122
-
- Download from Node.js offical [website](https://nodejs.org/en/), and install it.
123
-
- Use the Node Version Manager ([nvm](https://github.com/creationix/nvm)) to install it.
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:
136
-
137
-
- For Windows: `echo %AMENT_PREFIX_PATH%` in the command prompt.
138
-
139
-
- For Linux and macOS: `echo $AMENT_PREFIX_PATH` in the terminal.
140
-
141
-
If the `AMENT_PREFIX_PATH` is unset, you should load the ROS2 environments:
142
-
143
-
- For Windows, open the command prompt and run
144
-
145
-
```bash
146
-
call <path\to\ros2>\install\local_setup.bat
147
-
```
148
-
149
-
- For Linux and macOS, open the terminal and run:
150
-
151
-
```bash
152
-
source<path/to/ros2>/install/local_setup.bash
153
-
```
154
-
155
-
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:
156
-
157
-
```javascript
158
-
npm install
159
-
```
160
-
161
-
**Windows-specific**: make sure Python 2.x interpreter is first searched in your `PATH` before running the command. You can change it temporarily by:
162
-
163
-
```bash
164
-
set PATH=<path\to\python 2.x>;%PATH%
165
-
```
166
-
167
-
## Run Unit Tests
168
-
169
-
The test suite is implemented using the [mocha](https://www.npmjs.com/package/mocha) JavaScript test framework for node.js. Run the unit tests:
170
-
171
-
```javascript
172
-
npm run test
173
-
```
174
-
175
-
**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:
176
-
177
-
```bash
178
-
set PATH=<path\to\python 3.x>;%PATH%
179
-
```
180
-
181
-
## Troubleshooting
182
-
183
-
### Maximum call stack size exceeded error when running in Jest
184
-
185
-
When running tests in Jest, you may see an error like this:
186
-
187
-
```
188
-
RangeError: Maximum call stack size exceeded
189
-
190
-
at debug (../node_modules/ref/node_modules/debug/src/debug.js:1:1)
191
-
at Object.writePointer [as _writePointer] (../node_modules/ref/lib/ref.js:746:3)
192
-
at Object.writePointer [as _writePointer] (../node_modules/ref/lib/ref.js:747:11)
193
-
at Object.writePointer [as _writePointer] (../node_modules/ref/lib/ref.js:747:11)
194
-
at Object.writePointer [as _writePointer] (../node_modules/ref/lib/ref.js:747:11)
195
-
at Object.writePointer [as _writePointer] (../node_modules/ref/lib/ref.js:747:11)
196
-
at Object.writePointer [as _writePointer] (../node_modules/ref/lib/ref.js:747:11)
197
-
at Object.writePointer [as _writePointer] (../node_modules/ref/lib/ref.js:747:11)
198
-
at Object.writePointer [as _writePointer] (../node_modules/ref/lib/ref.js:747:11)
199
-
at Object.writePointer [as _writePointer] (../node_modules/ref/lib/ref.js:747:11)
200
-
```
201
-
202
-
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.
203
-
204
-
If it is required to use Jest, a solution would be to fork `ref` and use npm shrinkwrap to installed a patched version.
205
-
206
-
### Running with ASAN
207
-
208
-
#### Linux
209
-
210
-
To run with google's AddressSanitizer tool, build with `-fsanitize=address` flag,
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.
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.
If you want to contribute code to this project, first you need to fork the
241
-
project. The next step is to send a pull request (PR) for review. The PR will be reviewed by the project team members. Once you have gained "Look Good To Me (LGTM)", the project maintainers will merge the PR.
0 commit comments