1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: add guide about abi stability

Browse Source 
Re: https://github.com/nodejs/abi-stable-node/issues/332#issuecomment-418379903
PR-URL: https://github.com/nodejs/node/pull/23229
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
This commit is contained in:
Gabriel Schulhof 2018-10-02 11:25:47 -04:00
parent e273abc01b
commit 65366addb2
1 changed files with 113 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

113
doc/guides/abi-stability.md Normal file
View File

@ -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