From b69ff2ff602adb7cf882cef42eb7ac15a01d7c85 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Mon, 27 Jul 2020 22:19:31 -0700 Subject: [PATCH] doc: use consistent capitalization for addons Sometimes _addon_ is capitalized and sometimes not. Capitalizing it seems peculiar and hard to justify. Standardize on treating it like other common nouns. PR-URL: https://github.com/nodejs/node/pull/34536 Reviewed-By: James M Snell Reviewed-By: Trivikram Kamat Reviewed-By: Daijiro Wachi --- doc/api/addons.md | 70 +++++++++++++++++++++++------------------------ 1 file changed, 35 insertions(+), 35 deletions(-) diff --git a/doc/api/addons.md b/doc/api/addons.md index fca5d2a154db4f..0e7bf4ca9f2563 100644 --- a/doc/api/addons.md +++ b/doc/api/addons.md @@ -3,16 +3,16 @@ -Addons are dynamically-linked shared objects written in C++. The -[`require()`][require] function can load Addons as ordinary Node.js modules. +_Addons_ are dynamically-linked shared objects written in C++. The +[`require()`][require] function can load addons as ordinary Node.js modules. Addons provide an interface between JavaScript and C/C++ libraries. -There are three options for implementing Addons: N-API, nan, or direct +There are three options for implementing addons: N-API, nan, or direct use of internal V8, libuv and Node.js libraries. Unless there is a need for direct access to functionality which is not exposed by N-API, use N-API. -Refer to [C/C++ Addons with N-API](n-api.html) for more information on N-API. +Refer to [C/C++ addons with N-API](n-api.html) for more information on N-API. -When not using N-API, implementing Addons is complicated, +When not using N-API, implementing addons is complicated, involving knowledge of several components and APIs: * V8: the C++ library Node.js uses to provide the @@ -27,27 +27,27 @@ involving knowledge of several components and APIs: 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 + 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 C++ APIs that Addons can +* Internal Node.js libraries. Node.js itself exports C++ APIs that addons can use, the most important of which is the `node::ObjectWrap` class. * Node.js includes other statically linked libraries including OpenSSL. These other libraries are located in the `deps/` directory in the Node.js source tree. Only the libuv, OpenSSL, V8 and zlib symbols are purposefully - re-exported by Node.js and may be used to various extents by Addons. See + re-exported by Node.js and may be used to various extents by addons. See [Linking to libraries included with Node.js][] for additional information. All of the following examples are available for [download][] and may -be used as the starting-point for an Addon. +be used as the starting-point for an addon. ## Hello world -This "Hello world" example is a simple Addon, written in C++, that is the +This "Hello world" example is a simple addon, written in C++, that is the equivalent of the following JavaScript code: ```js @@ -84,7 +84,7 @@ NODE_MODULE(NODE_GYP_MODULE_NAME, Initialize) } // namespace demo ``` -All Node.js Addons must export an initialization function following +All Node.js addons must export an initialization function following the pattern: ```cpp @@ -315,7 +315,7 @@ 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. +specifically to compile Node.js addons. ```json { @@ -331,7 +331,7 @@ specifically to compile Node.js Addons. 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 +`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. @@ -344,11 +344,11 @@ will generate either a `Makefile` (on Unix platforms) or a `vcxproj` file 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 +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. +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 +Once built, the binary addon can be used from within Node.js by pointing [`require()`][require] to the built `addon.node` module: ```js @@ -359,12 +359,12 @@ console.log(addon.hello()); // Prints: 'world' ``` -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 +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. While the `bindings` package implementation is more sophisticated in how it -locates Addon modules, it is essentially using a `try…catch` pattern similar to: +locates addon modules, it is essentially using a `try…catch` pattern similar to: ```js try { @@ -377,7 +377,7 @@ try { ### Linking to libraries included with Node.js Node.js uses statically linked libraries such as V8, libuv and OpenSSL. All -Addons are required to link to V8 and may link to any of the other dependencies +addons are required to link to V8 and may link to any of the other dependencies as well. Typically, this is as simple as including the appropriate `#include <...>` statements (e.g. `#include `) and `node-gyp` will locate the appropriate headers automatically. However, there are a few caveats to be @@ -385,23 +385,23 @@ aware of: * When `node-gyp` runs, it will detect the specific release version of Node.js and download either the full source tarball or just the headers. If the full -source is downloaded, Addons will have complete access to the full set of +source is downloaded, addons will have complete access to the full set of Node.js dependencies. However, if only the Node.js headers are downloaded, then only the symbols exported by Node.js will be available. * `node-gyp` can be run using the `--nodedir` flag pointing at a local Node.js -source image. Using this option, the Addon will have access to the full set of +source image. Using this option, the addon will have access to the full set of dependencies. ### Loading addons using `require()` -The filename extension of the compiled Addon binary is `.node` (as opposed +The filename extension of the compiled addon binary is `.node` (as opposed to `.dll` or `.so`). The [`require()`][require] function is written to look for files with the `.node` file extension and initialize those as dynamically-linked libraries. When calling [`require()`][require], the `.node` extension can usually be -omitted and Node.js will still find and initialize the Addon. One caveat, +omitted and Node.js will still find and initialize the addon. One caveat, however, is that Node.js will first attempt to locate and load modules or JavaScript files that happen to share the same base name. For instance, if there is a file `addon.js` in the same directory as the binary `addon.node`, @@ -411,15 +411,15 @@ and load it instead. ## Native abstractions for Node.js Each of the examples illustrated in this document make direct use of the -Node.js and V8 APIs for implementing Addons. The V8 API can, and has, changed +Node.js and V8 APIs for implementing addons. The V8 API can, and has, changed dramatically from one V8 release to the next (and one major Node.js release to -the next). With each change, Addons may need to be updated and recompiled in +the next). With each change, addons may need to be updated and recompiled in order to continue functioning. The Node.js release schedule is designed to minimize the frequency and impact of such changes but there is little that Node.js can do to ensure stability of the V8 APIs. The [Native Abstractions for Node.js][] (or `nan`) provide a set of tools that -Addon developers are recommended to use to keep compatibility between past and +addon developers are recommended to use to keep compatibility between past and future releases of V8 and Node.js. See the `nan` [examples][] for an illustration of how it can be used. @@ -427,10 +427,10 @@ illustration of how it can be used. > Stability: 2 - Stable -N-API is an API for building native Addons. It is independent from +N-API is an API for building native addons. It is independent from the underlying JavaScript runtime (e.g. V8) and is maintained as part of Node.js itself. This API will be Application Binary Interface (ABI) stable -across versions of Node.js. It is intended to insulate Addons from +across versions of Node.js. It is intended to insulate addons from changes in the underlying JavaScript engine and allow modules compiled for one version to run on later versions of Node.js without recompilation. Addons are built/packaged with the same approach/tools @@ -479,11 +479,11 @@ NAPI_MODULE(NODE_GYP_MODULE_NAME, init) ``` The functions available and how to use them are documented in -[C/C++ Addons with N-API](n-api.html). +[C/C++ addons with N-API](n-api.html). ## Addon examples -Following are some example Addons intended to help developers get started. The +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 @@ -509,7 +509,7 @@ filename to the `sources` array: "sources": ["addon.cc", "myexample.cc"] ``` -Once the `binding.gyp` file is ready, the example Addons can be configured and +Once the `binding.gyp` file is ready, the example addons can be configured and built using `node-gyp`: ```console @@ -583,7 +583,7 @@ NODE_MODULE(NODE_GYP_MODULE_NAME, Init) } // namespace demo ``` -Once compiled, the example Addon can be required and used from within Node.js: +Once compiled, the example addon can be required and used from within Node.js: ```js // test.js @@ -594,7 +594,7 @@ console.log('This should be eight:', addon.add(3, 5)); ### Callbacks -It is common practice within Addons to pass JavaScript functions to a C++ +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: @@ -635,7 +635,7 @@ NODE_MODULE(NODE_GYP_MODULE_NAME, Init) ``` 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 +`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`.