3
3
<!-- introduced_in=v0.10.0-->
4
4
<!-- type=misc -->
5
5
6
- Addons are dynamically-linked shared objects written in C++. The
7
- [ ` require() ` ] [ require ] function can load Addons as ordinary Node.js modules.
6
+ _ Addons _ are dynamically-linked shared objects written in C++. The
7
+ [ ` require() ` ] [ require ] function can load addons as ordinary Node.js modules.
8
8
Addons provide an interface between JavaScript and C/C++ libraries.
9
9
10
- There are three options for implementing Addons : N-API, nan, or direct
10
+ There are three options for implementing addons : N-API, nan, or direct
11
11
use of internal V8, libuv and Node.js libraries. Unless there is a need for
12
12
direct access to functionality which is not exposed by N-API, use N-API.
13
- Refer to [ C/C++ Addons with N-API] ( n-api.html ) for more information on N-API.
13
+ Refer to [ C/C++ addons with N-API] ( n-api.html ) for more information on N-API.
14
14
15
- When not using N-API, implementing Addons is complicated,
15
+ When not using N-API, implementing addons is complicated,
16
16
involving knowledge of several components and APIs:
17
17
18
18
* V8: the C++ library Node.js uses to provide the
@@ -27,27 +27,27 @@ involving knowledge of several components and APIs:
27
27
access across all major operating systems to many common system tasks, such
28
28
as interacting with the filesystem, sockets, timers, and system events. libuv
29
29
also provides a pthreads-like threading abstraction that may be used to
30
- power more sophisticated asynchronous Addons that need to move beyond the
30
+ power more sophisticated asynchronous addons that need to move beyond the
31
31
standard event loop. Addon authors are encouraged to think about how to
32
32
avoid blocking the event loop with I/O or other time-intensive tasks by
33
33
off-loading work via libuv to non-blocking system operations, worker threads
34
34
or a custom use of libuv's threads.
35
35
36
- * Internal Node.js libraries. Node.js itself exports C++ APIs that Addons can
36
+ * Internal Node.js libraries. Node.js itself exports C++ APIs that addons can
37
37
use, the most important of which is the ` node::ObjectWrap ` class.
38
38
39
39
* Node.js includes other statically linked libraries including OpenSSL. These
40
40
other libraries are located in the ` deps/ ` directory in the Node.js source
41
41
tree. Only the libuv, OpenSSL, V8 and zlib symbols are purposefully
42
- re-exported by Node.js and may be used to various extents by Addons . See
42
+ re-exported by Node.js and may be used to various extents by addons . See
43
43
[ Linking to libraries included with Node.js] [ ] for additional information.
44
44
45
45
All of the following examples are available for [ download] [ ] and may
46
- be used as the starting-point for an Addon .
46
+ be used as the starting-point for an addon .
47
47
48
48
## Hello world
49
49
50
- This "Hello world" example is a simple Addon , written in C++, that is the
50
+ This "Hello world" example is a simple addon , written in C++, that is the
51
51
equivalent of the following JavaScript code:
52
52
53
53
``` js
@@ -84,7 +84,7 @@ NODE_MODULE(NODE_GYP_MODULE_NAME, Initialize)
84
84
} // namespace demo
85
85
```
86
86
87
- All Node.js Addons must export an initialization function following
87
+ All Node.js addons must export an initialization function following
88
88
the pattern:
89
89
90
90
```cpp
@@ -315,7 +315,7 @@ Once the source code has been written, it must be compiled into the binary
315
315
` addon.node ` file. To do so, create a file called ` binding.gyp ` in the
316
316
top-level of the project describing the build configuration of the module
317
317
using a JSON-like format. This file is used by [ node-gyp] [ ] , a tool written
318
- specifically to compile Node.js Addons .
318
+ specifically to compile Node.js addons .
319
319
320
320
``` json
321
321
{
@@ -331,7 +331,7 @@ specifically to compile Node.js Addons.
331
331
A version of the ` node-gyp ` utility is bundled and distributed with
332
332
Node.js as part of ` npm ` . This version is not made directly available for
333
333
developers to use and is intended only to support the ability to use the
334
- ` npm install ` command to compile and install Addons . Developers who wish to
334
+ ` npm install ` command to compile and install addons . Developers who wish to
335
335
use ` node-gyp ` directly can install it using the command
336
336
` npm install -g node-gyp ` . See the ` node-gyp ` [ installation instructions] [ ] for
337
337
more information, including platform-specific requirements.
@@ -344,11 +344,11 @@ will generate either a `Makefile` (on Unix platforms) or a `vcxproj` file
344
344
Next, invoke the ` node-gyp build ` command to generate the compiled ` addon.node `
345
345
file. This will be put into the ` build/Release/ ` directory.
346
346
347
- When using ` npm install ` to install a Node.js Addon , npm uses its own bundled
347
+ When using ` npm install ` to install a Node.js addon , npm uses its own bundled
348
348
version of ` node-gyp ` to perform this same set of actions, generating a
349
- compiled version of the Addon for the user's platform on demand.
349
+ compiled version of the addon for the user's platform on demand.
350
350
351
- Once built, the binary Addon can be used from within Node.js by pointing
351
+ Once built, the binary addon can be used from within Node.js by pointing
352
352
[ ` require() ` ] [ require ] to the built ` addon.node ` module:
353
353
354
354
``` js
@@ -359,12 +359,12 @@ console.log(addon.hello());
359
359
// Prints: 'world'
360
360
```
361
361
362
- Because the exact path to the compiled Addon binary can vary depending on how
363
- it is compiled (i.e. sometimes it may be in ` ./build/Debug/ ` ), Addons can use
362
+ Because the exact path to the compiled addon binary can vary depending on how
363
+ it is compiled (i.e. sometimes it may be in ` ./build/Debug/ ` ), addons can use
364
364
the [ bindings] [ ] package to load the compiled module.
365
365
366
366
While the ` bindings ` package implementation is more sophisticated in how it
367
- locates Addon modules, it is essentially using a ` try…catch ` pattern similar to:
367
+ locates addon modules, it is essentially using a ` try…catch ` pattern similar to:
368
368
369
369
``` js
370
370
try {
@@ -377,31 +377,31 @@ try {
377
377
### Linking to libraries included with Node.js
378
378
379
379
Node.js uses statically linked libraries such as V8, libuv and OpenSSL. All
380
- Addons are required to link to V8 and may link to any of the other dependencies
380
+ addons are required to link to V8 and may link to any of the other dependencies
381
381
as well. Typically, this is as simple as including the appropriate
382
382
` #include <...> ` statements (e.g. ` #include <v8.h> ` ) and ` node-gyp ` will locate
383
383
the appropriate headers automatically. However, there are a few caveats to be
384
384
aware of:
385
385
386
386
* When ` node-gyp ` runs, it will detect the specific release version of Node.js
387
387
and download either the full source tarball or just the headers. If the full
388
- source is downloaded, Addons will have complete access to the full set of
388
+ source is downloaded, addons will have complete access to the full set of
389
389
Node.js dependencies. However, if only the Node.js headers are downloaded, then
390
390
only the symbols exported by Node.js will be available.
391
391
392
392
* ` node-gyp ` can be run using the ` --nodedir ` flag pointing at a local Node.js
393
- source image. Using this option, the Addon will have access to the full set of
393
+ source image. Using this option, the addon will have access to the full set of
394
394
dependencies.
395
395
396
396
### Loading addons using ` require() `
397
397
398
- The filename extension of the compiled Addon binary is ` .node ` (as opposed
398
+ The filename extension of the compiled addon binary is ` .node ` (as opposed
399
399
to ` .dll ` or ` .so ` ). The [ ` require() ` ] [ require ] function is written to look for
400
400
files with the ` .node ` file extension and initialize those as dynamically-linked
401
401
libraries.
402
402
403
403
When calling [ ` require() ` ] [ require ] , the ` .node ` extension can usually be
404
- omitted and Node.js will still find and initialize the Addon . One caveat,
404
+ omitted and Node.js will still find and initialize the addon . One caveat,
405
405
however, is that Node.js will first attempt to locate and load modules or
406
406
JavaScript files that happen to share the same base name. For instance, if
407
407
there is a file ` addon.js ` in the same directory as the binary ` addon.node ` ,
@@ -411,26 +411,26 @@ and load it instead.
411
411
## Native abstractions for Node.js
412
412
413
413
Each of the examples illustrated in this document make direct use of the
414
- Node.js and V8 APIs for implementing Addons . The V8 API can, and has, changed
414
+ Node.js and V8 APIs for implementing addons . The V8 API can, and has, changed
415
415
dramatically from one V8 release to the next (and one major Node.js release to
416
- the next). With each change, Addons may need to be updated and recompiled in
416
+ the next). With each change, addons may need to be updated and recompiled in
417
417
order to continue functioning. The Node.js release schedule is designed to
418
418
minimize the frequency and impact of such changes but there is little that
419
419
Node.js can do to ensure stability of the V8 APIs.
420
420
421
421
The [ Native Abstractions for Node.js] [ ] (or ` nan ` ) provide a set of tools that
422
- Addon developers are recommended to use to keep compatibility between past and
422
+ addon developers are recommended to use to keep compatibility between past and
423
423
future releases of V8 and Node.js. See the ` nan ` [ examples] [ ] for an
424
424
illustration of how it can be used.
425
425
426
426
## N-API
427
427
428
428
> Stability: 2 - Stable
429
429
430
- N-API is an API for building native Addons . It is independent from
430
+ N-API is an API for building native addons . It is independent from
431
431
the underlying JavaScript runtime (e.g. V8) and is maintained as part of
432
432
Node.js itself. This API will be Application Binary Interface (ABI) stable
433
- across versions of Node.js. It is intended to insulate Addons from
433
+ across versions of Node.js. It is intended to insulate addons from
434
434
changes in the underlying JavaScript engine and allow modules
435
435
compiled for one version to run on later versions of Node.js without
436
436
recompilation. Addons are built/packaged with the same approach/tools
@@ -479,11 +479,11 @@ NAPI_MODULE(NODE_GYP_MODULE_NAME, init)
479
479
```
480
480
481
481
The functions available and how to use them are documented in
482
- [C/C++ Addons with N-API](n-api.html).
482
+ [C/C++ addons with N-API](n-api.html).
483
483
484
484
## Addon examples
485
485
486
- Following are some example Addons intended to help developers get started. The
486
+ Following are some example addons intended to help developers get started. The
487
487
examples make use of the V8 APIs. Refer to the online [V8 reference][v8-docs]
488
488
for help with the various V8 calls, and V8's [Embedder's Guide][] for an
489
489
explanation of several concepts used such as handles, scopes, function
@@ -509,7 +509,7 @@ filename to the `sources` array:
509
509
"sources" : [" addon.cc" , " myexample.cc" ]
510
510
```
511
511
512
- Once the ` binding.gyp ` file is ready, the example Addons can be configured and
512
+ Once the ` binding.gyp ` file is ready, the example addons can be configured and
513
513
built using ` node-gyp ` :
514
514
515
515
``` console
@@ -583,7 +583,7 @@ NODE_MODULE(NODE_GYP_MODULE_NAME, Init)
583
583
} // namespace demo
584
584
```
585
585
586
- Once compiled, the example Addon can be required and used from within Node.js:
586
+ Once compiled, the example addon can be required and used from within Node.js:
587
587
588
588
```js
589
589
// test.js
@@ -594,7 +594,7 @@ console.log('This should be eight:', addon.add(3, 5));
594
594
595
595
### Callbacks
596
596
597
- It is common practice within Addons to pass JavaScript functions to a C++
597
+ It is common practice within addons to pass JavaScript functions to a C++
598
598
function and execute them from there. The following example illustrates how
599
599
to invoke such callbacks:
600
600
@@ -635,7 +635,7 @@ NODE_MODULE(NODE_GYP_MODULE_NAME, Init)
635
635
```
636
636
637
637
This example uses a two-argument form of `Init()` that receives the full
638
- `module` object as the second argument. This allows the Addon to completely
638
+ `module` object as the second argument. This allows the addon to completely
639
639
overwrite `exports` with a single function instead of adding the function as a
640
640
property of `exports`.
641
641
0 commit comments