Skip to content

Commit

Permalink
doc: add ABI version registry
Browse files Browse the repository at this point in the history 
PR-URL: #24114
Refs: https://nodejs.org/en/download/releases/
Refs: https://github.com/lgeiger/node-abi/blob/master/index.js
Refs: nodejs/TSC#621
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Ujjwal Sharma <usharma1998@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: Ali Ijaz Sheikh <ofrobots@google.com>
  • Loading branch information
@rvagg
rvagg committed Apr 17, 2019
1 parent cdba9f2 commit c61c722
Show file tree
Hide file tree
Showing 4 changed files with 84 additions and 45 deletions.
19 changes: 11 additions & 8 deletions BUILDING.md
View file
Expand Up @@ -581,11 +581,14 @@ To make `./myModule.js` available via `require('myModule')` and

## Note for downstream distributors of Node.js

The Node.js ecosystem is reliant on ABI compatibility within a major
release. To maintain ABI compatibility it is required that production
builds of Node.js will be built against the same version of dependencies as the
project vendors. If Node.js is to be built against a different version of a
dependency please create a custom `NODE_MODULE_VERSION` to ensure ecosystem
compatibility. Please consult with the TSC by opening an issue at
https://github.com/nodejs/tsc/issues if you decide to create a custom
`NODE_MODULE_VERSION` so we can avoid duplication in the ecosystem.
The Node.js ecosystem is reliant on ABI compatibility within a major release.
To maintain ABI compatibility it is required that distributed builds of Node.js
be built against the same version of dependencies, or similar versions that do
not break their ABI compatibility, as those released by Node.js for any given
`NODE_MODULE_VERSION` (located in `src/node_version.h`).

When Node.js is built (with an intention to distribute) with an ABI
incompatible with the official Node.js builds (e.g. using a ABI incompatible
version of a dependency), please reserve and use a custom `NODE_MODULE_VERSION`
by opening a pull request against the registry available at
<https://github.com/nodejs/node/blob/master/doc/abi_version_registry.json>.
58 changes: 58 additions & 0 deletions doc/abi_version_registry.json
View file
@@ -0,0 +1,58 @@
{
"NODE_MODULE_VERSION": [
{ "modules": 72, "runtime": "node", "variant": "v8_7.4", "versions": "12.0.0-pre" },
{ "modules": 71, "runtime": "node", "variant": "v8_7.3", "versions": "12.0.0-pre" },
{ "modules": 70, "runtime": "electron", "variant": "electron", "versions": "5" },
{ "modules": 69, "runtime": "electron", "variant": "electron", "versions": "^4.0.5" },
{ "modules": 68, "runtime": "node", "variant": "v8_7.1", "versions": "12.0.0-pre" },
{ "modules": 67, "runtime": "node", "variant": "node", "versions": "11" },
{ "modules": 66, "runtime": "node", "variant": "v8_6.9", "versions": "11.0.0-pre" },
{ "modules": 65, "runtime": "node", "variant": "v8_6.8", "versions": "11.0.0-pre" },
{ "modules": 65, "runtime": "node", "variant": "debian-openssl_1.1.1", "versions": "10" },
{ "modules": 64, "runtime": "node", "variant": "node", "versions": "10" },
{ "modules": 64, "runtime": "electron", "variant": "electron", "versions": ">=3 <4.0.5" },
{ "modules": 63, "runtime": "node", "variant": "v8_6.6", "versions": "10.0.0-pre" },
{ "modules": 62, "runtime": "node", "variant": "v8_6.5", "versions": "10.0.0-pre" },
{ "modules": 61, "runtime": "node", "variant": "v8_6.4", "versions": "10.0.0-pre" },
{ "modules": 60, "runtime": "node", "variant": "v8_6.3", "versions": "10.0.0-pre" },
{ "modules": 59, "runtime": "node", "variant": "node", "versions": "9" },
{ "modules": 59, "runtime": "nw.js", "variant": "nw.js", "versions": "~0.26.5" },
{ "modules": 58, "runtime": "node", "variant": "v8_6.1", "versions": "9.0.0-pre" },
{ "modules": 58, "runtime": "node", "variant": "debian-openssl_1.1.1", "versions": "8" },
{ "modules": 57, "runtime": "node", "variant": "node", "versions": "8" },
{ "modules": 57, "runtime": "electron", "variant": "electron", "versions": ">=1.8 <3" },
{ "modules": 57, "runtime": "nw.js", "variant": "nw.js", "versions": ">=0.23 <0.26.5" },
{ "modules": 56, "runtime": "node", "variant": "v8_5.9", "versions": "8.0.0-pre" },
{ "modules": 55, "runtime": "node", "variant": "v8_5.8", "versions": "8.0.0-pre" },
{ "modules": 54, "runtime": "node", "variant": "v8_5.7", "versions": "8.0.0-pre" },
{ "modules": 54, "runtime": "electron", "variant": "electron", "versions": "1.7" },
{ "modules": 53, "runtime": "node", "variant": "v8_5.6", "versions": "8.0.0-pre" },
{ "modules": 53, "runtime": "electron", "variant": "electron", "versions": "1.6" },
{ "modules": 52, "runtime": "node", "variant": "v8_5.5", "versions": "8.0.0-pre" },
{ "modules": 51, "runtime": "node", "variant": "node", "versions": "7" },
{ "modules": 51, "runtime": "electron", "variant": "electron", "versions": "1.5" },
{ "modules": 51, "runtime": "nw.js", "variant": "nw.js", "versions": ">=0.18.3 <0.24" },
{ "modules": 50, "runtime": "electron", "variant": "electron", "versions": "1.4" },
{ "modules": 49, "runtime": "electron", "variant": "electron", "versions": "1.3" },
{ "modules": 48, "runtime": "node", "variant": "node", "versions": "6" },
{ "modules": 48, "runtime": "electron", "variant": "electron", "versions": ">1.1 <1.3" },
{ "modules": 48, "runtime": "nw.js", "variant": "nw.js", "versions": "6" },
{ "modules": 47, "runtime": "node", "variant": "node", "versions": "5" },
{ "modules": 47, "runtime": "electron", "variant": "electron", "versions": "0.36" },
{ "modules": 47, "runtime": "nw.js", "variant": "nw.js", "versions": "0.13" },
{ "modules": 46, "runtime": "node", "variant": "node", "versions": "4" },
{ "modules": 46, "runtime": "electron", "variant": "electron", "versions": ">=0.33 <0.36" },
{ "modules": 45, "runtime": "node", "variant": "io.js", "versions": "3" },
{ "modules": 45, "runtime": "electron", "variant": "electron", "versions": ">=0.31 <0.33" },
{ "modules": 44, "runtime": "node", "variant": "io.js", "versions": "2" },
{ "modules": 44, "runtime": "electron", "variant": "electron", "versions": "0.30" },
{ "modules": 43, "runtime": "node", "variant": "io.js", "versions": ">=1.1 <2" },
{ "modules": 42, "runtime": "node", "variant": "io.js", "versions": "1.0" },
{ "modules": 14, "runtime": "node", "variant": "node", "versions": ">=0.11.11 <0.13" },
{ "modules": 13, "runtime": "node", "variant": "node", "versions": ">=0.11.8 <0.11.11" },
{ "modules": 12, "runtime": "node", "variant": "node", "versions": ">=0.11.0 <0.11.8" },
{ "modules": 11, "runtime": "node", "variant": "node", "versions": ">=0.9.9 <0.11" },
{ "modules": 10, "runtime": "node", "variant": "node", "versions": ">=0.9.1 <0.9.9" },
{ "modules": 1, "runtime": "node", "variant": "node", "versions": ">=0.2.0 <0.9.8" }
]
}
6 changes: 6 additions & 0 deletions doc/releases.md
View file
Expand Up @@ -235,6 +235,12 @@ and also if there are non-trivial API changes. The rules are not yet strictly
defined, so if in doubt, please confer with someone that will have a more
informed perspective, such as a member of the NAN team.

A registry of currently used `NODE_MODULE_VERSION` values is maintained at
<https://github.com/nodejs/node/blob/master/doc/abi_version_registry.json>.
When bumping `NODE_MODULE_VERSION`, you should choose a new value not listed
in the registry. Also include a change to the registry in your commit to
reflect the newly used value.

It is current TSC policy to bump major version when ABI changes. If you
see a need to bump `NODE_MODULE_VERSION` then you should consult the TSC.
Commits may need to be reverted or a major version bump may need to happen.
Expand Down
46 changes: 9 additions & 37 deletions src/node_version.h
View file
Expand Up @@ -75,47 +75,19 @@
* Node.js will refuse to load modules that weren't compiled against its own
* module ABI number, exposed as the process.versions.modules property.
*
* When this version number is changed, node.js will refuse
* to load older modules. This should be done whenever
* an API is broken in the C++ side, including in v8 or
* other dependencies.
* Node.js will refuse to load modules with a non-matching ABI version. The
* version number here should be changed whenever an ABI-incompatible API change
* is made in the C++ side, including in V8 or other dependencies.
*
* Node.js will not change the module version during a Major release line
* We will at times update the version of V8 shipped in the release line
* We will, at times update the version of V8 shipped in the release line
* if it can be made ABI compatible with the previous version.
*
* Module version by Node.js version:
* Node.js v0.10.x: 11
* Node.js v0.12.x: 14
* Node.js v4.x: 46
* Node.js v5.x: 47
* Node.js v6.x: 48
* Node.js v7.x: 51
* Node.js v8.x: 57
*
* Module version by V8 ABI version:
* V8 5.4: 51
* V8 5.5: 52
* V8 5.6: 53
* V8 5.7: 54
* V8 5.8: 55
* V8 5.9: 56
* V8 6.0: 57
* V8 6.1: 58
* V8 6.2: 59
* V8 6.3: 60
* V8 6.4: 61
* V8 6.5: 62
* V8 6.6: 63
* V8 6.7: 64
* V8 6.8: 65
* V8 6.9: 66
* V8 7.0: 67
* V8 7.1: 68
* V8 7.3: 71
* V8 7.4: 72
*
* More information can be found at https://nodejs.org/en/download/releases/
* The registry of used NODE_MODULE_VERSION numbers is located at
* https://github.com/nodejs/node/blob/master/doc/abi_version_registry.json
* Extenders, embedders and other consumers of Node.js that require ABI
* version matching should open a pull request to reserve a number in this
* registry.
*/
#define NODE_MODULE_VERSION 72

Expand Down

0 comments on commit c61c722

Please sign in to comment.