Node-Switcher

Node-Switcher is the native NodeJS add-on for Switcher. It acts as a thin wrapper around Switcher's C++ API, allowing it to be included in Javascript applications. In the context of the Scenic stack, Node-Switcher is the link allowing Scenic Core to communicate with Switcher.

Node-Switcher is currently developed by the Société des Arts Technologiques [SAT], a non-profit artistic entity based in Montreal, CA. The current version of Node-Switcher has been tested with Ubuntu 18.04.

Installation

Dependencies

IMPORTANT: Take note that Node-Switcher 3.2.x is only compatible with Switcher 2.1.24 and up. Use Node-Switcher 3.1.2 if you plan to use a version of Switcher lower than 2.1.24.

Install with Scenic Core

Node-Switcher is specified as a dependency in Scenic Core's package.json. This means that Node-Switcher will be automatically downloaded, built and installed as part of Scenic Core's install process.

See Scenic Core's installation procedure for more information.

Install from Source

Additional Scripts

Additional NPM scripts are available to build the add-on:

node-gyp configure # configure node-gyp (optionnal) 
 
npm run build
npm run build:debug # build for debug 
npm run rebuild
npm run rebuild:debug # rebuild for debug 

Install from Docker

The default Docker configuration uses the images built from Switcher. Docker-compose will fetch the develop branches from shmdata, switcher and node-switcher.

# Build the whole stack 
docker-compose -f container/docker-compose.yml up

Build a Docker image

To build a Docker image of Node-Switcher, you'll need to build the Shmdata and Switcher images beforehand..

# Build node-switcher's image 
docker build -t "node-switcher:develop" .

The node-switcher image uses [mutli-stage builds][docker-multi-stage] with 4 stages : dependencies, nodejs, build and clean. Theses stages use some build arguments :

The node-switcher instance could be executed directly with its REPL :

docker run -ti node-switcher:develop node-switcher-repl

Usage

Javascript Scripting

Node-Switcher allows you to write JavaScript scripts to control Switcher. For example, you can use it to create quiddities, change a quiddity's properties, establish SIP communication with others, etc.

Example:

const Switcher = require('node-switcher').Switcher
 
const sw = new Switcher('debug', console.log)
 
// create a new quiddity `jacksrc`
sw.create('jacksrc')

You can see all examples in the folder example.

REPL Interface

You can also use a Read-Eval-Print Loop (REPL) in order to test Node-Switcher in the terminal. Type the following command in your terminal to do so:

# Inside node-switcher/ 
./bin/repl.js

Debugging

The following Visual Studio Code debug task can help you debug Node-Switcher. lldb and the vadimcn.vscode-lldb VSCode extension must be installed before running this task.

{
  "configurations": [{
    "name": "Node Switcher (lldb)",
    "type": "lldb",
    "request": "launch",
    "program": "${env:HOME}/.bin/node",
    "args": [
      "${workspaceFolder:node-switcher}/examples/debug.js"
    ],
    "preLaunchTask": "npm: build:dev"
  }]
}

Technologies

This add-on uses C++ 17 and NodeJS >= 10.

The SAT uses Ubuntu 18.04, so testing priority is given to this version.

Documentation

The NodeJs API is documented with source comments into cpp files. The documentation can be generated with JSDoc by running the command :

npm run doc

Contributing

Check out our Contributing Guide to get started!

Versioning

SemVer is used for versioning. For the versions available, see the tags on this repository.

Authors

See here.

License

This project is licensed under the GNU General Public License version 3 - see the LICENSE file for details.

Acknowledgments

This project was made possible by the Société des Arts Technologiques [SAT].