@@ -251,74 +251,6 @@ down. If necessary, such hooks can be removed using
251
251
`RemoveEnvironmentCleanupHook()` before they are run, which has the same
252
252
signature.
253
253
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
-
322
254
### Building
323
255
324
256
Once the source code has been written, it must be compiled into the binary
@@ -391,8 +323,8 @@ try {
391
323
### Linking to Node.js' own dependencies
392
324
393
325
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
396
328
the appropriate ` #include <...> ` statements (e.g. ` #include <v8.h> ` ) and
397
329
` node-gyp ` will locate the appropriate headers automatically. However, there
398
330
are a few caveats to be aware of:
@@ -407,6 +339,78 @@ only the symbols exported by Node.js will be available.
407
339
source image. Using this option, the Addon will have access to the full set of
408
340
dependencies.
409
341
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
+
410
414
### Loading Addons using require()
411
415
412
416
The filename extension of the compiled Addon binary is `.node` (as opposed
0 commit comments