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
@@ -85,7 +85,7 @@ NODE_MODULE(NODE_GYP_MODULE_NAME, Initialize)
85
85
} // namespace demo
86
86
```
87
87
88
- All Node.js Addons must export an initialization function following
88
+ All Node.js addons must export an initialization function following
89
89
the pattern:
90
90
91
91
```cpp
@@ -317,7 +317,7 @@ Once the source code has been written, it must be compiled into the binary
317
317
` addon.node ` file. To do so, create a file called ` binding.gyp ` in the
318
318
top-level of the project describing the build configuration of the module
319
319
using a JSON-like format. This file is used by [ node-gyp] [ ] , a tool written
320
- specifically to compile Node.js Addons .
320
+ specifically to compile Node.js addons .
321
321
322
322
``` json
323
323
{
@@ -333,7 +333,7 @@ specifically to compile Node.js Addons.
333
333
A version of the ` node-gyp ` utility is bundled and distributed with
334
334
Node.js as part of ` npm ` . This version is not made directly available for
335
335
developers to use and is intended only to support the ability to use the
336
- ` npm install ` command to compile and install Addons . Developers who wish to
336
+ ` npm install ` command to compile and install addons . Developers who wish to
337
337
use ` node-gyp ` directly can install it using the command
338
338
` npm install -g node-gyp ` . See the ` node-gyp ` [ installation instructions] [ ] for
339
339
more information, including platform-specific requirements.
@@ -346,11 +346,11 @@ will generate either a `Makefile` (on Unix platforms) or a `vcxproj` file
346
346
Next, invoke the ` node-gyp build ` command to generate the compiled ` addon.node `
347
347
file. This will be put into the ` build/Release/ ` directory.
348
348
349
- When using ` npm install ` to install a Node.js Addon , npm uses its own bundled
349
+ When using ` npm install ` to install a Node.js addon , npm uses its own bundled
350
350
version of ` node-gyp ` to perform this same set of actions, generating a
351
- compiled version of the Addon for the user's platform on demand.
351
+ compiled version of the addon for the user's platform on demand.
352
352
353
- Once built, the binary Addon can be used from within Node.js by pointing
353
+ Once built, the binary addon can be used from within Node.js by pointing
354
354
[ ` require() ` ] [ require ] to the built ` addon.node ` module:
355
355
356
356
``` js
@@ -361,12 +361,12 @@ console.log(addon.hello());
361
361
// Prints: 'world'
362
362
```
363
363
364
- Because the exact path to the compiled Addon binary can vary depending on how
365
- it is compiled (i.e. sometimes it may be in ` ./build/Debug/ ` ), Addons can use
364
+ Because the exact path to the compiled addon binary can vary depending on how
365
+ it is compiled (i.e. sometimes it may be in ` ./build/Debug/ ` ), addons can use
366
366
the [ bindings] [ ] package to load the compiled module.
367
367
368
368
While the ` bindings ` package implementation is more sophisticated in how it
369
- locates Addon modules, it is essentially using a ` try…catch ` pattern similar to:
369
+ locates addon modules, it is essentially using a ` try…catch ` pattern similar to:
370
370
371
371
``` js
372
372
try {
@@ -379,31 +379,31 @@ try {
379
379
### Linking to libraries included with Node.js
380
380
381
381
Node.js uses statically linked libraries such as V8, libuv and OpenSSL. All
382
- Addons are required to link to V8 and may link to any of the other dependencies
382
+ addons are required to link to V8 and may link to any of the other dependencies
383
383
as well. Typically, this is as simple as including the appropriate
384
384
` #include <...> ` statements (e.g. ` #include <v8.h> ` ) and ` node-gyp ` will locate
385
385
the appropriate headers automatically. However, there are a few caveats to be
386
386
aware of:
387
387
388
388
* When ` node-gyp ` runs, it will detect the specific release version of Node.js
389
389
and download either the full source tarball or just the headers. If the full
390
- source is downloaded, Addons will have complete access to the full set of
390
+ source is downloaded, addons will have complete access to the full set of
391
391
Node.js dependencies. However, if only the Node.js headers are downloaded, then
392
392
only the symbols exported by Node.js will be available.
393
393
394
394
* ` node-gyp ` can be run using the ` --nodedir ` flag pointing at a local Node.js
395
- source image. Using this option, the Addon will have access to the full set of
395
+ source image. Using this option, the addon will have access to the full set of
396
396
dependencies.
397
397
398
398
### Loading addons using ` require() `
399
399
400
- The filename extension of the compiled Addon binary is ` .node ` (as opposed
400
+ The filename extension of the compiled addon binary is ` .node ` (as opposed
401
401
to ` .dll ` or ` .so ` ). The [ ` require() ` ] [ require ] function is written to look for
402
402
files with the ` .node ` file extension and initialize those as dynamically-linked
403
403
libraries.
404
404
405
405
When calling [ ` require() ` ] [ require ] , the ` .node ` extension can usually be
406
- omitted and Node.js will still find and initialize the Addon . One caveat,
406
+ omitted and Node.js will still find and initialize the addon . One caveat,
407
407
however, is that Node.js will first attempt to locate and load modules or
408
408
JavaScript files that happen to share the same base name. For instance, if
409
409
there is a file ` addon.js ` in the same directory as the binary ` addon.node ` ,
@@ -413,26 +413,26 @@ and load it instead.
413
413
## Native abstractions for Node.js
414
414
415
415
Each of the examples illustrated in this document make direct use of the
416
- Node.js and V8 APIs for implementing Addons . The V8 API can, and has, changed
416
+ Node.js and V8 APIs for implementing addons . The V8 API can, and has, changed
417
417
dramatically from one V8 release to the next (and one major Node.js release to
418
- the next). With each change, Addons may need to be updated and recompiled in
418
+ the next). With each change, addons may need to be updated and recompiled in
419
419
order to continue functioning. The Node.js release schedule is designed to
420
420
minimize the frequency and impact of such changes but there is little that
421
421
Node.js can do to ensure stability of the V8 APIs.
422
422
423
423
The [ Native Abstractions for Node.js] [ ] (or ` nan ` ) provide a set of tools that
424
- Addon developers are recommended to use to keep compatibility between past and
424
+ addon developers are recommended to use to keep compatibility between past and
425
425
future releases of V8 and Node.js. See the ` nan ` [ examples] [ ] for an
426
426
illustration of how it can be used.
427
427
428
428
## N-API
429
429
430
430
> Stability: 2 - Stable
431
431
432
- N-API is an API for building native Addons . It is independent from
432
+ N-API is an API for building native addons . It is independent from
433
433
the underlying JavaScript runtime (e.g. V8) and is maintained as part of
434
434
Node.js itself. This API will be Application Binary Interface (ABI) stable
435
- across versions of Node.js. It is intended to insulate Addons from
435
+ across versions of Node.js. It is intended to insulate addons from
436
436
changes in the underlying JavaScript engine and allow modules
437
437
compiled for one version to run on later versions of Node.js without
438
438
recompilation. Addons are built/packaged with the same approach/tools
@@ -481,11 +481,11 @@ NAPI_MODULE(NODE_GYP_MODULE_NAME, init)
481
481
```
482
482
483
483
The functions available and how to use them are documented in
484
- [C/C++ Addons with N-API](n-api.html).
484
+ [C/C++ addons with N-API](n-api.html).
485
485
486
486
## Addon examples
487
487
488
- Following are some example Addons intended to help developers get started. The
488
+ Following are some example addons intended to help developers get started. The
489
489
examples make use of the V8 APIs. Refer to the online [V8 reference][v8-docs]
490
490
for help with the various V8 calls, and V8's [Embedder's Guide][] for an
491
491
explanation of several concepts used such as handles, scopes, function
@@ -511,7 +511,7 @@ filename to the `sources` array:
511
511
"sources" : [" addon.cc" , " myexample.cc" ]
512
512
```
513
513
514
- Once the ` binding.gyp ` file is ready, the example Addons can be configured and
514
+ Once the ` binding.gyp ` file is ready, the example addons can be configured and
515
515
built using ` node-gyp ` :
516
516
517
517
``` console
@@ -588,7 +588,7 @@ NODE_MODULE(NODE_GYP_MODULE_NAME, Init)
588
588
} // namespace demo
589
589
```
590
590
591
- Once compiled, the example Addon can be required and used from within Node.js:
591
+ Once compiled, the example addon can be required and used from within Node.js:
592
592
593
593
```js
594
594
// test.js
@@ -599,7 +599,7 @@ console.log('This should be eight:', addon.add(3, 5));
599
599
600
600
### Callbacks
601
601
602
- It is common practice within Addons to pass JavaScript functions to a C++
602
+ It is common practice within addons to pass JavaScript functions to a C++
603
603
function and execute them from there. The following example illustrates how
604
604
to invoke such callbacks:
605
605
@@ -642,7 +642,7 @@ NODE_MODULE(NODE_GYP_MODULE_NAME, Init)
642
642
```
643
643
644
644
This example uses a two-argument form of `Init()` that receives the full
645
- `module` object as the second argument. This allows the Addon to completely
645
+ `module` object as the second argument. This allows the addon to completely
646
646
overwrite `exports` with a single function instead of adding the function as a
647
647
property of `exports`.
648
648
0 commit comments