From a448c8b779f1d3b34e2ab9511d88c8b4702f10b8 Mon Sep 17 00:00:00 2001 From: Gabriel Schulhof Date: Fri, 24 Aug 2018 13:11:50 -0400 Subject: [PATCH] doc: add blurb about implications of ABI stability 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 Reviewed-By: Michael Dawson --- doc/api/addons.md | 4 ++++ doc/api/n-api.md | 30 ++++++++++++++++++++++++++++++ 2 files changed, 34 insertions(+) diff --git a/doc/api/addons.md b/doc/api/addons.md index 9ea0a6b6446ce4..bba4820ca9c084 100644 --- a/doc/api/addons.md +++ b/doc/api/addons.md @@ -367,6 +367,10 @@ set of APIs that are used by the native code. Instead of using the V8 or [Native Abstractions for Node.js][] APIs, the functions available in the N-API are used. +Creating and maintaining an addon that benefits from the ABI stability +provided by N-API carries with it certain +[implementation considerations](n-api.html#n_api_implications_of_abi_stability). + To use N-API in the above "Hello world" example, replace the content of `hello.cc` with the following. All other instructions remain the same. diff --git a/doc/api/n-api.md b/doc/api/n-api.md index a21d1f7ad70bff..4f27d8c55223d6 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -42,6 +42,36 @@ for the N-API C based functions exported by Node.js. These wrappers are not part of N-API, nor will they be maintained as part of Node.js. One such example is: [node-addon-api](https://github.com/nodejs/node-addon-api). +## Implications of ABI Stability + +Although N-API provides an ABI stability guarantee, other parts of Node.js do +not, and any external libraries used from the addon may not. In particular, +none of the following APIs provide an ABI stability guarantee across major +versions: +* the Node.js C++ APIs available via any of + ```C++ + #include + #include + #include + #include + ``` +* the libuv APIs which are also included with Node.js and available via + ```C++ + #include + ``` +* the V8 API available via + ```C++ + #include + ``` + +Thus, for an addon to remain ABI-compatible across Node.js major versions, it +must make use exclusively of N-API by restricting itself to using +```C +#include +``` +and by checking, for all external libraries that it uses, that the external +library makes ABI stability guarantees similar to N-API. + ## Usage In order to use the N-API functions, include the file