mmir-tooling v7.0.0-beta5

mmir-tooling

The mmir-tooling repository holds files, resources etc. for building mmir-based applications.

Overview:

• API Documentation
• Prerequisites
• Basic Project Setup
• Installation
• Webpack Build Integration
• Cordova Build Integration
• "Bare-bones" mmir-lib Integration
• Manual Build Script
• Versioning Note
• Development

API Documentation

See generated API documentation (or more detailed HTML documentation) and details below.

Prerequisites

• Node.js (version 10.x or later)
• mmir-lib:

  npm install mmir-lib

Basic Project Setup

See Versioning Note below, for compatibility with mmir-lib versions.

By default the build process will assume that the mmir-based application is located at www/ and follows the default structure of a mmir-based project:

www/config/
          configuration.json
          languages/
                    <lang1>/grammar.json
                            speech.json
                            dictionary.json
                    <lang2>/grammar.json
                            speech.json
                            dictionary.json
          states/
                 dialog.xml
                 input.xml
www/controller/*
www/views/*
...

If the mmir resources are located in different directories/files, they need to be specified in the build configuration (see examples below for setting option resourcesPath).

Installation

Install mmir-tooling via npm.

From npm registry

npm install -D mmir-tooling

Or latest development version from github

npm install -D git+https://github.com/mmig/mmir-tooling.git

See sections below for integrating mmir-lib into various frameworks / build-systems.

For a setup without a (supported) build-system or framework, see section "Bare-bones" mmir-lib Integration.

Webpack Build Integration

For webpack-based applications, mmir-webpack can be used.

Cordova Build Integration

NOTE if the cordova app is packaged by webpack, the mmir-webpack integration should be used instead (see section above).

For automatically building the mmir resources in a cordova-based app, the build-script mmir-tooling/utils/cordova-build-tool.js can be included as prepare hook, i.e. in config.xml:

<hook type="before_prepare" src="node_modules/mmir-tooling/utils/cordova-build-tool.js" />

This will by default parse the www/ directory for mmir resources (grammars, dictionaries, view templates, etc) and compile them if necessary. Note, this would be the same build configuration as using {resourcesPath: projectRootDir + '/www'}.

Optionally, additional build configuration for mmir can be specified by creating the file mmir.build.config.js (in the project root) in which the mmir build configuration is exported via module.exports, e.g. something like

var path = require('path');

//custom options for grammars
const grammarOptions = {

  // parse directory test-data/grammars/ for JSON grammar definitions
  //  (instead of default (see below) <resourcesPath>/config/languages/)
  path: path.resolve(__dirname, 'test-data/grammars'),
  // use grammar engine 'pegjs' for compiling grammars (instead of default 'jscc')
  engine: 'pegjs',
  // set some custom per-grammar options:
  //  the grammar IDs are derived from the directory name when parsing the path, i.e.
  //  test-data/grammars/<grammar ID>/grammar.json
  grammars: {
    //do ignore grammar for "ja" (i.e. not load when app starts)
    ja: {ignore: true},
    //do completly exclude (i.e. not compile) grammar for "de"
    de: {exclude: true},
    //use grammar engine 'jscc' for grammar "en" (instead of general configured 'pegjs')
    en: {engine: 'jscc'},
    //for grammar "testing": specify JSON grammar file directly & use grammar engine 'jison'
    testing: {engine: 'jison', file: path.resolve(__dirname, 'custom/my-testing-grammar.json')}
  }
};

//custom options for state models
var stateOptions = {
  models: {
    //compile custom state machine calendarStates from SCXML definition at
    // test-data/states/calendarDescriptionSCXML.xml
    calendarStates: {
      file: path.resolve(__dirname, 'test-data/states/calendarDescriptionSCXML.xml')
    }
  }
};

const mmirAppConfig = {

  //instead of parsing 'www/', parse directory 'mmir-res/' for mmir resources
  resourcesPath: path.resolve(__dirname, 'mmir-res'),

  //set custom options for grammars in build configuration
  grammars: grammarOptions,

  //set custom options for state machines in build configuration
  states: stateOptions
};

module.exports = mmirAppConfig;

NOTE: if the cordova app is built with webpack, the mmir-webpack integration should be used instead.

"Bare-bones" mmir-lib Integration

If the application does not use a build-system like webpack, and cannot utilize the node / npm package directly, the mmir-lib library files can be simply copied into the application directory:
copy the mmir-lib/lib/ directory into a sub-directory mmirf/ of the application directory.

Alternatively, mmir-tooling provides the simple command line tool mmirinstall for this:
the following steps would install the mmir-lib library files into the application directory www/mmirf/

1. install mmir and mmir-lib via npm

   # install mmir-lib
   npm install mmir-lib --save
   # install mmir-tooling
   npm install mmir-tooling --save-dev

2. copy mmir-lib library files using mmir-tooling's helper mmirinstall, e.g.
   • directly via command line ...
     (if used in an npm script, the relative path to mmirinstall can be omitted)
     • on Windows

       node_modules\.bin\mmirinstall www/mmirf

     • on *nix

       node_modules/.bin/mmirinstall www/mmirf

   • ... or as npm script:
     • add scripts entry in the package.json of the application:

       "scripts": {
         "install-mmir-lib": "mmirinstall www/mmirf"
       },

     • run script via npm

       npm run install-mmir-lib

NOTE if mmir-lib is included in a web page "as is", using its built-in requirejs mechanism, the library files are expected in the sub-directory/path mmirf/ (w.r.t. to the including web page). If the library files are located somewhere different, the mmir-lib configuration needs explicitly specifiy the corresponding location.

Manual Build Script

• install mmir-tooling via npm:
  (re-)build resources like grammars after creation/modification, e.g. with simple script

  var path = require('path');
  var buildTools = require('mmir-tooling');
  
  var buildConfig = {
    //parses path src/mmir-res/ for mmir resources
    resourcesPath: path.join(__dirname, 'src/mmir-res'),
    //stores the compiled resources into dist/
    //NOTE: this will create corresponding sub directories if necessary,
    //      e.g for compiled grammars etc
    targetDir: path.join(__dirname, 'dist')
  };
  
  buildTools.apply(buildConfig).then(function(errors){
    var errMsg = errors.join('\n');
    console.log('Finished compiling resources'+(errMsg? ', with errors: ' +errMsg : ''));
  });

  The resourcePath will be searched for mmir resources that need to be built (see documentation for more details).

  By default, the built resources will be stored in /www/gen/**, or you can use targetDir in the build configuration for specifying a different directory

  var buildConfig = {
    targetDir: path.join(__dirname, 'dist')
    resourcesPath: path.join(__dirname, 'www')
  };

  which would store the built resources into /dist/gen/**.

Versioning Note

The major and minor version number of mmir-tooling matches the compatible verison of mmir-lib, i.e. mmir-tooling X.Y.i is compatible with mmir-lib X.Y.j.

Development

The mmir-tooling sources are located in

assets\**  # non-TypeScript resources, and "overwrite" resources
src\**     # TypeScript sources

(outher resources will be generated/overwritten when running npm run build)

For including new libraries to mmir-lib (or updating/modifying existing vendor/generated libraries), see mmir-lib-dev