Skip to content

Commit 06d96f7

Browse files
author
Gabriel Schulhof
committed
Move doc to own-dependencies section
1 parent 2f62e74 commit 06d96f7

File tree

1 file changed

+74
-70
lines changed

1 file changed

+74
-70
lines changed

doc/api/addons.md

+74-70
Original file line numberDiff line numberDiff line change
@@ -251,74 +251,6 @@ down. If necessary, such hooks can be removed using
251251
`RemoveEnvironmentCleanupHook()` before they are run, which has the same
252252
signature.
253253
254-
#### ABI declaration
255-
256-
Node.js is available from a number of sources besides the [official
257-
distribution][]. Since the various versions of Node.js are configured
258-
differently at build time, the resulting runtime ABI may be different. For
259-
example, version 10 of Node.js as shipped by Debian GNU/Linux may have a
260-
different ABI than version 10 of Node.js as available from the official
261-
distribution.
262-
263-
The Node.js ABI consists of various different, independent parts, such as V8,
264-
openssl, libuv, and others. Native addons may use some, all, or even just one of
265-
these independent parts of the Node.js ABI. Thus, when Node.js is tasked with
266-
loading an addon, at which time it needs to determine whether the addon is ABI-
267-
compatible, it needs ABI information provided by the addon. The addon normally
268-
provides this information as a single number (`NODE_MODULE_VERSION`) which is
269-
stored inside the addon and which is compared against the value present in the
270-
running Node.js process at addon load time.
271-
272-
Since `NODE_MODULE_VERSION` reflects only the Node.js major version against
273-
which the addon was built, it may match the running Node.js process even though
274-
some of the independent parts of the ABI are mismatched. To address this problem
275-
the addon may optionally declare which portions of the Node.js ABI it uses by
276-
invoking the `NODE_MODULE_DECLARE_ABI` macro. Any portions of the ABI included
277-
as a parameter to the macro will be checked during addon load in addition to
278-
`NODE_MODULE_VERSION` in order to ensure that all ABIs declared by the addon
279-
have the version as requested by the addon. Node.js assumes that ABIs not
280-
included in the invocation of the `NODE_MODULE_DECLARE_ABI` macro are not used
281-
by the addon.
282-
283-
The `NODE_MODULE_DECLARE_ABI` macro may be invoked as follows:
284-
```C++
285-
NODE_MODULE_DECLARE_ABI(
286-
NODE_MODULE_ABI_VENDOR_VERSION,
287-
NODE_MODULE_ABI_ENGINE_VERSION,
288-
NODE_MODULE_ABI_OPENSSL_VERSION)
289-
```
290-
Note that there must be no semicolon at the end of the declaration.
291-
292-
The following parameters can be passed to `NODE_MODULE_DECLARE_ABI`:
293-
* `NODE_MODULE_ABI_VERSION_TERMINATOR` - this is a sentinel indicating the end
294-
of the list of ABI declarations. It need not normally be used by addons.
295-
296-
* `NODE_MODULE_ABI_VENDOR_VERSION` - this declaration ties the addon to a
297-
specific vendor's version of Node.js. For example, if the addon is built against
298-
the official disitrbution of Node.js, it will not load on a version of Node.js
299-
provided by the Debian GNU/Linux project nor will it load on a version of
300-
Electron.
301-
302-
* `NODE_MODULE_ABI_ENGINE_VERSION` - this declaration ties the addon to a
303-
specific JavaScript engine version. It will fail to load on a version of Node.js
304-
that provides a different JavaScript engine version.
305-
306-
* `NODE_MODULE_ABI_OPENSSL_VERSION` - this declaration ties the addon to a
307-
specific version of the OpenSSL library. It will not load on a version of
308-
Node.js that provides a different version of the OpenSSL library.
309-
310-
* `NODE_MODULE_ABI_LIBUV_VERSION` - this declaration ties the addon to a
311-
specific version of the libuv library. It will fail to load on a version of
312-
Node.js that provides a different version of libuv.
313-
314-
* `NODE_MODULE_ABI_ICU_VERSION` - this declaration ties the addon to a
315-
specific version of the ICU library. It will fail to load on a version of
316-
Node.js that provides a different version of the ICU library.
317-
318-
* `NODE_MODULE_ABI_CARES_VERSION` - this declaration ties the addon to a
319-
specific version of the c-ares library. It will fail to load on a version of
320-
Node.js that provides a different version of the c-ares library.
321-
322254
### Building
323255
324256
Once the source code has been written, it must be compiled into the binary
@@ -391,8 +323,8 @@ try {
391323
### Linking to Node.js' own dependencies
392324

393325
Node.js uses a number of statically linked libraries such as V8, libuv and
394-
OpenSSL. All Addons are required to link to V8 and may link to any of the
395-
other dependencies as well. Typically, this is as simple as including
326+
OpenSSL. All addons are required to link to either V8 or N-API and may link to
327+
any of the other dependencies as well. Typically, this is as simple as including
396328
the appropriate `#include <...>` statements (e.g. `#include <v8.h>`) and
397329
`node-gyp` will locate the appropriate headers automatically. However, there
398330
are a few caveats to be aware of:
@@ -407,6 +339,78 @@ only the symbols exported by Node.js will be available.
407339
source image. Using this option, the Addon will have access to the full set of
408340
dependencies.
409341

342+
Node.js is available from a number of sources besides the [official
343+
distribution][]. Since the various versions of Node.js are configured
344+
differently at build time, the resulting runtime ABI of the statically linked
345+
libraries may be different. For example, version 10 of Node.js as shipped by
346+
Debian GNU/Linux may have a different ABI than version 10 of Node.js as
347+
available from the official distribution.
348+
349+
The Node.js ABI consists of various different, independent parts, such as V8,
350+
OpenSSL, libuv, and others. Native addons may use some, all, or even just one of
351+
these independent parts of the Node.js ABI. Thus, when Node.js is tasked with
352+
loading an addon, at which time it needs to determine whether the addon is ABI-
353+
compatible, it needs ABI information provided by the addon. The addon normally
354+
provides this information as a single number (`NODE_MODULE_VERSION`) which is
355+
stored inside the addon and which is compared against the value present in the
356+
running Node.js process at addon load time.
357+
358+
Since `NODE_MODULE_VERSION` reflects only the Node.js major version against
359+
which the addon was built, it may match the running Node.js process even though
360+
some of the independent parts of the ABI are mismatched. To address this problem
361+
the addon may optionally declare which portions of the Node.js ABI it uses by
362+
invoking the `NODE_MODULE_DECLARE_ABI` macro. Any portions of the ABI included
363+
as a parameter to the macro will be checked during addon load in addition to
364+
`NODE_MODULE_VERSION` in order to ensure that all ABIs declared by the addon
365+
have the version as requested by the addon. Node.js assumes that ABIs not
366+
included in the invocation of the `NODE_MODULE_DECLARE_ABI` macro are not used
367+
by the addon.
368+
369+
If there is a mismatch between any ABI version number declared by the addon and
370+
the corresponding ABI version number as present in the Node.js process
371+
attempting to load the addon, Node.js will refuse to load the addon and throw an
372+
exception in which it indicates which ABIs were mismatched.
373+
374+
The `NODE_MODULE_DECLARE_ABI` macro may be invoked as follows:
375+
```C++
376+
NODE_MODULE_DECLARE_ABI(
377+
NODE_MODULE_ABI_VENDOR_VERSION,
378+
NODE_MODULE_ABI_ENGINE_VERSION,
379+
NODE_MODULE_ABI_OPENSSL_VERSION)
380+
```
381+
Note that there must be no semicolon at the end of the declaration.
382+
383+
One or more of the following parameters may be passed to
384+
`NODE_MODULE_DECLARE_ABI`:
385+
* `NODE_MODULE_ABI_VERSION_TERMINATOR` - this is a sentinel indicating the end
386+
of the list of ABI declarations. It need not normally be used by addons.
387+
388+
* `NODE_MODULE_ABI_VENDOR_VERSION` - this declaration ties the addon to a
389+
specific vendor's version of Node.js. For example, if the addon is built against
390+
the official disitrbution of Node.js, it will not load on a version of Node.js
391+
provided by the Debian GNU/Linux project nor will it load on a version of
392+
Electron.
393+
394+
* `NODE_MODULE_ABI_ENGINE_VERSION` - this declaration ties the addon to a
395+
specific JavaScript engine version. It will fail to load on a version of Node.js
396+
that provides a different JavaScript engine version.
397+
398+
* `NODE_MODULE_ABI_OPENSSL_VERSION` - this declaration ties the addon to a
399+
specific version of the OpenSSL library. It will not load on a version of
400+
Node.js that provides a different version of the OpenSSL library.
401+
402+
* `NODE_MODULE_ABI_LIBUV_VERSION` - this declaration ties the addon to a
403+
specific version of the libuv library. It will fail to load on a version of
404+
Node.js that provides a different version of libuv.
405+
406+
* `NODE_MODULE_ABI_ICU_VERSION` - this declaration ties the addon to a
407+
specific version of the ICU library. It will fail to load on a version of
408+
Node.js that provides a different version of the ICU library.
409+
410+
* `NODE_MODULE_ABI_CARES_VERSION` - this declaration ties the addon to a
411+
specific version of the c-ares library. It will fail to load on a version of
412+
Node.js that provides a different version of the c-ares library.
413+
410414
### Loading Addons using require()
411415
412416
The filename extension of the compiled Addon binary is `.node` (as opposed

0 commit comments

Comments
 (0)