National Public Mania

    cbind

    0.0.10 • Public • Published

    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);

    Supported and tested features

    • 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.

    Keywords

    none

    Install

    npm i cbind

    DownloadsWeekly Downloads

    26

    Version

    0.0.10

    License

    MIT

    Last publish

    Collaborators

    • rush