Commit d62e812
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -239,11 +239,32 @@ available to the module code. | |||
| 239 | 239 | ||
| 240 | 240 | ## Node-API version matrix | |
| 241 | 241 | ||
| 242 | - Node-API versions are additive and versioned independently from Node.js. | ||
| 243 | - Version 4 is an extension to version 3 in that it has all of the APIs | ||
| 244 | - from version 3 with some additions. This means that it is not necessary | ||
| 245 | - to recompile for new versions of Node.js which are | ||
| 246 | - listed as supporting a later version. | ||
| 242 | + Up until version 9, Node-API versions were additive and versioned | ||
| 243 | + independently from Node.js. This meant that any version was | ||
| 244 | + an extension to the previous version in that it had all of | ||
| 245 | + the APIs from the previous version with some additions. Each | ||
| 246 | + Node.js version only supported a single Node-API version. | ||
| 247 | + For example v18.15.0 supports only Node-API version 8. ABI stability was | ||
| 248 | + achieved because 8 was a strict superset of all previous versions. | ||
| 249 | + | ||
| 250 | + As of version 9, while Node-API versions continue to be versioned | ||
| 251 | + independently an add-on that ran with Node-API version 9 may need | ||
| 252 | + code updates to run with Node-API version 10. ABI stability | ||
| 253 | + is maintained, however, because Node.js versions that support | ||
| 254 | + Node-API versions higher than 8 will support all versions | ||
| 255 | + between 8 and the highest version they support and will default | ||
| 256 | + to providing the version 8 APIs unless an add-on opts into a | ||
| 257 | + higher Node-API version. This approach provides the flexibility | ||
| 258 | + of better optimizing existing Node-API functions while | ||
| 259 | + maintaining ABI stability. Existing add-ons can continue to run without | ||
| 260 | + recompilation using an earlier version of Node-API. If an add-on | ||
| 261 | + needs functionality from a newer Node-API version, changes to existing | ||
| 262 | + code and recompilation will be needed to use those new functions anyway. | ||
| 263 | + | ||
| 264 | + In versions of Node.js that support Node-API version 9 and later, defining | ||
| 265 | + `NAPI_VERSION=X` and using the existing add-on initialization macros | ||
| 266 | + will bake in the requested Node-API version that will be used at runtime | ||
| 267 | + into the add-on. If `NAPI_VERSION` is not set it will default to 8. | ||
| 247 | 268 | ||
| 248 | 269 | This table may not be up to date in older streams, the most up to date | |
| 249 | 270 | information is in the latest API documentation in: | |
0 commit comments