v8.4.0

addons/addon_examples.md

@@ -0,0 +1,35 @@
+
+Following are some example Addons intended to help developers get started. The
+examples make use of the V8 APIs. Refer to the online [V8 reference][v8-docs]
+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.
+
+Each of these examples using the following `binding.gyp` file:
+
+```json
+{
+  "targets": [
+    {
+      "target_name": "addon",
+      "sources": [ "addon.cc" ]
+    }
+  ]
+}
+```
+
+In cases where there is more than one `.cc` file, simply add the additional
+filename to the `sources` array. For example:
+
+```json
+"sources": ["addon.cc", "myexample.cc"]
+```
+
+Once the `binding.gyp` file is ready, the example Addons can be configured and
+built using `node-gyp`:
+
+```console
+$ node-gyp configure build
+```
+
+

addons/atexit_hooks.md

@@ -0,0 +1,5 @@
+
+An "AtExit" hook is a function that is invoked after the Node.js event loop
+has ended but before the JavaScript VM is terminated and Node.js shuts down.
+"AtExit" hooks are registered using the `node::AtExit` API.
+

addons/building.md

@@ -0,0 +1,68 @@
+
+Once the source code has been written, it must be compiled into the binary
+`addon.node` file. To do so, create a file called `binding.gyp` in the
+top-level of the project describing the build configuration of the module
+using a JSON-like format. This file is used by [node-gyp][] -- a tool written
+specifically to compile Node.js Addons.
+
+```json
+{
+  "targets": [
+    {
+      "target_name": "addon",
+      "sources": [ "hello.cc" ]
+    }
+  ]
+}
+```
+
+*Note*: A version of the `node-gyp` utility is bundled and distributed with
+Node.js as part of `npm`. This version is not made directly available for
+developers to use and is intended only to support the ability to use the
+`npm install` command to compile and install Addons. Developers who wish to
+use `node-gyp` directly can install it using the command
+`npm install -g node-gyp`. See the `node-gyp` [installation instructions][] for
+more information, including platform-specific requirements.
+
+Once the `binding.gyp` file has been created, use `node-gyp configure` to
+generate the appropriate project build files for the current platform. This
+will generate either a `Makefile` (on Unix platforms) or a `vcxproj` file
+(on Windows) in the `build/` directory.
+
+Next, invoke the `node-gyp build` command to generate the compiled `addon.node`
+file. This will be put into the `build/Release/` directory.
+
+When using `npm install` to install a Node.js Addon, npm uses its own bundled
+version of `node-gyp` to perform this same set of actions, generating a
+compiled version of the Addon for the user's platform on demand.
+
+Once built, the binary Addon can be used from within Node.js by pointing
+[`require()`][require] to the built `addon.node` module:
+
+```js
+// hello.js
+const addon = require('./build/Release/addon');
+
+console.log(addon.hello());
+// Prints: 'world'
+```
+
+Please see the examples below for further information or
+<https://github.com/arturadib/node-qt> for an example in production.
+
+Because the exact path to the compiled Addon binary can vary depending on how
+it is compiled (i.e. sometimes it may be in `./build/Debug/`), Addons can use
+the [bindings][] package to load the compiled module.
+
+Note that while the `bindings` package implementation is more sophisticated
+in how it locates Addon modules, it is essentially using a try-catch pattern
+similar to:
+
+```js
+try {
+  return require('./build/Release/addon.node');
+} catch (err) {
+  return require('./build/Debug/addon.node');
+}
+```
+

addons/c_addons.md

@@ -0,0 +1,40 @@
+
+Node.js Addons are dynamically-linked shared objects, written in C++, that
+can be loaded into Node.js using the [`require()`][require] function, and used
+just as if they were an ordinary Node.js module. They are used primarily to
+provide an interface between JavaScript running in Node.js and C/C++ libraries.
+
+At the moment, the method for implementing Addons is rather complicated,
+involving knowledge of several components and APIs :
+
+ - V8: the C++ library Node.js currently uses to provide the
+   JavaScript implementation. V8 provides the mechanisms for creating objects,
+   calling functions, etc. V8's API is documented mostly in the
+   `v8.h` header file (`deps/v8/include/v8.h` in the Node.js source
+   tree), which is also available [online][v8-docs].
+
+ - [libuv][]: The C library that implements the Node.js event loop, its worker
+   threads and all of the asynchronous behaviors of the platform. It also
+   serves as a cross-platform abstraction library, giving easy, POSIX-like
+   access across all major operating systems to many common system tasks, such
+   as interacting with the filesystem, sockets, timers and system events. libuv
+   also provides a pthreads-like threading abstraction that may be used to
+   power more sophisticated asynchronous Addons that need to move beyond the
+   standard event loop. Addon authors are encouraged to think about how to
+   avoid blocking the event loop with I/O or other time-intensive tasks by
+   off-loading work via libuv to non-blocking system operations, worker threads
+   or a custom use of libuv's threads.
+
+ - Internal Node.js libraries. Node.js itself exports a number of C++ APIs
+   that Addons can use — the most important of which is the
+   `node::ObjectWrap` class.
+
+ - Node.js includes a number of other statically linked libraries including
+   OpenSSL. These other libraries are located in the `deps/` directory in the
+   Node.js source tree. Only the V8 and OpenSSL symbols are purposefully
+   re-exported by Node.js and may be used to various extents by Addons.
+   See [Linking to Node.js' own dependencies][] for additional information.
+
+All of the following examples are available for [download][] and may
+be used as the starting-point for an Addon.
+

addons/callbacks.md

@@ -0,0 +1,56 @@
+
+It is common practice within Addons to pass JavaScript functions to a C++
+function and execute them from there. The following example illustrates how
+to invoke such callbacks:
+
+```cpp
+// addon.cc
+#include <node.h>
+
+namespace demo {
+
+using v8::Function;
+using v8::FunctionCallbackInfo;
+using v8::Isolate;
+using v8::Local;
+using v8::Null;
+using v8::Object;
+using v8::String;
+using v8::Value;
+
+void RunCallback(const FunctionCallbackInfo<Value>& args) {
+  Isolate* isolate = args.GetIsolate();
+  Local<Function> cb = Local<Function>::Cast(args[0]);
+  const unsigned argc = 1;
+  Local<Value> argv[argc] = { String::NewFromUtf8(isolate, "hello world") };
+  cb->Call(Null(isolate), argc, argv);
+}
+
+void Init(Local<Object> exports, Local<Object> module) {
+  NODE_SET_METHOD(module, "exports", RunCallback);
+}
+
+NODE_MODULE(addon, Init)
+
+}  // namespace demo
+```
+
+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`.
+
+To test it, run the following JavaScript:
+
+```js
+// test.js
+const addon = require('./build/Release/addon');
+
+addon((msg) => {
+  console.log(msg);
+// Prints: 'hello world'
+});
+```
+
+Note that, in this example, the callback function is invoked synchronously.
+