Skip to content

Streamlined C/C++ v8 bindings generator for Node.JS inspired by tolua++ (requires C++11)

License

Notifications You must be signed in to change notification settings

encharm/node-cbind

Repository files navigation

node-cbind

Build Status Package version Package version Dependcies status

Streamlined automatic C/C++ v8 bindings generator for Node.JS inspired by tolua++ (requires C++11)

Core idea is the ability to easily bind to C/C++ by providing a header-like description of the native interface that is a subset of C++ (format is called Native Interface Description https://github.com/CodeCharmLtd/NID):

Simple things:

int global_variable;

std::string global_function(int a, float b);

struct Rect {
  int x;
  int y;
  int w;
  int h;
};
bool rectangles_intersect(Rect a, Rect b);

More complex things:

#include <stdio.h>

int errno; // make errno available as getter and setter

// make fopen available and mark FILE* pointers for automatic closing when gced
FILE * [[free(fclose)]] fopen(const char* filename, const char* mode);

// make fread available and automatically set one of its arguments
size_t fread(void* ptr [[buffer]], size_t size, size_t nmemb [[set(ptr.length / size)]], FILE* stream [[handle]]);

// tell cbind to mark the object containing pointer as invalid
int fclose(FILE* f [[clear_free,unref]]);
## Complex weird cases function pointer handling Consider this declaration (valid C and valid NID): ```c++ void (*catch_and_return(void (*callback)(char* a, char* b, int* c), char *name_one, char* name_two, int* number))(char* a, char * b, int c); ``` Do you know what it does? Actually it is a declaration of function taking 4 arguments: * `callback` - pointer to function `void(char* a, char* b, int* c)` * `name_one` - string * `name_two` - string * `number` - pointer to number

This function returns another function pointer void(char* a, char* b, int)

It turns out cbind can generate bindings for this that fully work:

bindings.catch_and_return(function(a, b, c) {
  console.log(a, b, cBind.derefInt(c));
}, "str1", "str2", cBind.createInt(30))("FINAL", "TEST", 44);
  • Handling basic types int, float, double, char*, const char*, std::string
  • Handling pointers to basic types. Contains functions to create pointer values and dereference them.
  • Binding to global variables with getter/setter.
  • Binding to global functions.
  • Type checking that throws exception to javascript in case of unmatched types.
  • Attributes for specifying automatic free of returned arguments.
  • Attributes for handling input buffer automatically and passing it to javascript as a return value.

Implemented and initially tested

  • Handle binary buffers as Buffer.
  • Handling function pointer types. Function pointers are automatically converted to javascript functions and vice-versa. Function pointer variables as getter/setters and function pointers as arguments are equally handled.
  • Handling constructors of structs/classes and binding them to javascript new.
  • Handling class/struct variables and methods.
  • Passing struct and class pointers to arbitrary functions.

Planned features / Not supported yet

  • Function overloading.
  • Attributes for calling native code asynchronously and returning values as promises (bluebird).
  • Attributes for automatically handling native callbacks that have returned from a separate thread.

Requirements

  • C++11 support (GCC 4.8 or clang 3.3)
  • Node 0.8, 0.10 or 0.11.13+

How-to use

  • npm install --save cbind
  • Create example.nid file Put your native interface definition there, for example:
void hello(int b);
  • Have your binding.gyp follow this example:
{
  "targets": [
    {
      "target_name": "cbind_example",
      "sources": [
        "src/addon.cc"
      ],
      "include_dirs"  : [
          "<!(node -e \"require('nan')\" 2> /dev/null)",
          "<!(node -e \"require('cbind')('example.nid')\" 2> /dev/null)"
      ],
      "cflags": ["-g", "-std=c++11"],
			"cflags_cc!": [ '-fno-exceptions' ]
    }
  ]
}
  • Have your addon.cc the following content
#include <cstdio>

void hello(int a) {
  printf("Hello world: %i\n", a);
}

#include <cbind_example.h>

void init(v8::Handle<v8::Object> exports) {
  
  cbind::init_example(exports);
}

NODE_MODULE(tov8_example, init);
  • Run node-gyp rebuild

  • With hello.js having the following content:

var bindings = require('./build/Release/cbind_example.node');
bindings = hello(42);
  • node hello.js should print "Hello world 42`

The above is in the repository https://github.com/CodeCharmLtd/cbind-example

Please open issues or follow example tests. README will be gradually expanded.

Special thanks

https://github.com/celer/fire-ts - awesome templates for code generation

## Authors * Damian Kaczmarek ## Sponsors Please open an issue if you would like a specific feature to be implemented and sponsored. ## License Copyright (c) 2013-2014 [Code Charm Ltd](http://codecharm.co.uk)

Licensed under the MIT license, see LICENSE for details.

About

Streamlined C/C++ v8 bindings generator for Node.JS inspired by tolua++ (requires C++11)

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published