Skip to content
Merged
Changes from 1 commit
Commits
Show all changes
79 commits
Select commit Hold shift + click to select a range
f46649b
util: print External address from inspect
rosaxxny Jul 16, 2020
465968c
console: document the behavior of console.assert()
Jul 23, 2020
692a735
doc: use sentence-case for headers in SECURITY.md
Trott Jul 27, 2020
70e9ece
build: toolchain.gypi and node_gyp.py cleanup
Jul 9, 2020
14656e1
async_hooks: don't reuse resource in HttpAgent when queued
puzpuzpuz Jul 20, 2020
9c442f9
test: remove unneeded flag check in test-vm-memleak
Trott Jul 27, 2020
2703fe4
n-api: simplify bigint-from-word creation
Jul 29, 2020
70cf3cb
build: auto start Jenkins CI via PR labels
mmarchini Jun 27, 2020
c8104f3
doc: update .mailmap for mmarchini
mmarchini Jul 31, 2020
7a28c3d
doc: update mmarchini contact info
mmarchini Jul 31, 2020
212d17f
doc: add mmarchini pronouns
mmarchini Jul 31, 2020
8cc9e5e
n-api: support type-tagging objects
Jun 14, 2019
b69ff2f
doc: use consistent capitalization for addons
Trott Jul 28, 2020
f393ae9
doc: simplify and clarify console.assert() documentation
Trott Jul 29, 2020
be23e23
doc: use consistent spelling for "falsy"
Trott Jul 29, 2020
4af5dbd
build: fix auto-start-ci script path
mmarchini Jul 31, 2020
befbaf3
build: don't run auto-start-ci on push
mmarchini Aug 1, 2020
44e6c01
esm: fix hook mistypes and links to types
DerekNonGeneric Jul 7, 2020
c4457d8
benchmark: always throw the same Error instance
addaleax Jul 26, 2020
335cb0d
lib: absorb `path` error cases
gireeshpunathil Jul 26, 2020
e2bea73
doc: clarify N-API version 1
mhdawson Jul 13, 2020
c1abc8d
src: fix unused namespace member in node_util
puzpuzpuz Jul 30, 2020
36fd3da
http: provide keep-alive timeout response header
ronag Jul 30, 2020
d7eaf3a
doc: revise N-API versions matrix text
Trott Jul 30, 2020
7322e58
http: reset headers timeout on headers complete
ronag Jul 31, 2020
10dd7a0
doc: add DerekNonGeneric to collaborators
DerekNonGeneric Aug 2, 2020
0a9389b
doc: mention null special-case for `napi_typeof`
goto-bus-stop Jul 31, 2020
9af6264
async_hooks: execute destroy hooks earlier
Flarna Jul 13, 2020
7c4e1db
async_hooks: fix resource stack for deep stacks
addaleax Jul 31, 2020
283f5c3
test: fix flaky http-parser-timeout-reset
ronag Aug 3, 2020
1b0d3b2
doc: document the connection event for HTTP2 & TLS servers
pimterry Jul 27, 2020
dba869e
test: change Fixes: to Refs:
Trott Jul 30, 2020
18ca52d
async_hooks: fix id assignment in fast-path promise hook
puzpuzpuz Jul 28, 2020
2d2ea99
tools: add meta.fixable to fixable lint rules
cjihrig Aug 1, 2020
72f357a
tools: update ESLint to 7.6.0
cjihrig Aug 1, 2020
ae64ec4
repl: give repl entries unique names
bmeck Jul 14, 2020
d6b0a40
test: replace flaky pummel regression tests
addaleax Jul 27, 2020
d972c54
doc: clarify process.title inconsistencies
coreybutler Jul 29, 2020
ba137e0
doc: add release key for Ruy Adorno
ruyadorno Aug 5, 2020
938842e
repl: improve static import error message in repl
MylesBorins May 27, 2020
338994f
build: increase startCI verbosity and fix job name
mmarchini Aug 5, 2020
3eabb7e
policy: increase tests via permutation matrix
bmeck Jul 16, 2020
7be68cd
test: convert most N-API tests from C++ to C
Aug 3, 2020
d0a599a
module: unflag Top-Level Await
MylesBorins Jul 29, 2020
c21e62f
module: handle Top-Level Await non-fulfills better
addaleax Aug 6, 2020
22f499f
build: enable build for node-v8 push
gengjiawen Aug 5, 2020
221802d
build: run CI on release branches
codebytere Aug 6, 2020
4dbb931
async_hooks: don't read resource if ALS is disabled
Flarna Aug 3, 2020
ffd2c7a
meta: enable http2 team for CODEOWNERS
Trott Jul 28, 2020
a503470
crypto: add OP flag constants added in OpenSSL v1.1.1
mkrawczuk Jun 17, 2020
a0caf8c
doc: fix typo in path.md
Jul 29, 2020
767a5cb
doc: update fs.watch() availability for IBM i
Aug 3, 2020
4cd9c4f
test: add debugging for test-https-foafssl.js
Trott Aug 2, 2020
27333b1
test: add debugging for callbacks in test-https-foafssl.js
Trott Aug 2, 2020
7b4d40c
doc: edit process.title note for brevity and clarity
Trott Aug 4, 2020
8ff9caa
deps: update to uvwasi 0.0.10
cjihrig Aug 4, 2020
c4d373b
wasi: add __wasi_fd_filestat_set_times() test
cjihrig Aug 4, 2020
3132878
src: fix `size` underflow in CallbackQueue
addaleax Aug 7, 2020
4369c2a
src: spin shutdown loop while immediates are pending
addaleax Aug 7, 2020
f0b364f
build: do not run auto-start-ci on forks
evanlucas Aug 6, 2020
df8f9a4
doc: add Ricky Zhou to collaborators
rickyes Aug 8, 2020
33777a3
test: fix wrong method call
gengjiawen Aug 5, 2020
3ecb16b
repl: use _REPL_ in user-facing text
Trott Aug 6, 2020
7887ce2
net: don't return the stream object from onStreamRead
robey Jul 15, 2020
0c4226e
repl: use _Node.js_ in user-facing REPL text
Trott Aug 6, 2020
ef4fb68
async_hooks: add AsyncResource.bind utility
jasnell Jul 31, 2020
0730c76
async_hooks: improve property descriptors in als.bind
Flarna Aug 4, 2020
641a5fb
async_hooks: avoid unneeded AsyncResource creation
Flarna Aug 3, 2020
8630f34
n-api,src: provide asynchronous cleanup hooks
addaleax Jul 31, 2020
db6f9bd
async_hooks: avoid GC tracking of AsyncResource in ALS
Flarna Aug 3, 2020
4ed89a3
n-api: fix use-after-free with napi_remove_async_cleanup_hook
addaleax Aug 7, 2020
a944dab
doc: use _Class Method_ in async_hooks.md
Trott Aug 4, 2020
e97fe4b
src: fix linter failures
addaleax Jul 31, 2020
af0cfeb
tools: fix C++ import checker argument expansion
addaleax Jul 31, 2020
5b5f5f9
doc: tidy some addons.md text
Trott Aug 6, 2020
4efc5f6
lib: use non-symbols in isURLInstance check
codebytere Aug 4, 2020
41d0cf7
doc: use _Static method_ instead of _Class Method_
Trott Aug 7, 2020
bd00f26
meta: uncomment all codeowners
mmarchini Aug 7, 2020
b45ea94
2020-08-11, Version 14.8.0 (Current)
codebytere Aug 10, 2020
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
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: #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>
  • Loading branch information
Trott authored and codebytere committed Aug 5, 2020
commit b69ff2ff602adb7cf882cef42eb7ac15a01d7c85
70 changes: 35 additions & 35 deletions doc/api/addons.md
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 @@ -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
Expand Down Expand Up @@ -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
{
Expand All @@ -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.
Expand All @@ -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
Expand All @@ -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 {
Expand All @@ -377,31 +377,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 @@ -411,26 +411,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 @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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:

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

Expand Down