From f1cb8ab4bf4e5bbc577cd89a50d2690acbd0baa1 Mon Sep 17 00:00:00 2001 From: Gabriel Schulhof Date: Sat, 6 Oct 2018 21:41:55 -0400 Subject: [PATCH] doc: remove ABI guide Move it to the nodejs.org repo. PR-URL: https://github.com/nodejs/node/pull/23303 Reviewed-By: Rich Trott Reviewed-By: Vse Mozhet Byt --- doc/guides/abi-stability.md | 113 ------------------------------------ 1 file changed, 113 deletions(-) delete mode 100644 doc/guides/abi-stability.md diff --git a/doc/guides/abi-stability.md b/doc/guides/abi-stability.md deleted file mode 100644 index bbb4733c59d83f..00000000000000 --- a/doc/guides/abi-stability.md +++ /dev/null @@ -1,113 +0,0 @@ -# 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