Skip to content

doc: add note about ABI compatibility #22237

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
MylesBorins wants to merge 1 commit into from
Closed

doc: add note about ABI compatibility #22237

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions BUILDING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -528,3 +528,14 @@ To make `./myModule.js` available via `require('myModule')` and
```console
> .\vcbuild link-module './myModule.js' link-module './myModule2.js'
```

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

@ofrobots ofrobots Aug 10, 2018 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should flesh out a bit more what is involved in a custom NODE_MODULE_VERSION. The problem is that we don't necessarily have "room" in the incrementally increasing versions to anticipate needs apriori.

My proposal is:

  • Reserve 8 most significant bits in the NODE_MODULE_VERSION for 'distribution'.
  • Official builds would use 0. Electron, and other distributors could use a different value if the binary they are shipping is not ABI compatible.

@mhdawson mhdawson Aug 10, 2018

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

reserving a number of bits makes sense to me.

@MylesBorins MylesBorins Aug 10, 2018

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1. Does someone want to push a commit that adds this specific documentation?

@MylesBorins MylesBorins Oct 2, 2018

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ofrobots would you be able to supply explicit copy for this? Otherwise I'd like to land this in an iteration of this PR

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.