diff --git a/doc/guides/abi-stability.md b/doc/guides/abi-stability.md new file mode 100644 index 00000000000000..bbb4733c59d83f --- /dev/null +++ b/doc/guides/abi-stability.md @@ -0,0 +1,113 @@ +# ABI Stability + +## Introduction +An Application Binary Interface (ABI) is a way for programs to call functions +and use data structures from other compiled programs. It is the compiled version +of an Application Programming Interface (API). In other words, the headers files +describing the classes, functions, data structures, enumerations, and constants +which enable an application to perform a desired task correspond by way of +compilation to a set of addresses and expected parameter values and memory +structure sizes and layouts with which the provider of the ABI was compiled. + +The application using the ABI must be compiled such that the available +addresses, expected parameter values, and memory structure sizes and layouts +agree with those with which the ABI provider was compiled. This is usually +accomplished by compiling against the headers provided by the ABI provider. + +Since the provider of the ABI and the user of the ABI may be compiled at +different times with different versions of the compiler, a portion of the +responsibility for ensuring ABI compatibility lies with the compiler. Different +versions of the compiler, perhaps provided by different vendors, must all +produce the same ABI from a header file with a certain content, and must produce +code for the application using the ABI that accesses the API described in a +given header according to the conventions of the ABI resulting from the +description in the header. Modern compilers have a fairly good track record of +not breaking the ABI compatibility of the applications they compile. + +The remaining responsibility for ensuring ABI compatibility lies with the team +maintaining the header files which provide the API that results, upon +compilation, in the ABI that is to remain stable. Changes to the header files +can be made, but the nature of the changes has to be closely tracked to ensure +that, upon compilation, the ABI does not change in a way that will render +existing users of the ABI incompatible with the new version. + +## ABI Stability in Node.js +Node.js provides header files maintained by several independent teams. For +example, header files such as `node.h` and `node_buffer.h` are maintained by +the Node.js team. `v8.h` is maintained by the V8 team, which, although in close +co-operation with the Node.js team, is independent, and with its own schedule +and priorities. Thus, the Node.js team has only partial control over the +changes that are introduced in the headers the project provides. As a result, +the Node.js project has adopted [semantic versioning](https://semver.org/). +This ensures that the APIs provided by the project will result in a stable ABI +for all minor and patch versions of Node.js released within one major version. +In practice, this means that the Node.js project has committed itself to +ensuring that a Node.js native addon compiled against a given major version of +Node.js will load successfully when loaded by any Node.js minor or patch version +within the major version against which it was compiled. + +## N-API +Demand has arisen for equipping Node.js with an API that results in an ABI that +remains stable across multiple Node.js major versions. The motivation for +creating such an API is as follows: +* The JavaScript language has remained compatible with itself since its very +early days, whereas the ABI of the engine executing the JavaScript code changes +with every major version of Node.js. This means that applications consisting of +Node.js packages written entirely in JavaScript need not be recompiled, +reinstalled, or redeployed as a new major version of Node.js is dropped into +the production environment in which such applications run. In contrast, if an +application depends on a package that contains a native addon, the application +has to be recompiled, reinstalled, and redeployed whenever a new major version +of Node.js is introduced into the production environment. This disparity +between Node.js packages containing native addons and those that are written +entirely in JavaScript has added to the maintenance burden of production +systems which rely on native addons. + +* Other projects have started to produce JavaScript interfaces that are +essentially alternative implementations of Node.js. Since these projects are +usually built on a different JavaScript engine than V8, their native addons +necessarily take on a different structure and use a different API. Nevertheless, +using a single API for a native addon across different implementations of the +Node.js JavaScript API would allow these projects to take advantage of the +ecosystem of JavaScript packages that has accrued around Node.js. + +* Node.js may contain a different JavaScript engine in the future. This means +that, externally, all Node.js interfaces would remain the same, but the V8 +header file would be absent. Such a step would cause the disruption of the +Node.js ecosystem in general, and that of the native addons in particular, if +an API that is JavaScript engine agnostic is not first provided by Node.js and +adopted by native addons. + +To these ends Node.js has introduced N-API in version 8.6.0 and marked it as a +stable component of the project as of Node.js 8.12.0. The API is defined in the +headers [`node_api.h`][] and [`node_api_types.h`][], and provides a forward- +compatibility guarantee that crosses the Node.js major version boundary. The +guarantee can be stated as follows: + +**A given version *n* of N-API will be available in the major version of +Node.js in which it was published, and in all subsequent versions of Node.js, +including subsequent major versions.** + +A native addon author can take advantage of the N-API forward compatibility +guarantee by ensuring that the addon makes use only of APIs defined in +`node_api.h` and data structures and constants defined in `node_api_types.h`. +By doing so, the author facilitates adoption of their addon by indicating to +production users that the maintenance burden for their application will increase +no more by the addition of the native addon to their project than it would by +the addition of a package written purely in JavaScript. + +N-API is versioned because new APIs are added from time to time. Unlike +semantic versioning, N-API versioning is cumulative. That is, each version of +N-API conveys the same meaning as a minor version in the semver system, meaning +that all changes made to N-API will be backwards compatible. Additionally, new +N-APIs are added under an experimental flag to give the community an opportunity +to vet them in a production environment. Experimental status means that, +although care has been taken to ensure that the new API will not have to be +modified in an ABI-incompatible way in the future, it has not yet been +sufficiently proven in production to be correct and useful as designed and, as +such, may undergo ABI-incompatible changes before it is finally incorporated +into a forthcoming version of N-API. That is, an experimental N-API is not yet +covered by the forward compatibility guarantee. + +[`node_api.h`]: ../../src/node_api.h +[`node_api_types.h`]: ../..src/node_api_types.h