wpfx.org-HBuilder.zip

Native Abstractions for Node.js =============================== **A header file filled with macro and utility goodness for making add-on development for Node.js easier across versions 0.8, 0.10 and 0.11, and eventually 0.12.** ***Current version: 1.0.0*** *(See [nan.h](https://github.com/rvagg/nan/blob/master/nan.h) for complete ChangeLog)* [](https://nodei.co/npm/nan/) [](https://nodei.co/npm/nan/) Thanks to the crazy changes in V8 (and some in Node core), keeping native addons compiling happily across versions, particularly 0.10 to 0.11/0.12, is a minor nightmare. The goal of this project is to store all logic necessary to develop native Node.js addons without having to inspect `NODE_MODULE_VERSION` and get yourself into a macro-tangle. This project also contains some helper utilities that make addon development a bit more pleasant. * **[News & Updates](#news)** * **[Usage](#usage)** * **[Example](#example)** * **[API](#api)** <a name="news"></a> ## News & Updates ### May-2013: Major changes for V8 3.25 / Node 0.11.13 Node 0.11.11 and 0.11.12 were both broken releases for native add-ons, you simply can't properly compile against either of them for different reasons. But we now have a 0.11.13 release that jumps a couple of versions of V8 ahead and includes some more, major (traumatic) API changes. Because we are now nearing Node 0.12 and estimate that the version of V8 we are using in Node 0.11.13 will be close to the API we get for 0.12, we have taken the opportunity to not only *fix* NAN for 0.11.13 but make some major changes to improve the NAN API. We have **removed support for Node 0.11 versions prior to 0.11.13**, (although our tests are still passing for 0.11.10). As usual, our tests are run against (and pass) the last 5 versions of Node 0.8 and Node 0.10. We also include Node 0.11.13 obviously. The major change is something that [Benjamin Byholm](kkoopa) has put many hours in to. We now have a fantastic new `NanNew<T>(args)` interface for creating new `Local`s, this replaces `NanNewLocal()` and much more. If you look in [./nan.h](nan.h) you'll see a large number of overloaded versions of this method. In general you should be able to `NanNew<Type>(arguments)` for any type you want to make a `Local` from. This includes `Persistent` types, so we now have a `Local<T> NanNew(const Persistent<T> arg)` to replace `NanPersistentToLocal()`. We also now have `NanUndefined()`, `NanNull()`, `NanTrue()` and `NanFalse()`. Mainly because of the new requirement for an `Isolate` argument for each of the native V8 versions of this. V8 has now introduced an `EscapableHandleScope` from which you `scope.Escape(Local<T> value)` to *return* a value from a one scope to another. This replaces the standard `HandleScope` and `scope.Close(Local<T> value)`, although `HandleScope` still exists for when you don't need to return a handle to the caller. For NAN we are exposing it as `NanEscapableScope()` and `NanEscapeScope()`, while `NanScope()` is still how you create a new scope that doesn't need to return handles. For older versions of Node/V8, it'll still map to the older `HandleScope` functionality. `NanFromV8String()` was deprecated and has now been removed. You should use `NanCString()` or `NanRawString()` instead. Because `node::MakeCallback()` now takes an `Isolate`, and because it doesn't exist in older versions of Node, we've introduced `NanMakeCallabck()`. You should *always* use this when calling a JavaScript function from C++. There's lots more, check out the Changelog in nan.h or look through [#86](https://github.com/rvagg/nan/pull/86) for all the gory details. ### Dec-2013: NanCString and NanRawString Two new functions have been introduced to replace the functionality that's been provided by `NanFromV8String` until now. NanCString has sensible defaults so it's super easy to fetch a null-terminated c-style string out of a `v8::String`. `NanFromV8String` is still around and has defaults that allow you to pass a single handle to fetch a `char*` while `NanRawString` requires a little more attention to arguments. ### Nov-2013: Node 0.11.9+ breaking V8 change The version of V8 that's shipping with Node 0.11.9+ has changed the signature for new `Local`s to: `v8::Local<T>::New(isolate, value)`, i.e. introducing the `isolate` argument and therefore breaking all new `Local` declarations for previous versions. NAN 0.6+ now includes a `NanNewLocal<T>(value)` that can be used in place to work around this incompatibility and maintain compatibility with 0.8->0.11.9+ (minus a few early 0.11 releases). For example, if you wanted to return a `null` on a callback you will have to change the argument from `v8::Local<v8::Value>::New(v8::Null())` to `NanNewLocal<v8::Value>(v8::Null())`. ### Nov-2013: Change to binding.gyp `"include_dirs"` for NAN Inclusion of NAN in a project's binding.gyp is now greatly simplified. You can now just use `"<!(node -e \"require('nan')\")"` in your `"include_dirs"`, see example below (note Windows needs the quoting around `require` to be just right: `"require('nan')"` with appropriate `\` escaping). <a name="usage"></a> ## Usage Simply add **NAN** as a dependency in the *package.json* of your Node addon: ``` bash $ npm install --save nan ``` Pull in the path to **NAN** in your *binding.gyp* so that you can use `#include <nan.h>` in your *.cpp* files: ``` python "include_dirs" : [ "<!(node -e \"require('nan')\")" ] ``` This works like a `-I<path-to-NAN>` when compiling your addon. <a name="example"></a> ## Example See **[LevelDOWN](https://github.com/rvagg/node-leveldown/pull/48)** for a full example of **NAN** in use. For a simpler example, see the **[async pi estimation example](https://github.com/rvagg/nan/tree/master/examples/async_pi_estimate)** in the examples directory for full code and an explanation of what this Monte Carlo Pi estimation example does. Below are just some parts of the full example that illustrate the use of **NAN**. Compare to the current 0.10 version of this example, found in the [node-addon-examples](https://github.com/rvagg/node-addon-examples/tree/master/9_async_work) repository and also a 0.11 version of the same found [here](https://github.com/kkoopa/node-addon-examples/tree/5c01f58fc993377a567812597e54a83af69686d7/9_async_work). Note that there is no embedded version sniffing going on here and also the async work is made much simpler, see below for details on the `NanAsyncWorker` class. ```c++ // addon.cc #include <node.h> #include <nan.h> // ... using v8::FunctionTemplate; using v8::Handle; using v8::Object; void InitAll(Handle<Object> exports) { exports->Set(NanSymbol("calculateSync"), NanNew<FunctionTemplate>(CalculateSync)->GetFunction()); exports->Set(NanSymbol("calculateAsync"), NanNew<FunctionTemplate>(CalculateAsync)->GetFunction()); } NODE_MODULE(addon, InitAll) ``` ```c++ // sync.h #include <node.h> #include <nan.h> NAN_METHOD(CalculateSync); ``` ```c++ // sync.cc #include <node.h> #include <nan.h> #include "./sync.h" // ... using v8::Number; // Simple synchronous access to the `Estimate()` function NAN_METHOD(CalculateSync) { NanScope(); // expect a number as the first argument int points = args[0]->Uint32Value(); double est = Estimate(points); NanReturnValue(NanNew<Number>(est)); } ``` ```c++ // async.cc #include <node.h> #include <nan.h> #include "./async.h" // ... using v8::Function; using v8::Local; using v8::Null; using v8::Number; using v8::Value; class PiWorker : public NanAsyncWorker { public: PiWorker(NanCallback *callback, int points) : NanAsyncWorker(callback), points(points) {} ~PiWorker() {} // Executed inside the worker-thread. // It is not safe to access V8, or V8 data structures // here, so everything we need for input and output // should go on `this`. void Execute () { estimate = Estimate