Lines Matching +full:node +full:- +full:gyp
3 <!--introduced_in=v0.10.0-->
5 <!-- type=misc -->
7 _Addons_ are dynamically-linked shared objects written in C++. The
8 [`require()`][require] function can load addons as ordinary Node.js modules.
11 There are three options for implementing addons: Node-API, nan, or direct
12 use of internal V8, libuv, and Node.js libraries. Unless there is a need for
13 direct access to functionality which is not exposed by Node-API, use Node-API.
14 Refer to [C/C++ addons with Node-API](n-api.md) for more information on
15 Node-API.
17 When not using Node-API, implementing addons is complicated,
20 * [V8][]: the C++ library Node.js uses to provide the
23 `v8.h` header file (`deps/v8/include/v8.h` in the Node.js source
24 tree), which is also available [online][v8-docs].
26 * [libuv][]: The C library that implements the Node.js event loop, its worker
28 serves as a cross-platform abstraction library, giving easy, POSIX-like
34 avoid blocking the event loop with I/O or other time-intensive tasks by
35 offloading work via libuv to non-blocking system operations, worker threads,
38 * Internal Node.js libraries. Node.js itself exports C++ APIs that addons can
39 use, the most important of which is the `node::ObjectWrap` class.
41 * Node.js includes other statically linked libraries including OpenSSL. These
42 other libraries are located in the `deps/` directory in the Node.js source
44 re-exported by Node.js and may be used to various extents by addons. See
45 [Linking to libraries included with Node.js][] for additional information.
48 be used as the starting-point for an addon.
63 #include <node.h>
89 All Node.js addons must export an initialization function following
97 There is no semi-colon after `NODE_MODULE` as it's not a function (see
98 `node.h`).
101 the `.node` suffix).
106 When building addons with `node-gyp`, using the macro `NODE_GYP_MODULE_NAME` as
113 ### Context-aware addons
115 There are environments in which Node.js addons may need to be loaded multiple
117 instances of Node.js in a single process. Each instance will have its own
122 A context-aware addon can be constructed by using the macro
123 `NODE_MODULE_INITIALIZER`, which expands to the name of a function which Node.js
139 construct a context-aware addon. Unlike `NODE_MODULE()`, which is used to
151 The choice to build a context-aware addon carries with it the responsibility of
160 The context-aware addon can be structured to avoid global static data by
163 * Define a class which will hold per-addon-instance data and which has a static
170 * Heap-allocate an instance of this class in the addon initializer. This can be
172 * Call `node::AddEnvironmentCleanupHook()`, passing it the above-created
178 native-backed JavaScript functions. The third parameter of
183 This will ensure that the per-addon-instance data reaches each binding that can
184 be called from JavaScript. The per-addon-instance data must also be passed into
187 The following example illustrates the implementation of a context-aware addon:
190 #include <node.h>
198 // Ensure this per-addon-instance data is deleted at environment cleanup.
199 node::AddEnvironmentCleanupHook(isolate, DeleteInstance, this);
202 // Per-addon data.
211 // Retrieve the per-addon-instance data.
213 reinterpret_cast<AddonData*>(info.Data().As<External>()->Value());
214 data->call_count++;
215 info.GetReturnValue().Set((double)data->call_count);
218 // Initialize this addon to be context-aware.
220 Isolate* isolate = context->GetIsolate();
223 // tie its life cycle to that of the Node.js environment.
231 // per-addon-instance data we created above by passing `external` as the
233 exports->Set(context,
236 ->GetFunction(context).ToLocalChecked()).FromJust();
242 <!-- YAML
244 - version:
245 - v14.8.0
246 - v12.19.0
247 pr-url: https://github.com/nodejs/node/pull/34572
249 -->
251 In order to be loaded from multiple Node.js environments,
252 such as a main thread and a Worker thread, an add-on needs to either:
254 * Be an Node-API addon, or
255 * Be declared as context-aware using `NODE_MODULE_INIT()` as described above
267 This function adds a hook that will run before a given Node.js instance shuts
270 run in last-in first-out order.
281 #include <node.h>
285 using node::AddEnvironmentCleanupHook;
291 // Note: In a real-world application, do not rely on static/global data.
301 assert(obj->IsObject());
315 // Initialize this addon to be context-aware.
317 Isolate* isolate = context->GetIsolate();
335 `addon.node` file. To do so, create a file called `binding.gyp` in the
336 top-level of the project describing the build configuration of the module
337 using a JSON-like format. This file is used by [node-gyp][], a tool written
338 specifically to compile Node.js addons.
351 A version of the `node-gyp` utility is bundled and distributed with
352 Node.js as part of `npm`. This version is not made directly available for
355 use `node-gyp` directly can install it using the command
356 `npm install -g node-gyp`. See the `node-gyp` [installation instructions][] for
357 more information, including platform-specific requirements.
359 Once the `binding.gyp` file has been created, use `node-gyp configure` to
364 Next, invoke the `node-gyp build` command to generate the compiled `addon.node`
367 When using `npm install` to install a Node.js addon, npm uses its own bundled
368 version of `node-gyp` to perform this same set of actions, generating a
371 Once built, the binary addon can be used from within Node.js by pointing
372 [`require()`][require] to the built `addon.node` module:
391 return require('./build/Release/addon.node');
393 return require('./build/Debug/addon.node');
397 ### Linking to libraries included with Node.js
399 Node.js uses statically linked libraries such as V8, libuv, and OpenSSL. All
402 `#include <...>` statements (e.g. `#include <v8.h>`) and `node-gyp` will locate
406 * When `node-gyp` runs, it will detect the specific release version of Node.js
409 Node.js dependencies. However, if only the Node.js headers are downloaded,
410 then only the symbols exported by Node.js will be available.
412 * `node-gyp` can be run using the `--nodedir` flag pointing at a local Node.js
418 The filename extension of the compiled addon binary is `.node` (as opposed
420 files with the `.node` file extension and initialize those as dynamically-linked
423 When calling [`require()`][require], the `.node` extension can usually be
424 omitted and Node.js will still find and initialize the addon. One caveat,
425 however, is that Node.js will first attempt to locate and load modules or
427 there is a file `addon.js` in the same directory as the binary `addon.node`,
431 ## Native abstractions for Node.js
434 Node.js and V8 APIs for implementing addons. The V8 API can, and has, changed
435 dramatically from one V8 release to the next (and one major Node.js release to
437 order to continue functioning. The Node.js release schedule is designed to
439 Node.js can do to ensure stability of the V8 APIs.
441 The [Native Abstractions for Node.js][] (or `nan`) provide a set of tools that
443 future releases of V8 and Node.js. See the `nan` [examples][] for an
446 ## Node-API
448 > Stability: 2 - Stable
450 Node-API is an API for building native addons. It is independent from
452 Node.js itself. This API will be Application Binary Interface (ABI) stable
453 across versions of Node.js. It is intended to insulate addons from
455 compiled for one version to run on later versions of Node.js without
457 outlined in this document (node-gyp, etc.). The only difference is the
459 or [Native Abstractions for Node.js][] APIs, the functions available
460 in the Node-API are used.
463 provided by Node-API carries with it certain
466 To use Node-API in the above "Hello world" example, replace the content of
470 // hello.cc using Node-API
502 [C/C++ addons with Node-API](n-api.md).
507 examples use the V8 APIs. Refer to the online [V8 reference][v8-docs]
512 Each of these examples using the following `binding.gyp` file:
532 Once the `binding.gyp` file is ready, the example addons can be configured and
533 built using `node-gyp`:
536 $ node-gyp configure build
542 JavaScript running within Node.js. When functions are invoked from JavaScript,
551 #include <node.h>
573 isolate->ThrowException(Exception::TypeError(
580 if (!args[0]->IsNumber() || !args[1]->IsNumber()) {
581 isolate->ThrowException(Exception::TypeError(
589 args[0].As<Number>()->Value() + args[1].As<Number>()->Value();
606 Once compiled, the example addon can be required and used from within Node.js:
623 #include <node.h>
639 Local<Context> context = isolate->GetCurrentContext();
645 cb->Call(context, Null(isolate), argc, argv).ToLocalChecked();
657 This example uses a two-argument form of `Init()` that receives the full
684 #include <node.h>
698 Local<Context> context = isolate->GetCurrentContext();
701 obj->Set(context,
704 args[0]->ToString(context).ToLocalChecked())
738 #include <node.h>
761 Local<Context> context = isolate->GetCurrentContext();
763 Local<Function> fn = tpl->GetFunction(context).ToLocalChecked();
766 fn->SetName(String::NewFromUtf8(
799 #include <node.h>
816 Then, in `myobject.h`, the wrapper class inherits from `node::ObjectWrap`:
823 #include <node.h>
828 class MyObject : public node::ObjectWrap {
876 Isolate* isolate = exports->GetIsolate();
877 Local<Context> context = isolate->GetCurrentContext();
880 addon_data_tpl->SetInternalFieldCount(1); // 1 field for the MyObject::New()
882 addon_data_tpl->NewInstance(context).ToLocalChecked();
886 tpl->SetClassName(String::NewFromUtf8(isolate, "MyObject").ToLocalChecked());
887 tpl->InstanceTemplate()->SetInternalFieldCount(1);
892 Local<Function> constructor = tpl->GetFunction(context).ToLocalChecked();
893 addon_data->SetInternalField(0, constructor);
894 exports->Set(context, String::NewFromUtf8(
901 Local<Context> context = isolate->GetCurrentContext();
905 double value = args[0]->IsUndefined() ?
906 0 : args[0]->NumberValue(context).FromMaybe(0);
908 obj->Wrap(args.This());
915 args.Data().As<Object>()->GetInternalField(0).As<Function>();
917 cons->NewInstance(context, argc, argv).ToLocalChecked();
926 obj->value_ += 1;
928 args.GetReturnValue().Set(Number::New(isolate, obj->value_));
935 `binding.gyp`:
967 garbage-collected. For destructor testing, there are command-line flags that
970 or removal at any time. They are not documented by Node.js or V8, and they
992 #include <node.h>
1009 MyObject::Init(exports->GetIsolate());
1028 #include <node.h>
1033 class MyObject : public node::ObjectWrap {
1057 #include <node.h>
1062 using node::AddEnvironmentCleanupHook;
1075 // Warning! This is not thread-safe, this addon cannot be used for worker
1088 tpl->SetClassName(String::NewFromUtf8(isolate, "MyObject").ToLocalChecked());
1089 tpl->InstanceTemplate()->SetInternalFieldCount(1);
1094 Local<Context> context = isolate->GetCurrentContext();
1095 constructor.Reset(isolate, tpl->GetFunction(context).ToLocalChecked());
1104 Local<Context> context = isolate->GetCurrentContext();
1108 double value = args[0]->IsUndefined() ?
1109 0 : args[0]->NumberValue(context).FromMaybe(0);
1111 obj->Wrap(args.This());
1119 cons->NewInstance(context, argc, argv).ToLocalChecked();
1130 Local<Context> context = isolate->GetCurrentContext();
1132 cons->NewInstance(context, argc, argv).ToLocalChecked();
1141 obj->value_ += 1;
1143 args.GetReturnValue().Set(Number::New(isolate, obj->value_));
1150 `binding.gyp`:
1192 wrapped objects around by unwrapping them with the Node.js helper function
1193 `node::ObjectWrap::Unwrap`. The following examples shows a function `add()`
1198 #include <node.h>
1219 Local<Context> context = isolate->GetCurrentContext();
1221 MyObject* obj1 = node::ObjectWrap::Unwrap<MyObject>(
1222 args[0]->ToObject(context).ToLocalChecked());
1223 MyObject* obj2 = node::ObjectWrap::Unwrap<MyObject>(
1224 args[1]->ToObject(context).ToLocalChecked());
1226 double sum = obj1->value() + obj2->value();
1231 MyObject::Init(exports->GetIsolate());
1250 #include <node.h>
1255 class MyObject : public node::ObjectWrap {
1279 #include <node.h>
1284 using node::AddEnvironmentCleanupHook;
1296 // Warning! This is not thread-safe, this addon cannot be used for worker
1309 tpl->SetClassName(String::NewFromUtf8(isolate, "MyObject").ToLocalChecked());
1310 tpl->InstanceTemplate()->SetInternalFieldCount(1);
1312 Local<Context> context = isolate->GetCurrentContext();
1313 constructor.Reset(isolate, tpl->GetFunction(context).ToLocalChecked());
1322 Local<Context> context = isolate->GetCurrentContext();
1326 double value = args[0]->IsUndefined() ?
1327 0 : args[0]->NumberValue(context).FromMaybe(0);
1329 obj->Wrap(args.This());
1337 cons->NewInstance(context, argc, argv).ToLocalChecked();
1348 Local<Context> context = isolate->GetCurrentContext();
1350 cons->NewInstance(context, argc, argv).ToLocalChecked();
1374 [Linking to libraries included with Node.js]: #linking-to-libraries-included-with-nodejs
1375 [Native Abstractions for Node.js]: https://github.com/nodejs/nan
1377 [`Worker`]: worker_threads.md#class-worker
1378 [bindings]: https://github.com/TooTallNate/node-bindings
1379 [download]: https://github.com/nodejs/node-addon-examples
1381 [implementation considerations]: n-api.md#implications-of-abi-stability
1382 [installation instructions]: https://github.com/nodejs/node-gyp#installation
1384 [node-gyp]: https://github.com/nodejs/node-gyp
1386 [v8-docs]: https://v8docs.nodesource.com/