mirror of https://github.com/lukechilds/node.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
81 lines
2.7 KiB
81 lines
2.7 KiB
14 years ago
|
## 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 http://code.google.com/p/waf/[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.
|