Quick start | Requirements | Features | User guide | Contributing | License

nbind

#include

nbind

node-gyp

nbind

Quick start

C++ everywhere in 5 easy steps using Node.js,

nbind

#include <string>
#include <iostream>
 
struct Greeter {
  static void sayHello(
    std::string name
  ) {
    std::cout
      << "Hello, "
      << name << "!\n";
  }
};

// Your original code here
 
// Add these below it:
 
#include "nbind/nbind.h"
 
NBIND_CLASS(Greeter) {
  method(sayHello);
}

{
  "scripts": {
    "autogypi": "autogypi",
    "node-gyp": "node-gyp",
    "emcc-path": "emcc-path",
    "copyasm": "copyasm",
    "ndts": "ndts"
  }
}

npm install --save \
  nbind autogypi node-gyp
 
npm run -- autogypi \
  --init-gyp \
  -p nbind -s hello.cc

npm run -- node-gyp \
  configure build

npm run -- node-gyp \
  configure build \
  --asmjs=1

var nbind = require('nbind');
var lib = nbind.init().lib;
 
lib.Greeter.sayHello('you');

The above is all of the required code. Just copy and paste in the mentioned files and prompts or take a shortcut:

git clone https://github.com/charto/nbind-example-minimal.git
cd nbind-example-minimal
npm install && npm test

See it run!

(Note: nbind-example-universal is a better starting point for development)

Requirements

You need:

• Node.js 0.10.x - 7.x.x (newer may also work).
• Python 2.7, NOT 3.x (required by

  node-gyp

  , see instructions).

And one of the following C++ compilers:

• GCC 4.8 or above.
• Clang 3.6 or above.
• Emscripten 1.35.0 or above.
• Visual Studio 2015 (the Community version is fine).

Features

nbind

• Use your C++ API from JavaScript without any extra effort.
  • From Node.js, Electron and web browsers (using asm.js on Chrome, Firefox and Edge).
  • On Linux, OS X and Windows.
  • Without changes to your C++ code. Simply add a separate short description at the end.
• Distribute both native code and an asm.js fallback binary.
• Automatically generate TypeScript

  .d.ts

  definition files from C++ code for IDE autocompletion and compile-time checks of JavaScript side code.

In more detail:

• Export multiple C++ classes, even ones not visible from other files.
• Export C++ methods simply by mentioning their names.
• Auto-detect argument and return types from C++ declarations.
• Automatically convert types and data structures between languages.
• Call C++ methods from JavaScript with type checking.
• Pass JavaScript callbacks to C++ and call them with any types.
• Pass instances of compatible classes by value between languages (through the C++ stack).

The goal is to provide a stable API for binding C++ to JavaScript. All internals related to JavaScript engines are hidden away, and a single API already supports extremely different platforms.

Works on your platform

Target	Development platform
	Linux / OS X	Windows
Native
Asm.js		Tested manually

Roadmap

More is coming! Work is ongoing to:

• Precompile to a single native library for all versions Node.js and Electron on the same platform
  • Precompiled addons for different Node.js versions for efficiently calling the library will be provided with nbind
• Support native Android and iPhone apps.

Future

0.x.y

x

y

0

Contributing

Please report issues through Github and mention the platform you're targeting (Node.js, asm.js, Electron or something else). Pull requests are very welcome.

Warning: rebase is used within develop and feature branches (but not master).

When developing new features, writing tests first works best. If possible, please try to get them working on both Node.js and asm.js. Otherwise your pull request will get merged to Master only after maintainer(s) have fixed the other platform.

Installing Emscripten to develop for asm.js can be tricky. It will require Python 2.7 and setting paths correctly, please refer to Emscripten documentation. The

bin/emcc

emcc

You can rebuild the asm.js library and run tests as follows:

npm run clean-asm && npm run prepublish && npm run test-asm

User guide

• Installing the examples
• Creating your project
• Configuration
• Calling from Node.js
• Using nbind headers
• Functions
• Classes and constructors
• Inheritance ^{new in 0.3.5}
• Methods and properties
• Overloaded functions ^{new in 0.3.2}
• Getters and setters
• Passing data structures
• Callbacks
• Using objects
• Type conversion ^{updated in 0.3.2}
• Buffers ^{new in 0.3.1}
• 64-bit integers ^{new in 0.3.0}
• Error handling
• Publishing on npm
• Shipping an asm.js fallback
• Using in web browsers ^{updated in 0.3.0}
• Using with TypeScript ^{updated in 0.3.5}
• Binding plain C
• Binding external libraries
• Debugging
• Alternatives

Installing the examples

nbind

Extract this zip package or run:

git clone https://github.com/charto/nbind-examples.git

Enter the examples directory and install:

cd nbind-examples
npm install

Creating your project

Once you have all requirements installed, run:

npm init
npm install --save nbind autogypi node-gyp

nbind

autogypi

node-gyp

--save-dev

--save

Next, to run commands without installing them globally, it's practical to add them in the

scripts

package.json

npm init

  "scripts": {
    "autogypi": "autogypi",
    "node-gyp": "node-gyp",
    "emcc-path": "emcc-path",
    "copyasm": "copyasm",

"install": "autogypi && node-gyp configure build"
  }

emcc-path

nbind

node-gypi

The

install

autogypi

node-gyp

autogypi

nbind

nan

npm run -- autogypi --init-gyp -p nbind -s hello.cc

Replace

hello.cc

-s

The

-p nbind

nbind

-p

autogypi

The

--init-gyp

binding.gyp

autogypi.json

autogypi

node-gyp

install

Now you're ready to start writing code and compiling.

Configuration

Refer to autogypi documentation to set up dependencies of your package, and how other packages should include it if it's a library usable directly from C++.

--asmjs=1

nbind

node-gyp

node-gyp configure build --asmjs=1

Calling from Node.js

First

nbind

nbind.init

• Base path under which to look for compiled binaries. Default is

  process.cwd()

  and

  __dirname

  is a good alternative.
• Binary code exports object. Any classes from C++ API exported using

  nbind

  will be added as members. Default is an empty object. Any existing options will be seen by asm.js code and can be used to configure Emscripten output. Must follow base path (which may be set to

  null

  or

  undefined

  ).
• Node-style callback with 2 parameters:
  • Error if present, otherwise

    null

    .
  • Binary code exports object containing C++ classes.

nbind

var nbind = require('nbind');
var lib = nbind.init().lib;

// Use the library.

Using a callback also supports asynchronous initialization:

var nbind = require('nbind');

nbind.init(function(err, binding) {
  var lib = binding.lib;
  // Use the library.
});

The callback passed to init currently gets called synchronously in Node.js and asynchronously in browsers. To avoid releasing zalgo you can for example wrap the call in a bluebird promise:

var bluebird = require('bluebird');
var nbind = require('nbind');

bluebird.promisify(nbind.init)().then(function(binding) {
  var lib = binding.lib;
  // Use the library.
});

Using nbind headers

There are two possible files to include:

• nbind/api.h

  for using types from the

  nbind

  namespace such as JavaScript callbacks inside your C++ code.

  • #include

    before your own class definitions.
  • Causes your code to depend on

    nbind

    .

• nbind/nbind.h

  for exposing your C++ API to JavaScript.

  • #include

    after your own class definitions to avoid accidentally invoking its macros.
  • The header automatically hides itself if not targeting Node.js or asm.js.
  • Safe to use in any projects.

Use

#include "nbind/nbind.h"

construct

method

It's OK to include

nbind/nbind.h

node-gyp

BUILDING_NODE_EXTENSION

EMSCRIPTEN

Use

#include "nbind/api.h"

You can use an

#ifdef NBIND_CLASS

nbind

Example that uses an

nbind

1-headers.cc

#include 
#include 

// For nbind::cbFunction type.
#include "nbind/api.h"
class HeaderExample {
public:
  static void callJS(nbind::cbFunction &callback) {
    std::cout << "JS says: " << callback.call<:string>(1, 2, 3);
  }
};
// For NBIND_CLASS() and method() macros.
#include "nbind/nbind.h"
#ifdef NBIND_CLASS
NBIND_CLASS(HeaderExample) {
  method(callJS);
}
#endif
</:string>

Example used from JavaScript:

1-headers.js

var nbind = require('nbind');

var lib = nbind.init().lib;
lib.HeaderExample.callJS(function(a, b, c) {
  return('sum = ' + (a + b + c) + '\n');
});

Run the example with

node 1-headers.js

JS says: sum = 6

Functions

Functions not belonging to any class are exported inside an

NBIND_GLOBAL

function(functionName);

function(cppFunctionName, "jsExportedName");

If the C++ function is overloaded,

multifunction

Note: you cannot put several

function(...);

Example:

6-functions.cc

#include 

void sayHello(std::string name) {
  std::cout << "Hello, " << name << "!\n";
}
#include "nbind/nbind.h"
NBIND_GLOBAL() {
  function(sayHello);
}

Example used from JavaScript:

6-functions.js

var nbind = require('nbind');
var lib = nbind.init().lib;

lib.sayHello('you');

Classes and constructors

The

NBIND_CLASS(className)

The class can be renamed on the JavaScript side by passing a string as a second argument. This is especially useful for binding a template class specialization with a more reasonable name:

NBIND_CLASS(Data, "IntData")

Constructors are exported with a macro call

construct();

types

int, int

construct

Constructor arguments are the only types that

nbind

Example with different constructor argument counts and types:

2-classes.cc

#include 

class ClassExample {
public:
  ClassExample() {
    std::cout << "No arguments\n";
  }
  ClassExample(int a, int b) {
    std::cout << "Ints: " << a << " " << b << "\n";
  }
  ClassExample(const char *msg) {
    std::cout << "String: " << msg << "\n";
  }
};
#include "nbind/nbind.h"
NBIND_CLASS(ClassExample) {
  construct<>();
  construct();
  construct();
}

Example used from JavaScript:

2-classes.js

var nbind = require('nbind');

var lib = nbind.init().lib;
var a = new lib.ClassExample();
var b = new lib.ClassExample(42, 54);
var c = new lib.ClassExample("Don't panic");

Run the example with

node 2-classes.js

No arguments
Ints: 42 54
String: Don't panic

Inheritance

When a C++ class inherits another, the

inherit

Internally JavaScript only has prototype-based single inheritance while C++ supports multiple inheritance. To simulate it, nbind will use one parent class as the child class prototype, and copy the contents of the other parents to the prototype. This has otherwise the same effect, except the JavaScript

instanceof

true

Example:

NBIND_CLASS(Child) {
    inherit(FirstParent);
    inherit(SecondParent);
}

Methods and properties

Methods are exported inside an

NBIND_CLASS

method(methodName);

If the C++ method is overloaded,

multimethod

Properties should be accessed through getter and setter functions.

Data types of method arguments and its return value are detected automatically so you don't have to specify them. Note the supported data types because using other types may cause compiler errors that are difficult to understand.

If the method is

static

className.methodName()

obj = new className(); obj.methodName();

Example with a method that counts a cumulative checksum of ASCII character values in strings, and a static method that processes an entire array of strings:

3-methods.cc

#include 
#include 

class MethodExample {
public:
  unsigned int add(std::string part) {
    for(char &c : part) sum += c;
return(sum);
  }
  static std::vector check(std::vector<:string> list) {
    std::vector result;
    MethodExample example;
for(auto &amp;&amp;part : list) result.push_back(example.add(part));

return(result);
  }
  unsigned int sum = 0;
};
#include "nbind/nbind.h"
NBIND_CLASS(MethodExample) {
  construct<>();
  method(add);
  method(check);
}
</:string>

Example used from JavaScript, first calling a method in a loop from JS and then a static method returning an array:

3-methods.js

var nbind = require('nbind');

var lib = nbind.init().lib;
var parts = ['foo', 'bar', 'quux'];
var checker = new lib.MethodExample();
console.log(parts.map(function(part) {
  return(checker.add(part));
}));
console.log(lib.MethodExample.check(parts));

Run the example with

node 3-methods.js

[ 324, 633, 1100 ]
[ 324, 633, 1100 ]

The example serves to illustrate passing data. In practice, such simple calculations are faster to do in JavaScript rather than calling across languages because copying data is quite expensive.

Overloaded functions

The

function()

method()

multifunction()

multimethod()

Their second parameter is a list of argument types wrapped in an

args()

For example consider an overloaded method:

void test(unsigned int x) const;
void test(unsigned int x, unsigned int y) const;

In bindings, one of the versions needs to be explicitly selected. The second of the two would be referenced like:

multimethod(test, args(unsigned int, unsigned int));

As always, the return type and method constness are autodetected.

For calling from JavaScript, additionally each overload needs to have a distinct name. For renaming an overload JavaScript will see, the binding code is like:

multimethod(test, args(unsigned int, unsigned int), "test2");

You can then write a JavaScript wrapper to inspect arguments and select which overload to call. The reason for this is, that

nbind

Otherwise, it would need to generate a new C++ function that also checks the arguments. This would result in a larger native binary without any speed advantage.

Getters and setters

Property getters are exported inside an

NBIND_CLASS

getter(getterName)

nbind

get

Get

get_

Get_

getX

get_x

x

obj.x

Property setters are exported together with getters using a macro call

getset(getterName, setterName)

getter(getterName)

getterName

setterName

getX

set_x

++obj.x

Example class and property with a getter and setter:

4-getset.cc

class GetSetExample {

public:
  void setValue(int value) { this->value = value; }
  int getValue() { return(value); }
private:
  int value = 42;
};
#include "nbind/nbind.h"
NBIND_CLASS(GetSetExample) {
  construct<>();
  getset(getValue, setValue);
}

Example used from JavaScript:

4-getset.js

var nbind = require('nbind');

var lib = nbind.init().lib;
var obj = new lib.GetSetExample();
console.log(obj.value++); // 42
console.log(obj.value++); // 43

Run the example with

node 4-getset.js

Passing data structures

nbind

std::vector

std::array

Note that data structures don't use the same memory layout in both languages, so the data always gets copied which takes more time for more data. For example the strings in an array of strings also get copied, one character at a time. In asm.js data is copied twice, first to a temporary space using a common format both languages can read and write.

Callbacks

Callbacks can be passed to C++ methods by simply adding an argument of type

nbind::cbFunction &

They can be called with any number of any supported types without having to declare in any way what they accept. The JavaScript code will receive the parameters as JavaScript variables to do with them as it pleases.

A callback argument

arg

arg("foobar", 42);

arg.call("foobar", 42);

Warning: while callbacks are currently passed by reference, they're freed after the called C++ function returns! That's intended for synchronous functions like

Array.map

setTimeout

nbind::cbFunction

Using objects

C++ objects can be passed to and from JavaScript using different parameter and return types in C++ code:

• by reference using pointers or references (optionally

  const

  )
• by value

Note: currently passing objects by pointer on Node.js requires the class to have a "copy constructor" initializing itself from a pointer. This will probably be fixed later.

Returned pointers and references can be

const

Using pointers and references is particularly:

• dangerous because the pointer may become invalid without JavaScript noticing it.
• annoying in asm.js because browsers give no access to the garbage collector, so memory may leak when pointers become garbage without C++ noticing it. Smart pointers are not supported until a workaround for this is implemented.

Passing data by value using value objects solves both issues. They're based on a

toJS

fromJS

The callback on the C++ side is of type

nbind::cbOutput

nbind

The equivalent JavaScript constructor must be registered on the JavaScript side by calling

binding.bind('CppClassName', JSClassName)

nbind

Example with a class

Coord

ObjectExample

5-objects.cc

#include 

#include "nbind/api.h"
class Coord {
public:
  Coord(signed int x = 0, signed int y = 0) : x(x), y(y) {}
  explicit Coord(const Coord *other) : x(other->x), y(other->y) {}
  void toJS(nbind::cbOutput output) {
    output(x, y);
  }
  signed int getX() { std::cout << "Get X\n"; return(x); }
  signed int getY() { std::cout << "Get Y\n"; return(y); }
  void setX(signed int x) { this->x = x; }
  void setY(signed int y) { this->y = y; }
  signed int x, y;
};
class ObjectExample {
public:
  static void showByValue(Coord coord) {
    std::cout << "C++ value " << coord.x << ", " << coord.y << "\n";
  }
  static void showByRef(Coord *coord) {
    std::cout << "C++ ref " << coord->x << ", " << coord->y << "\n";
  }
  static Coord getValue() {
    return(Coord(12, 34));
  }
  static Coord *getRef() {
    static Coord coord(56, 78);
    return(&coord);
  }
};
#include "nbind/nbind.h"
NBIND_CLASS(Coord) {
  construct<>();
  construct();
  construct();
  getset(getX, setX);
  getset(getY, setY);
}
NBIND_CLASS(ObjectExample) {
  method(showByValue);
  method(showByRef);
  method(getValue);
  method(getRef);
}

Example used from JavaScript:

5-objects.js

var nbind = require('nbind');

var binding = nbind.init();
var lib = binding.lib;
function Coord(x, y) {
  this.x = x;
  this.y = y;
}
Coord.prototype.fromJS = function(output) {
  output(this.x, this.y);
}
Coord.prototype.show = function() {
  console.log('JS value ' + this.x + ', ' + this.y);
}
binding.bind('Coord', Coord);
var value1 = new Coord(123, 456);
var value2 = lib.ObjectExample.getValue();
var ref = lib.ObjectExample.getRef();
lib.ObjectExample.showByValue(value1);
lib.ObjectExample.showByValue(value2);
value1.show();
value2.show();
lib.ObjectExample.showByRef(ref);
console.log('JS ref ' + ref.x + ', ' + ref.y);

Run the example with

node 5-objects.js

C++ value 123, 456
C++ value 12, 34
JS value 123, 456
JS value 12, 34
C++ ref 56, 78
Get X
Get Y
JS ref 56, 78

Type conversion

Parameters and return values of function calls between languages are automatically converted between equivalent types:

| JavaScript | C++ | | ---------- | ------------------------------------------- | | number | (

un

signed char

short

int

long

float

double

un

signed long

long long

bool

const

unsigned

char *

std::string

std::vector

std::array

nbind::cbFunction

nbind::Buffer

Type conversion is customizable by passing policies as additional arguments to

construct

function

method

NBIND_CLASS

NBIND_GLOBAL

• nbind::Nullable()

  allows passing

  null

  as an argument when a C++ class instance is expected. The C++ function will then receive a

  nullptr

  .

• nbind::Strict()

  enables stricter type checking. Normally anything in JavaScript can be converted to

  number

  ,

  string

  or

  boolean

  when expected by a C++ function. This policy requires passing the exact JavaScript type instead.

Type conversion policies are listed after the method or function names, for example:

NBIND_CLASS(Reference) {
    method(reticulateSplines, "reticulate", nbind::Nullable());
    method(printString, nbind::Strict());
}

Buffers

Transferring large chunks of data between languages is fastest using typed arrays or Node.js buffers in JavaScript. Both are accessible from C++ as plain blocks of memory if passed in through the

nbind::Buffer

• data()

  returns an

  unsigned char *

  pointing to a block of memory also seen by JavaScript.

• length()

  returns the length of the block in bytes.

• commit()

  copies data from C++ back to JavaScript (only needed with Emscripten).

This is especially useful for passing

canvas.getContext('2d').getImageData(...).data

Example:

#include "nbind/api.h"

void range(nbind::Buffer buf) {
  size_t length = buf.length();
  unsigned char *data = buf.data();
  if(!data || !length) return;
  for(size_t pos = 0; pos < length; ++pos) {
    data[pos] = pos;
  }
  buf.commit();
}
#include "nbind/nbind.h"
NBIND_GLOBAL() {
  function(range);
}

Example used from JavaScript:

var nbind = require('nbind');
var lib = nbind.init().lib;

var data = new Uint8Array(16);
lib.range(data);
console.log(data.join(' '));

It prints:

0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

64-bit integers

Normally C++ 64-bit integer types are first converted to

double

• Integer containing 32 bits from the least important half.
• Integer containing 32 bits from the most important half.
• Boolean, true if the number is negative.

It should also have a

fromJS

An example implementation also capable of printing 64-bit numbers to strings in bases 2, 4, 10 and 16 is included.

Error handling

You can use the

NBIND_ERR("message here");

#include "nbind/api.h"

Publishing on npm

Make sure your

package.json

emcc-path

install

  "scripts": {
    "emcc-path": "emcc-path",

"install": "autogypi && node-gyp configure build"
  }

The

dependencies

  "dependencies": {
    "autogypi": "^0.2.2",
    "nbind": "^0.2.1",
    "node-gyp": "^3.3.1"
  }

Your package should also include

binding.gyp

autogypi.json

Shipping an asm.js fallback

nbind-example-universal is a good minimal example of compiling a native Node.js addon if possible, and otherwise using a pre-compiled asm.js version.

It has two temporary build directories

build/native

build/asmjs

nbind

copyasm

Note that the native version should be compiled in the

install

prepublish

package.json

Using in web browsers

nbind-example-universal is a good minimal example also of calling compiled asm.js code from inside web browsers. The simplest way to get

nbind

index.html

Make sure to fix the path to

nbind.js

Using with TypeScript

nbind

.d.ts

All you have to do is compile your C++ code and run the included

ndts

npm run -- node-gyp configure build
npm run -s -- ndts . > lib-types.d.ts

When run in this way, the first argument of

ndts

binding.gyp

.

Now you can load the C++ code from TypeScript in three different ways. First import

nbind

ndts

import * as nbind from 'nbind';
import * as LibTypes from './lib-types';

Then choose your favorite way to initialize it:

Purely synchronous:

const lib = nbind.init().lib;

// Use the library.

Asynchronous-aware:

nbind.init((err: any, binding: nbind.Binding) => {
  const lib = binding.lib;

  // Use the library.
});

Promise-based:

import * as bluebird from 'bluebird';

bluebird.promisify(nbind.init)().then((binding: nbind.Binding) => {
  const lib = binding.lib;
  // Use the library.
});

Note how there is a type argument

binding.lib

ndts

For example if you have a C++ class:

struct C : public A, public B {
    A *getA();

static uint32_t reticulate();
};

And bind it like:

NBIND_CLASS(C) {
    inherit(A);
    inherit(B);

construct<>();

method(reticulate);

getter(getA);
}

ndts

export interface _C extends A, B {}
export var _C: { new(): _C };

export class C extends _C {
    /** C(); */
    constructor();
/** static uint32_t reticulate(); */
static reticulate(): number;

/** A * a; -- Read-only */
a: A;
}

The additional interface

_C

C

A

B

All the tests are written in TypeScript so if you run:

git clone https://github.com/charto/nbind.git
cd nbind
npm install
npm test

You can then open

test/test.ts

Binding plain C

nbind generates bindings using C++ templates for compile-time introspection of argument and return types of functions and methods.

Since plain C doesn't have templates, there's no standard way to have a C compiler generate new wrapper code for type conversion and output type information available at run-time.

The easiest way to use nbind with C is to write a C++ wrapper calling the C code, and use nbind with that.

Mapping idiomatic C to JavaScript classes may require some manual work, since it's common to reinvent new ways to do object-oriented programming, usually by using structs as classes and simulating methods by passing struct pointers to functions. C++ classes and methods should be used for these.

A good example is libui-node which uses nbind to generate bindings for libui, mainly a C library.

Binding external libraries

If you have external library source code, you should compile it separately into a library first, and then link your Node.js addon with it. If the library has an installation script and the addon is only intended for your own use or other users are willing to do some extra steps, it's easiest to install the library globally first.

For best user experience, libui-node is an example of distributing an external library together with your package.

For creating the actual bindings, see for example this and this message and a tutorial for getting the

vg

Debugging

In the browser it can be difficult to stop and debug at the correct spot in optimized C++ code.

nbind

_nbind_debug()

api.h

For debugging a Node.js addon, if you would normally test it like

node test.js

gdb node

run test.js

You should also modify

nbind.gypi

src

binding.gyp

-O?

-g

build

Alternatives

Very similar:

• Embind
• v8pp

Less similar:

• libembindcefv8
• node-ffi
• cbind
• cpgf
• n2o

Authors

• Juha Järvi, befunge

License

The MIT License

Copyright (c) 2014-2017 BusFaster Ltd