Table of Contents

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), which is also available
online.

libuv, 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 be received one will need
to interface with libuv. That is, if you perform any I/O, libuv will
need to be used.

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.

All of the following examples are available for
download and may be
used as a starting-point for your own Addon.

There is no semi-colon after NODE_MODULE as it's not a function (see
node.h).

The module_name needs to match the filename of the final binary (minus the
.node suffix).

The source code needs to be built into addon.node, the binary Addon. To
do this we create a file called binding.gyp which describes the configuration
to build your module in a JSON-like format. This file gets compiled by
node-gyp.

Below are some addon patterns to help you get started. Consult the online
v8 reference for help with the various v8
calls, and v8's Embedder's Guide
for an explanation of several concepts used such as handles, scopes,
function templates, etc.

In order to use these examples you need to compile them using node-gyp.
Create the following binding.gyp file:

Note that this example uses a two-argument form of Init() that receives
the full module object as the second argument. This allows the addon
to completely overwrite exports with a single function instead of
adding the function as a property of exports.

In addition to wrapping and returning C++ objects, you can pass them around
by unwrapping them with Node's node::ObjectWrap::Unwrap helper function.
In the following addon.cc we introduce a function add() that can take on two
MyObject objects: