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

nbind is a set of headers that make your C++11 library accessible from JavaScript. With a single #include statement, your C++ compiler generates the necessary bindings without any additional tools. Your library is then usable as a Node.js addon or, if compiled to asm.js with Emscripten, directly in web pages without any plugins.

nbind works with the autogypi dependency management tool, which sets up node-gyp to compile your library without needing any configuration (other than listing your source code file names).

nbind is MIT licensed and based on templates and macros inspired by embind.

Quick start

C++ everywhere in 5 easy steps using Node.js, nbind and autogypi:

<table> <tr> <th>Starting point</th> <th>Step 1 - bind</th> <th>Step 2 - prepare</th> </tr><tr> <td valign="top">Original C++ code <a href="https://raw.githubusercontent.com/charto/nbind-example-minimal/master/hello.cc"><code>hello.cc</code></a>:<br> <pre>#include &lt;string&gt; #include &lt;iostream&gt; &nbsp; struct Greeter { static void sayHello( std::string name ) { std::cout &lt;&lt; "Hello, " &lt;&lt; name &lt;&lt; "!\n"; } };</pre></td> <td valign="top">List your <a href="#classes-and-constructors">classes</a> and <a href="#methods-and-properties">methods</a>:<br> <pre>// Your original code here &nbsp; // Add these below it: &nbsp; #include "nbind/nbind.h" &nbsp; NBIND_CLASS(Greeter) { method(sayHello); }</pre></td> <td valign="top"><a href="#creating-your-project">Add scripts</a> to <a href="https://raw.githubusercontent.com/charto/nbind-example-minimal/master/package.json"><code>package.json</code></a>:<br> <pre>{ "scripts": { "autogypi": "autogypi", "node-gyp": "node-gyp", "emcc-path": "emcc-path", "copyasm": "copyasm", "ndts": "ndts" } }</pre></td> </tr><tr> <th>Step 3 - install</th> <th>Step 4 - build</th> <th>Step 5 - use!</th> </tr><tr> <td valign="top">Run on the command line:<br> <pre>npm install --save \ nbind autogypi node-gyp &nbsp; npm run -- autogypi \ --init-gyp \ -p nbind -s hello.cc</pre></td> <td valign="top">Compile to native binary:<br> <pre>npm run -- node-gyp \ configure build</pre> Or to Asm.js:<br> <pre>npm run -- node-gyp \ configure build \ --asmjs=1</pre></td> <td valign="top">Call from Node.js:<br> <pre>var nbind = require('nbind'); var lib = nbind.init().lib; &nbsp; lib.Greeter.sayHello('you');</pre> Or from a web browser (<a href="#using-in-web-browsers">see below</a>). </td></tr> </table>

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 allows you to:

• 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

<table> <tr> <th>Target</th> <th colspan=2>Development platform</th> </tr><tr> <th></th> <th>Linux / OS X</th> <th>Windows</th> </tr><tr> <td>Native</td> <td> <a href="http://travis-ci.org/charto/nbind"> <img src="https://travis-ci.org/charto/nbind.svg?branch=master" alt="Build status"> </a> </td> <td> <a href="https://ci.appveyor.com/project/jjrv/nbind/branch/master"> <img src="https://ci.appveyor.com/api/projects/status/xu5ooh1m3mircpde/branch/master?svg=true" alt="Build status"> </a> </td> </tr><tr> <td>Asm.js</td> <td> <a href="http://travis-ci.org/charto/nbind-ci-emscripten"> <img src="https://travis-ci.org/charto/nbind-ci-emscripten.svg?branch=master" alt="Build status"> </a> </td> <td>Tested manually</td> </tr> </table>

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 versions should remain completely backwards-compatible between matching x and otherwise with minor changes. Breaking changes will be listed in release notes of versions where y equals 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 script in this package is just a wrapper, the actual emcc compiler binary should be in your path.

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 examples shown in this user guide are also available to download for easier testing as follows:

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 and node-gyp are all needed to compile a native Node.js addon from source when installing it. If you only distribute an asm.js version, you can use --save-dev instead of --save because users won't need to compile it.

Next, to run commands without installing them globally, it's practical to add them in the scripts section of your package.json that npm init just generated. Let's add an install script as well:

  "scripts":