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 <jasnell@gmail.com> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com> Reviewed-By: Daijiro Wachi <daijiro.wachi@gmail.com>
This commit is contained in:
Rich Trott
parent
cc7ec889e8
commit
3e9caaf505
@ -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
|
||||
@ -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 <v8.h>`) 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`.
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user