Using `AtExit()` without an `Environment*` pointer or providing
an argument is almost always a sign of improperly relying on global
state and/or using `AtExit()` as an addon when the addon-targeting
`AddEnvironmentCleanupHook()` would be the better choice.
Deprecate those variants. This also updates the addon docs to
refer to `AddEnvironmentCleanupHook()` rather than `AtExit()`.
PR-URL: https://github.com/nodejs/node/pull/30227
Reviewed-By: David Carlier <devnexen@gmail.com>
Reviewed-By: Franziska Hinkelmann <franziska.hinkelmann@gmail.com>
Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
This makes the actual behaviour match the documented (and arguably
the correct) behaviour.
PR-URL: https://github.com/nodejs/node/pull/30230
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Franziska Hinkelmann <franziska.hinkelmann@gmail.com>
Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com>
Instead of telling someone "It is important to do X", just tell them to
"Do X."
PR-URL: https://github.com/nodejs/node/pull/30108
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Delete "a number of" phrases in the docs. See what I did there? Ha ha.
Ha ha. Ha. ...heh.. <clears throat/>
PR-URL: https://github.com/nodejs/node/pull/30103
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: David Carlier <devnexen@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
The use of dashes -- in general, but especially in our docs -- can be
problematic. It is used inconsistently and there is always another form
of punctuation that is as good or better for the situation. In an effort
to reduce the number of variations we use to display the same types of
information, remove the various uses of dashes from the documentation.
PR-URL: https://github.com/nodejs/node/pull/30101
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Convert to asterisks when there are mixed styles in document.
Addresses Markdownlint MD004 rule
PR-URL: https://github.com/nodejs/node/pull/29516
Reviewed-By: David Carlier <devnexen@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Address Markdownlint MD006 rule.
Can flag when list items aren't indented far enough.
PR-URL: https://github.com/nodejs/node/pull/29390
Reviewed-By: David Carlier <devnexen@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
We've had a few comments that from the doc it might not
be clear that N-API is the recommended approach for Addons.
As a start, mention N-API early in the non N-API section
as the recommended approach unless lower level access
is required.
PR-URL: https://github.com/nodejs/node/pull/28922
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
This commit removes the usage of 'Note that' in the addons
documentation. Note that this phrase was not adding anything
meaningful to the docs.
PR-URL: https://github.com/nodejs/node/pull/28327
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
The addons documentation links to an external node-qt repo as
a production example. That repo hasn't been updated in over
five years. This commit removes the link.
PR-URL: https://github.com/nodejs/node/pull/28326
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
The N-API version of the hello example, returned "hello" instead of
"world".
PR-URL: https://github.com/nodejs/node/pull/26328
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Anto Aravinth <anto.aravinth.cse@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Currently there are a number of compiler warnings like the following:
../binding.cc:6:41:
warning: 'NewFromUtf8' is deprecated:
Use maybe version [-Wdeprecated-declarations]
args.GetReturnValue().Set(v8::String::NewFromUtf8(isolate, "world"));
^
/node/deps/v8/include/v8.h:2883:10:
note: 'NewFromUtf8' has been explicitly marked deprecated here
static V8_DEPRECATE_SOON(
^
/node/deps/v8/include/v8config.h:341:29:
note: expanded from macro 'V8_DEPRECATE_SOON'
declarator __attribute__((deprecated(message)))
^
This commit updates the code to use the maybe versions.
PR-URL: https://github.com/nodejs/node/pull/24216
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Currently there are compiler warnings is emitted:
../addon.cc:17:58:
warning: 'ToString' is deprecated:
Use maybe version [-Wdeprecated-declarations]
obj->Set(String::NewFromUtf8(isolate, "msg"),
args[0]->ToString(isolate));
^
deps/v8/include/v8.h:2537:3:
note: 'ToString' has been explicitly marked deprecated here
V8_DEPRECATED("Use maybe version",
^
This commit updates examples to use the non-deprecated versions.
PR-URL: https://github.com/nodejs/node/pull/23323
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
Currently the documentation for Wrapping C++ Objects doesn't explain
how to destruct an object by explicitly invoking the garbage collector.
This commit includes a modification to docs that explains how to force
the garbage collector to clear objects using V8's command line flags.
Fixes: https://github.com/nodejs/node/issues/19876
PR-URL: https://github.com/nodejs/node/pull/20431
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Yang Guo <yangguo@chromium.org>
Mention that ABI stability can be achieved only by linking to ABI-
stable parts of Node.js and to other libraries which are ABI-stable.
PR-URL: https://github.com/nodejs/node/pull/22508
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Introduces macros `NODE_MODULE_INITIALIZER` which expands to the name
of the special symbol that process.dlopen() will look for to initialize
an addon, and `NODE_MODULE_INIT()` which creates the boilerplate for
a context-aware module which can be loaded multiple times via the
special symbol mechanism.
Additionally, provides an example of using the new macro to construct
an addon which stores per-addon-instance data in a heap-allocated
structure that gets passed to each binding, rather than in a collection
of global static variables.
Re: https://github.com/nodejs/node/issues/21291#issuecomment-396729727
PR-URL: https://github.com/nodejs/node/pull/21318
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Ujjwal Sharma <usharma1998@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/21067
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
While some places list n-api as stable, the reference
in doc/api/addons.md was missed. This fixes that
instance.
Fixes: https://github.com/nodejs/node/issues/20645
PR-URL: https://github.com/nodejs/node/pull/20659
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Tobias Nießen <tniessen@tnie.de>
- using a length of 6 for `"hello"` includes a terminating null yielding
`"hello\u0000"`
- length of 5 would work,
but comparing to the N-API docs gives `NAPI_AUTO_LENGTH` instead
PR-URL: https://github.com/nodejs/node/pull/19205
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com>
Reviewed-By: Tobias Nießen <tniessen@tnie.de>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
libuv and zlib symbols are also purposefully re-exported by Node.js for
use in Addons.
Refs: https://github.com/nodejs/node/issues/17444
PR-URL: https://github.com/nodejs/node/pull/19013
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Reviewed-By: Matheus Marchini <matheus@sthima.com>
Reviewed-By: Yuta Hiroto <hello@about-hiroppy.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
No need to announce obvious example code as being example code. Remove
unneeded "for example" text as one small way to try to keep the docs
more concise..
PR-URL: https://github.com/nodejs/node/pull/18890
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Matheus Marchini <matheus@sthima.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Remove the various **Note:** prefixes throughout the docs.
PR-URL: https://github.com/nodejs/node/pull/18592
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
This reverts commit d9b59def72.
Breaks downloadable source tarball builds as we remove some files prior
to creating a tarball but those files are included in the comprehensive
list of dependencies listed in .deps.
Ref: https://github.com/nodejs/node/pull/17407
PR-URL: https://github.com/nodejs/node/pull/18287
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
* Get rid of recursive `make` when building the node binary. An earlier
commit makes GYP write out rules that we can use for proper dependency
tracking.
* Use module name 'binding' in addons.md and addons-napi/*/binding.gyp.
This massively simplifies the logic for generating the build rules.
* Check in auto-generated add-on tests from `doc/api/addons.md`. The
files change rarely and generating them dynamically causes no end of
race conditions and special-casing during the build.
PR-URL: https://github.com/nodejs/node/pull/17407
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Our Addons documentation has a "Hello world" example that
outlines all steps to build it. Adding the sources for this
"Hello world" example for N-API.
PR-URL: https://github.com/nodejs/node/pull/17425
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Tobias Nießen <tniessen@tnie.de>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
- Implements the make test-doc target that build, verify
and lint docs
- Lint the C++ snippets in addon docs
- When generating addons and running the JS linter,
use the global node executable if it is not built.
Therefore one does not have to build node in order to
run make test-doc.
PR-URL: https://github.com/nodejs/node/pull/16377
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Refael Ackermann <refack@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/13769
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Currently the nm_modname does not match the file name of the resulting
module. In fact, the nm_modname is pretty arbitrary. This seeks to
introduce some consistency into the nm_modname property by having the
name of the module appear in exactly one place: the "target_name"
property of the gyp target that builds the module.
PR-URL: https://github.com/nodejs/node/pull/15209
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Each page of the API documentation should have links to other versions
of the same page. This will make it easier to switch between the current
"live" release at nodejs.org and LTS versions.
PR-URL: https://github.com/nodejs/node/pull/10958
Fixes: https://github.com/nodejs/node/issues/10726
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: Evan Lucas <evanlucas@me.com>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
The sanity_check AtExit callback needs to come last to verify that the
other callbacks have been completed. This was not noticed before as this
code was not been executed.
PR-URL: https://github.com/nodejs/node/pull/14048
Reviewed-By: Michaël Zasso <targos@protonmail.com>
When working on commit 0d95a0b60a
("test: remove undef NDEBUG from at-exit addons test) I searched for
usages of undef NDEBUG but did not include the doc directory (but I did
include the test directory) and missed this one.
Commit 1f02569f8db9cb0101807df4982534738f0161b2 ("tools: fix
tools/addon-verify.js") enables the code in the "AtExit" section to be
included in the test/addons diretory and this code will again be
tested.
PR-URL: https://github.com/nodejs/node/pull/14048
Reviewed-By: Michaël Zasso <targos@protonmail.com>
The current implementation of addon-verify.js is including the code
for the "Function arguments" section in test/addons/01_callbacks and
there is no directory generated or the "Function arguments section".
This continues and leads to the last section, "AtExit", code to be
excluded. There is an test/addons/07_atexit_hooks but it contains code
from the "Passing wrapped objects around" section.
This commit modifies addon-verify to associate headers with code and
then iterates over the set and generates the files as a separate step.
PR-URL: https://github.com/nodejs/node/pull/14048
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Make the style of "Note:" paragraphs consistent and document the
guidelines in `doc/STYLE_GUIDE.md`.
PR-URL: https://github.com/nodejs/node/pull/13133
Fixes: https://github.com/nodejs/node/issues/13131
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Daijiro Wachi <daijiro.wachi@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
