Skip to content

Commit

Permalink
doc: use consistent capitalization for addons
Browse files Browse the repository at this point in the history 
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: #34536
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Trivikram Kamat <[email protected]>
Reviewed-By: Daijiro Wachi <[email protected]>
  • Loading branch information
@Trott @addaleax
Trott authored and addaleax committed Sep 22, 2020
1 parent 2410a0f commit b4b2057
Showing 1 changed file with 35 additions and 35 deletions.
70 changes: 35 additions & 35 deletions doc/api/addons.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,16 +3,16 @@
<!--introduced_in=v0.10.0-->
<!-- type=misc -->

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
Expand All @@ -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
Expand Down Expand Up @@ -85,7 +85,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
Expand Down Expand Up @@ -317,7 +317,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
{
Expand All @@ -333,7 +333,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.
Expand All @@ -346,11 +346,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
Expand All @@ -361,12 +361,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 {
Expand All @@ -379,31 +379,31 @@ 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 <v8.h>`) and `node-gyp` will locate
the appropriate headers automatically. However, there are a few caveats to be
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`,
Expand All @@ -413,26 +413,26 @@ 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.

## N-API

> 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
Expand Down Expand Up @@ -481,11 +481,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
Expand All @@ -511,7 +511,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
Expand Down Expand Up @@ -588,7 +588,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
Expand All @@ -599,7 +599,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:

Expand Down Expand Up @@ -642,7 +642,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`.
Expand Down

0 comments on commit b4b2057

Please sign in to comment.