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.
C++ everywhere in 5 easy steps using Node.js, nbind and autogypi:
| Starting point | Step 1 - bind | Step 2 - prepare |
|---|---|---|
Original C++ code hello.cc:#include <string>
#include <iostream>
struct Greeter {
static void sayHello(
std::string name
) {
std::cout
<< "Hello, "
<< name << "!\n";
}
}; | List your classes and methods:// Your original code here
// Add these below it:
#include "nbind/nbind.h"
NBIND_CLASS(Greeter) {
method(sayHello);
} | Add scripts to package.json:{
"scripts": {
"autogypi": "autogypi",
"node-gyp": "node-gyp",
"emcc-path": "emcc-path",
"copyasm": "copyasm",
"ndts": "ndts"
}
} |
| Step 3 - install | Step 4 - build | Step 5 - use! |
Run on the command line:npm install --save \ nbind autogypi node-gyp npm run -- autogypi \ --init-gyp \ -p nbind -s hello.cc | Compile to native binary:npm run -- node-gyp \ configure buildOr to Asm.js: npm run -- node-gyp \ configure build \ --asmjs=1 | Call from Node.js:var nbind = require('nbind');
var lib = nbind.init().lib;
lib.Greeter.sayHello('you');
Or from a web browser (see below).
|
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)
You need:
node-gyp, see instructions).And one of the following C++ compilers:
nbind allows you to:
.d.ts definition files from C++ code for IDE autocompletion and compile-time checks of JavaScript side code.In more detail:
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.
| Target | Development platform | |
|---|---|---|
| Linux / OS X | Windows | |
| Native |
|
|
| Asm.js |
| Tested manually |
More is coming! Work is ongoing to:
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.
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
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
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": {
"autogypi": "autogypi",
"node-gyp": "node-gyp",
"emcc-path": "emcc-path",
"copyasm": "copyasm",
"install": "autogypi && node-gyp configure build"
}
emcc-path is needed internally by nbind when compiling for asm.js.
It fixes some command line options that node-gypi generates on OS X
and the Emscripten compiler doesn't like.
You can leave it out if only compiling native addons.
The install script runs when anyone installs your package.
It calls autogypi and then uses node-gyp to compile a native addon.
autogypi uses npm package information to set correct include paths
for C/C++ compilers. It's needed when distributing addons on npm
so the compiler can find header files from the nbind and nan packages
installed on the user's machine. Initialize it like this:
npm run -- autogypi --init-gyp -p nbind -s hello.cc
Replace hello.cc with the name of your C++ source file.
You can add multiple -s options, one for each source file.
The -p nbind means the C++ code uses nbind. Multiple -p
options can be added to add any other packages compatible with autogypi.
The --init-gyp command generates files binding.gyp and autogypi.json
that you should distribute with your package, so that autogypi and node-gyp
will know what to do when the install script runs.
Now you're ready to start writing code and compiling.
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 is the only existing configuration option for nbind itself.
You pass it to node-gyp by calling it like node-gyp configure build --asmjs=1.
It compiles your package using Emscripten instead of your default C++ compiler
and produces asm.js output.
First nbind needs to be initialized by calling nbind.init which takes
the following optional arguments:
process.cwd() and __dirname is a good alternative.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).null.nbind can be initialized synchronously on Node.js and asynchronously on
browsers and Node.js. Purely synchronous is easier but not as future-proof:
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.
});
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.nbind.nbind/nbind.h for exposing your C++ API to JavaScript.
#include after your own class definitions to avoid accidentally invoking its macros.Use #include "nbind/nbind.h" at the end of your source file with only the bindings after it.
The header defines macros with names like construct and method that may otherwise break
your code or conflict with other headers.
It's OK to include nbind/nbind.h also when not targeting any JavaScript environment.
node-gyp defines a BUILDING_NODE_EXTENSION macro and Emscripten defines an EMSCRIPTEN macro
so when those are undefined, the include file does nothing.
Use #include "nbind/api.h" in your header files to use types in the nbind namespace
if you need to report errors without throwing exceptions,
or want to pass around callbacks or objects.
You can use an #ifdef NBIND_CLASS guard to skip your nbind export definitions when the headers weren't loaded.
Example that uses an nbind callback in C++ code:
#include <string>
#include <iostream>
// For nbind::cbFunction type.
#include "nbind/api.h"
class HeaderExample {
public:
static void callJS(nbind::cbFunction &callback) {
std::cout << "JS says: " << callback.call<std::string>(1, 2, 3);
}
};
// For NBIND_CLASS() and method() macros.
#include "nbind/nbind.h"
#ifdef NBIND_CLASS
NBIND_CLASS(HeaderExample) {
method(callJS);
}
#endif
Example used from JavaScript:
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 after installing. It prints:
JS says: sum = 6
Functions not belonging to any class are exported inside an NBIND_GLOBAL
block with a macro call function(functionName); which takes the name of
the function as an argument (without any quotation marks).
The C++ function gets exported to JavaScript with the same name,
or it can be renamed by adding a second argument (with quotation marks):
function(cppFunctionName, "jsExportedName");
If the C++ function is overloaded, multifunction macro must be used
instead. See overloaded functions.
Note: you cannot put several function(...); calls on the same line!
Otherwise you'll get an error about redefining a symbol.
Example:
#include <iostream>
void sayHello(std::string name) {
std::cout << "Hello, " << name << "!\n";
}
#include "nbind/nbind.h"
NBIND_GLOBAL() {
function(sayHello);
}
Example used from JavaScript:
var nbind = require('nbind');
var lib = nbind.init().lib;
lib.sayHello('you');
The NBIND_CLASS(className) macro takes the name of your C++ class as an argument
(without any quotation marks), and exports it to JavaScript using the same name.
It's followed by a curly brace enclosed block of method exports,
as if it was a function definition.
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<int>, "IntData")
Constructors are exported with a macro call construct<types...>(); where types is a comma-separated list of arguments to the constructor, such as int, int. Calling construct multiple times allows overloading it, but each overload must have a different number of arguments.
Constructor arguments are the only types that nbind cannot detect automatically.
Example with different constructor argument counts and types:
#include <iostream>
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<int, int>();
construct<const char *>();
}
Example used from JavaScript:
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 after installing. It prints:
No arguments
Ints: 42 54
String: Don't panic
When a C++ class inherits another, the inherit macro can be used to allow calling parent
class methods on the child class, or passing child class instances to C++ methods expecting
parent class instances.
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 operator will return true for only
one of the parent classes.
Example:
NBIND_CLASS(Child) {
inherit(FirstParent);
inherit(SecondParent);
}
Methods are exported inside an NBIND_CLASS block with a macro call method(methodName);
which takes the name of the method as an argument (without any quotation marks).
The C++ method gets exported to JavaScript with the same name.
If the C++ method is overloaded, multimethod macro must be used instead.
See overloaded functions.
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, it becomes a property of the JavaScript constructor function
and can be accessed like className.methodName(). Otherwise it becomes a property of
the prototype and can be accessed like 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:
#include <string>
#include <vector>
class MethodExample {
public:
unsigned int add(std::string part) {
for(char &c : part) sum += c;
return(sum);
}
static std::vector<unsigned int> check(std::vector<std::string> list) {
std::vector<unsigned int> result;
MethodExample example;
for(auto &&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);
}
Example used from JavaScript, first calling a method in a loop from JS and then a static method returning an array:
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 after installing. It prints:
[ 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.
The function() and method() macroes cannot distinguish between several
overloaded versions of the same function or method, causing an error.
In this case the multifunction() and multimethod() macroes must be used.
Their second parameter is a list of argument types wrapped in an
args() macro to select a single overloaded version.
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));
If it needs to be renamed, the call would be:
multimethod(test, args(unsigned int, unsigned int), "test2");
As always, the return type and method constness are autodetected.
Property getters are exported inside an NBIND_CLASS block with a macro call
getter(getterName) with the name of the getter method as an argument.
nbind automatically strips a get/Get/get_/Get_ prefix and
converts the next letter to lowercase, so for example getX and get_x
both would become getters of x to be accessed like obj.x
Property setters are exported together with getters using a macro call
getset(getterName, setterName) which works much like getter(getterName) above.
Both getterName and setterName are mangled individually so
you can pair getX with set_x if you like.
From JavaScript, ++obj.x would then call both of them to read and change the property.
Example class and property with a getter and setter:
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:
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 after installing.
nbind supports automatically converting between JavaScript arrays and C++
std::vector or std::array types. Just use them as arguments or return values
in C++ methods.
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 can be passed to C++ methods by simply adding an argument of type
nbind::cbFunction & to their declaration.
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 can be called like arg("foobar", 42); in which case the return value is ignored.
If the return value is needed, the callback must be called like arg.call<type>("foobar", 42);
where type is the desired C++ type that the return value should be converted to.
This is because the C++ compiler cannot otherwise know what the callback might return.
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
which calls a callback zero or more times and then returns.
For asynchronous functions like setTimeout which calls the callback after it has returned,
you need to copy the argument to a new nbind::cbFunction and store it somewhere.
C++ objects can be passed to and from JavaScript using different parameter and return types in C++ code:
const)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, in which case calling their
non-const methods or passing them as non-const parameters will throw an error.
This prevents causing undefined behaviour corresponding to C++ code that
wouldn't even compile.
Using pointers and references is particularly:
Passing data by value using value objects solves both issues.
They're based on a toJS function on the C++ side
and a fromJS function on the JavaScript side.
Both receive a callback as an argument, and calling it with any parameters
calls the constructor of the equivalent type in the other language.
The callback on the C++ side is of type nbind::cbOutput.
Value objects are passed through the C++ stack to and from the exported function.
nbind uses C++11 move semantics to avoid creating some additional copies on the way.
The equivalent JavaScript constructor must be registered on the JavaScript side
by calling binding.bind('CppClassName', JSClassName)
so that nbind knows which types to translate between each other.
Example with a class Coord used as a value object, and a class
ObjectExample which uses objects passed by values and references:
#include <iostream>
#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<const Coord *>();
construct<signed int, signed int>();
getset(getX, setX);
getset(getY, setY);
}
NBIND_CLASS(ObjectExample) {
method(showByValue);
method(showByRef);
method(getValue);
method(getRef);
}
Example used from JavaScript:
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 after installing. It prints:
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
Parameters and return values of function calls between languages are automatically converted between equivalent types:
| JavaScript | C++ |
|---|---|
| number | (un)signed char, short, int, long |
| number | float, double |
| number or bignum | (un)signed long, long long |
| boolean | bool |
| string | const (unsigned) char * |
| string | std::string |
| Array | std::vector<type> |
| Array | std::array<type, size> |
| Function | nbind::cbFunction(only as a parameter) See Callbacks |
| nbind-wrapped pointer | Pointer or reference to an instance of any bound class See Using objects |
| Instance of any prototype (with a fromJS method) | Instance of any bound class (with a toJS method) See Using objects |
| ArrayBuffer(View), Int*Array or Buffer | nbind::Buffer struct(data pointer and length) See Buffers |
Type conversion is customizable by passing policies as additional arguments
to construct, function or method inside an NBIND_CLASS or NBIND_GLOBAL block.
Currently supported policies are:
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());
}
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 type which has the methods:
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 to C++
and drawing to an on-screen bitmap when targeting Emscripten or Electron.
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
Normally C++ 64-bit integer types are first converted to double and then to JavaScript number
which can only hold 53 bits of precision, but it's possible to preserve all bits by using a bignum class.
It should have a constructor taking the following arguments:
It should also have a fromJS function which takes a callback,
and calls it with those same arguments to pass the data back to C++ when needed.
An example implementation also capable of printing 64-bit numbers to strings in bases 2, 4, 10 and 16 is included.
You can use the NBIND_ERR("message here"); macro to report an error before returning from C++
(#include "nbind/api.h" first). It will be thrown as an error on the JavaScript side
(C++ environments like Emscripten may not support throwing exceptions, but the JavaScript side will).
Make sure your package.json file has at least the required emcc-path
and install scripts:
"scripts": {
"emcc-path": "emcc-path",
"install": "autogypi && node-gyp configure build"
}
The dependencies section should have at least:
"dependencies": {
"autogypi": "^0.2.2",
"nbind": "^0.2.1",
"node-gyp": "^3.3.1"
}
Your package should also include binding.gyp and autogypi.json files.
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 and build/asmjs,
for compiling both versions. nbind provides a binary copyasm
that can then be used to copy the compiled asm.js library
into a nicer location for publishing inside the final npm package.
Note that the native version should be compiled in the install script
so it runs for all users of the package, and the asm.js version should be
compiled in the prepublish script so it gets packaged in npm for usage
without the Emscripten compiler. See the
example package.json file.
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 working is to add
these scripts in your HTML code as seen in the
example index.html:
<script src="nbind.js"></script>
<script>
nbind.init(function(err, binding) {
var lib = binding.lib;
// Use the library.
});
</script>
Make sure to fix the path to nbind.js on the first line if necessary.
nbind has a fully typed API for interacting with C++ code and it can also
automatically generate .d.ts files for your C++ classes and functions.
This gives you effortless bindings with compile time type checking for calls
from JavaScript to Node.js addons and asm.js modules.
All you have to do is compile your C++ code and run the included ndts tool
to create the type definitions:
npm run -- node-gyp configure build
npm run -- ndts . > lib-types.d.ts
When run in this way, the first argument of ndts is a path from the package
root to the binding.gyp file. Typically the file is in the root so the
correct path is .
Now you can load the C++ code from TypeScript in three different ways. First
import nbind (which also loads the C++ code) and types generated by 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<typeof LibTypes>().lib;
// Use the library.
Asynchronous-aware:
nbind.init((err: any, binding: nbind.Binding<typeof LibTypes>) => {
const lib = binding.lib;
// Use the library.
});
Promise-based:
import * as bluebird from 'bluebird';
bluebird.promisify(nbind.init)().then((binding: nbind.Binding<typeof LibTypes>) => {
const lib = binding.lib;
// Use the library.
});
Note how there is a type argument <typeof LibTypes> for the init call
in all of the examples. It defines types of binding.lib contents, which
coming from C++ are otherwise unknown to the TypeScript compiler.
You can import the types from a file generated by ndts or just use <any>
to disable typing.
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 will generate the following typings:
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 is generated in this case to support multiple
inheritance, because C extends both A and 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 in a TypeScript IDE and see the generated
typings in action.
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.
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 library working.
In the browser it can be difficult to stop and debug at the correct spot in
optimized C++ code. nbind provides an _nbind_debug() function in api.h
that you can call from C++ to invoke the browser's debugger when using asm.js.
For debugging a Node.js addon, if you would normally test it like
node test.js, you can instead use gdb node and type run test.js in the
GDB prompt. Then in case of a crash, it will show where it happened,
inspect the stack etc.
You should also modify nbind.gypi (inside nbind's src directory)
and possibly your own binding.gyp, to remove any -O? flags and instead
add a -g flag, then remove the build directory and recompile.
This allows GDB to show much more information.
Very similar:
Less similar:
Copyright (c) 2014-2017 BusFaster Ltd
FAQs
Magical headers that make your C++ library accessible from JavaScript
The npm package nbind receives a total of 131 weekly downloads. As such, nbind popularity was classified as not popular.
We found that nbind demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.