| FazBrowse GitHub Viewer | Trending | | Home |
| Tools: [Download Repo ZIP] [Original HTTPS Page] |
1 parent 8cc9e5e commit b69ff2f
1 file changed
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -3,16 +3,16 @@ | |||
| 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 | ||
| Back | FazBrowse Home | New Git URL |
0 commit comments