zeromq

zeromq

Users | From Source | Contributors and Development | Maintainers

zeromq: Your ready to use, prebuilt ØMQ bindings for Node.js.

ØMQ provides handy functionality when working with sockets. Yet, installing dependencies on your operating system or building ØMQ from source can lead to developer frustration.

zeromq simplifies creating communications for a Node.js application by providing well-tested, ready to use ØMQ bindings. zeromq supports all major operating systems, including:

• OS X/Darwin 64-bit
• Linux 64-bit
• Windows (64-bit and 32-bit)

Use zeromq and take advantage of the elegant simplicity of binaries.

Installation - Users

We rely on prebuild.

Install zeromq with the following:

npm install zeromq

Now, prepare to be amazed by the wonders of binaries.

Installation - From Source

If you want to use zeromq inside your Electron application or if you are working on a Linux 32-bit system, you have to build zeromq from source.

Prerequisites

Linux

• python (v2.7 recommended, v3.x.x is not supported)
• make
• A proper C/C++ compiler toolchain, like GCC

Use your distribution's package manager to install.

macOS

• python (v2.7 recommended, v3.x.x is not supported): already installed on Mac OS X
• Xcode Command Line Tools: Can be installed with xcode-select --install

Windows

• Option 1: Install all the required tools and configurations using Microsoft's windows-build-tools by running npm install -g windows-build-tools from an elevated PowerShell (run as Administrator).

• Option 2: Install dependencies and configuration manually

  1. Visual C++ Build Environment:

  • Option 1: Install Visual C++ Build Tools using the Default Install option.

  • Option 2: Install Visual Studio 2015 (or modify an existing installation) and select Common Tools for Visual C++ during setup.

  :bulb: [Windows Vista / 7 only] requires .NET Framework 4.5.1

  1. Install Python 2.7 or Miniconda 2.7 (v3.x.x is not supported), and run npm config set python python2.7
  2. Launch cmd, npm config set msvs_version 2015

Installation

Now you can install zeromq with the following:

npm install zeromq

Rebuilding for Electron

If you want to use zeromq inside your Electron application it needs to be rebuild against Electron headers.

We highly recommend electron-builder which handles this automatically.

If you don't want to use electron-builder you can rebuild zeromq manually by running:

npm rebuild zeromq --runtime=electron --target=1.4.5 --disturl=https://atom.io/download/atom-shell --build-from-source

Where target is your desired Electron version.

You can find more information on the Electron website.

Installation - Contributors and Development

To set up zeromq for development, fork this repository and clone your fork to your system.

Make sure you have the required dependencies for building zeromq from source installed.

Install a development version of zeromq with the following:

npm install

Testing

Run the test suite using:

npm test

Running an example application

Several example applications are found in the examples directory. Use node to run an example. To run the 'subber' application, enter the following:

node examples/subber.js

Examples using zeromq

Push/Pull

This example demonstrates how a producer pushes information onto a socket and how a worker pulls information from the socket.

producer.js

// producer.js
var zmq = require('zeromq')
  , sock = zmq.socket('push');

sock.bindSync('tcp://127.0.0.1:3000');
console.log('Producer bound to port 3000');

setInterval(function(){
  console.log('sending work');
  sock.send('some work');
}, 500);

worker.js

// worker.js
var zmq = require('zeromq')
  , sock = zmq.socket('pull');

sock.connect('tcp://127.0.0.1:3000');
console.log('Worker connected to port 3000');

sock.on('message', function(msg){
  console.log('work: %s', msg.toString());
});

Pub/Sub

This example demonstrates using zeromq in a classic Pub/Sub, Publisher/Subscriber, application.

Publisher: pubber.js

// pubber.js
var zmq = require('zeromq')
  , sock = zmq.socket('pub');

sock.bindSync('tcp://127.0.0.1:3000');
console.log('Publisher bound to port 3000');

setInterval(function(){
  console.log('sending a multipart message envelope');
  sock.send(['kitty cats', 'meow!']);
}, 500);

Subscriber: subber.js

// subber.js
var zmq = require('zeromq')
  , sock = zmq.socket('sub');

sock.connect('tcp://127.0.0.1:3000');
sock.subscribe('kitty cats');
console.log('Subscriber connected to port 3000');

sock.on('message', function(topic, message) {
  console.log('received a message related to:', topic, 'containing message:', message);
});

For maintainers: Creating a release

When making a release, do the following:

npm version minor && git push && git push --tags

Then, wait for the prebuilds to get uploaded for each OS. After the prebuilds are uploaded, run the following to publish the release:

npm publish

To check if the binaries are packaged correctly, you can push a commit to nteract/zmq-prebuilt-testing.