node/doc/api/addons.markdown

Addons

Addons are dynamically linked shared objects. They can provide glue to C and C++ libraries. The API (at the moment) is rather complex, involving knowledge of several libraries:

• V8 JavaScript, a C++ library. Used for interfacing with JavaScript: creating objects, calling functions, etc. Documented mostly in the v8.h header file (deps/v8/include/v8.h in the Node source tree).

• libev, C event loop library. Anytime one needs to wait for a file descriptor to become readable, wait for a timer, or wait for a signal to received one will need to interface with libev. That is, if you perform any I/O, libev will need to be used. Node uses the EV_DEFAULT event loop. Documentation can be found http:/cvs.schmorp.de/libev/ev.html[here].

• libeio, C thread pool library. Used to execute blocking POSIX system calls asynchronously. Mostly wrappers already exist for such calls, in src/file.cc so you will probably not need to use it. If you do need it, look at the header file deps/libeio/eio.h.

• Internal Node libraries. Most importantly is the node::ObjectWrap class which you will likely want to derive from.

• Others. Look in deps/ for what else is available.

Node statically compiles all its dependencies into the executable. When compiling your module, you don't need to worry about linking to any of these libraries.

To get started let's make a small Addon which does the following except in C++:

exports.hello = 'world';

To get started we create a file hello.cc:

#include <v8.h>

using namespace v8;

extern "C" void
init (Handle<Object> target)
{
  HandleScope scope;
  target->Set(String::New("hello"), String::New("world"));
}

This source code needs to be built into hello.node, the binary Addon. To do this we create a file called wscript which is python code and looks like this:

srcdir = '.'
blddir = 'build'
VERSION = '0.0.1'

def set_options(opt):
  opt.tool_options('compiler_cxx')

def configure(conf):
  conf.check_tool('compiler_cxx')
  conf.check_tool('node_addon')

def build(bld):
  obj = bld.new_task_gen('cxx', 'shlib', 'node_addon')
  obj.target = 'hello'
  obj.source = 'hello.cc'

Running node-waf configure build will create a file build/default/hello.node which is our Addon.

node-waf is just WAF, the python-based build system. node-waf is provided for the ease of users.

All Node addons must export a function called init with this signature:

extern 'C' void init (Handle<Object> target)

For the moment, that is all the documentation on addons. Please see http://github.com/ry/node_postgres for a real example.