Improve UX of msg generation process (#759)

This patch implements:

- define a npm binary script in package.json named generate-messages
- add #! details to generate_messages.js script
- add section to FAQ.md describing how to generate messages
- added test case that runs the generate-messages script from root folder of a new node pkg, 
  <my_pkg>/node_modules/.bin/generate-messages

Fix #750

Author: wayneparrott

README.md

@@ -5,7 +5,10 @@
 | develop | [![Build Status](https://travis-ci.org/RobotWebTools/rclnodejs.svg?branch=develop)](https://travis-ci.org/RobotWebTools/rclnodejs) | [![macOS Build Status](https://circleci.com/gh/RobotWebTools/rclnodejs/tree/develop.svg?style=shield)](https://circleci.com/gh/RobotWebTools/rclnodejs) | [![Build status](https://ci.appveyor.com/api/projects/status/upbc7tavdag1aa5e/branch/develop?svg=true)](https://ci.appveyor.com/project/minggangw/rclnodejs/branch/develop) |
 | master  | [![Build Status](https://travis-ci.org/RobotWebTools/rclnodejs.svg?branch=master)](https://travis-ci.org/RobotWebTools/rclnodejs)  | [![macOS Build Status](https://circleci.com/gh/RobotWebTools/rclnodejs/tree/master.svg?style=shield)](https://circleci.com/gh/RobotWebTools/rclnodejs)  |  [![Build status](https://ci.appveyor.com/api/projects/status/upbc7tavdag1aa5e/branch/master?svg=true)](https://ci.appveyor.com/project/minggangw/rclnodejs/branch/master)  |
 
-`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.
+**rclnodejs** is a Node.js client library for the Robot Operating System 
+([ROS 2](https://index.ros.org/doc/ros2/)). It provides a JavaScript API 
+and tooling for ROS 2 programming. TypeScript declarations, i.e., (*.d.ts), 
+are included to support use in TypeScript projects.
 
 Here's an example for how to create a ROS 2 node that publishes a string message in a few lines of JavaScript.
 
@@ -67,12 +70,11 @@ npm i [email protected]
 
 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`.
 
-## Using TypeScript
+## Using rclnodejs with TypeScript
 
 `rclnodejs` API can be used in TypeScript projects. You can find the TypeScript declaration files (\*.d.ts) in the `types/` folder.
 
-Your project `tsconfig.json` file should include the following compiler options:
-
+Your `tsconfig.json` file should include the following compiler options:
 ```jsonc
 {
   "compilerOptions": {
@@ -96,17 +98,57 @@ rclnodejs.init().then(() => {
 });
 ```
 
-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.
+The benefits of using TypeScript become evident when working with more complex use-cases. ROS messages are defined in the `types/interfaces.d.ts` module. This module is updated as part of the `generate-messages` process described in the next section. 
 
-```typescript
-const msg: rclnodejs.std_msgs.msg.String = {
-  data: 'hello ROS2 from rclnodejs',
-};
+## ROS2 Interface Message Generation (important)
+ROS components communicate by sending and receiving messages described 
+by the interface definition language (IDL). ROS client libraries such as 
+rclnodejs are responsible for converting these IDL message descriptions 
+into source code of their target language. For this, rclnodejs provides 
+the `generate-messages` npm script that reads in the IDL 
+messages files of a ROS environment and generates corresponding JavaScript 
+message interface files. Additionally, the tool generates the TypeScript 
+`interface.d.ts` file containing declarations for every IDL message file 
+processed. 
+
+Learn more about ROS interfaces and IDL [here](https://index.ros.org/doc/ros2/Concepts/About-ROS-Interfaces/).
+
+In the following example rclnodejs loads a generated JavaScript message file corresponding to the ROS `std_msgs/msg/String' definition.
+
+```
+import * as rclnodejs from 'rclnodejs';
+let stringMsgObject = rclnodejs.createMessageObject('std_msgs/msg/String');
+stringMsgObject.data = 'hello world';
+```
+
+### Maintaining Generated JavaScript Message Files
+Message files are generated as a post-install step of the rclnodejs 
+installation process. Thereafter, you will need to manually run the 
+message generation script when new ROS message packages are installed 
+for which your ROS2-nodejs project has a dependency. 
+
+### Running `generate-messages` Utility
+To use `generate-messages` from your Nodejs package, create an npm 
+script entry in your package.json file as shown:
+
+```
+"scripts": {
+  "generate-messages": "generate-messages"
+  // your other scripts here
+}
+````
+
+To run the script use `npm` as follows:
 ```
+npm run generate-messages
+```
+The newly generated JavaScript files can be found at 
+`<yourproject>/node_modules/rclnodejs/generated/`.
+
 
 ## Contributing
 
-Please make sure to read the [Contributing Guide]() before making a pull request.
+Please read the [Contributing Guide]() before making a pull request.
 
 Thank you to all the [people](CONTRIBUTORS.md) who already contributed to rclnodejs!
 

docs/FAQ.md

@@ -15,14 +15,9 @@ 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 regenerate messages by either 1) reinstalling rclnodejs which will regenerate all JavaScript and TypeScript files as a post-install step:
-
-```
-npm i rclnodejs
-```
-or use the `rclnodejs cli` to generate JavaScript message files
+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:
 ```
-rclnodejs generate-ros-messages
+<your_project>/node_modules/.bin/generate-messages
 ```
 
 

package.json

@@ -21,6 +21,9 @@
     "postinstall": "node scripts/generate_messages.js",
     "format": "clang-format -i -style=file ./src/*.cpp ./src/*.hpp && prettier --write \"{lib,rosidl_gen,rostsd_gen,rosidl_parser,types,example,test,scripts,benchmark}/**/*.{js,md,ts}\" ./*.{js,md,ts}"
   },
+  "bin": {
+    "generate-messages": "./scripts/generate_messages.js"
+  },
   "authors": [
     "Minggang Wang <[email protected]>",
     "Kenny Yuan <[email protected]>",

scripts/generate_messages.js

@@ -1,3 +1,5 @@
+#!/usr/bin/env node
+
 /* eslint-disable camelcase */
 // Copyright (c) 2018 Intel Corporation. All rights reserved.
 

test/test-generate-messages-bin.js

@@ -0,0 +1,120 @@
+// Copyright (c) 2021 Wayne Parrott. All rights reserved.
+//
+// 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 assert = require('assert');
+const childProcess = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const rclnodejs = require('../index.js');
+
+const GEN_FOLDER = 'generated';
+const SCRIPT_NAME = 'generate-messages';
+
+describe('rclnodejs generate-messages binary-script tests', function () {
+  let cwd;
+  let tmpPkg;
+
+  this.timeout(90 * 1000); // 90 seconds to run this test suite
+
+  // Create a test pkg wtih rclnodejs dependency
+  //   create test package folder
+  //   run 'npm init' to create package.xml with rclnodejs as dependency
+  //   run 'npm pack' on rclnodejs saving into test package
+  //   in test package install from rclnodejs.x.y.z.tgz
+  //   delete generated/ folder as this will be generated as part of a test
+  before(function () {
+    this.cwd = process.cwd(); // back up rclnodejs path
+    let tmpDir = os.tmpdir();
+    this.tmpPkg = path.join(tmpDir, 'rclnodejs_test');
+    while (fs.existsSync(this.tmpPkg)) {
+      this.tmpPkg += Math.trunc(Math.random() * 100);
+    }
+
+    fs.mkdirSync(this.tmpPkg);
+
+    childProcess.spawnSync('npm', ['init', '-y'], {
+      stdio: 'inherit',
+      shell: true,
+      cwd: this.tmpPkg,
+    });
+    childProcess.spawnSync('npm', ['pack', this.cwd], {
+      stdio: 'inherit',
+      shell: true,
+      cwd: this.tmpPkg,
+    });
+
+    let tgz;
+    const regex = /^rclnodejs-\d+.\d+.\d+.tgz/;
+    for (let file of fs.readdirSync(this.tmpPkg)) {
+      if (file.match(regex)) {
+        tgz = file;
+        break;
+      }
+    }
+    if (!tgz) {
+      console.error('ERROR: unable to successfully run npm pack');
+      return;
+    }
+    let tgzPath = path.join(this.tmpPkg, tgz);
+    childProcess.spawnSync('npm', ['install', tgzPath], {
+      stdio: 'inherit',
+      shell: true,
+      cwd: this.tmpPkg,
+    });
+
+    let generatedFolderPath = createGeneratedFolderPath(this.tmpPkg);
+    if (fs.existsSync(generatedFolderPath)) {
+      fs.rmdirSync(generatedFolderPath, { recursive: true });
+    }
+  });
+
+  after(function () {
+    // recursively remove test package folder
+    fs.rmdirSync(this.tmpPkg, { recursive: true });
+  });
+
+  it('test generate-messages script installation', function (done) {
+    // confirm script is installed at <pgk>/node_modules/.bin/<script>
+    let script = createScriptFolderPath(this.tmpPkg);
+    assert.ok(fs.existsSync(script));
+    done();
+  });
+
+  it('test generate-messages script operation', function (done) {
+    let script = createScriptFolderPath(this.tmpPkg);
+    childProcess.spawnSync(script, [], { stdio: 'inherit', shell: true });
+
+    let generatedFolderPath = createGeneratedFolderPath(this.tmpPkg);
+    assert.ok(
+      fs.existsSync(generatedFolderPath),
+      'No generated message folder found'
+    );
+    assert.ok(
+      fs.existsSync(path.join(generatedFolderPath, 'std_msgs')),
+      'std_msgs folder found'
+    );
+    done();
+  });
+});
+
+function createGeneratedFolderPath(pkgFolder) {
+  return path.join(pkgFolder, 'node_modules', 'rclnodejs', GEN_FOLDER);
+}
+
+function createScriptFolderPath(pkgFolder) {
+  return path.join(pkgFolder, 'node_modules', '.bin', SCRIPT_NAME);
+}