From f84e39b0c6f6aa52a02755b9e7bd5a40cb2144ce Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Thu, 12 Oct 2023 21:06:35 +0000 Subject: [PATCH 01/15] doc: add information about Node-API versions >=9 Signed-off-by: Michael Dawson --- doc/api/n-api.md | 29 ++++++++++++++++++++++++----- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index af9e9db5cae80f..f8cf144098069a 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -239,11 +239,30 @@ available to the module code. ## Node-API version matrix -Node-API versions are additive and versioned independently from Node.js. -Version 4 is an extension to version 3 in that it has all of the APIs -from version 3 with some additions. This means that it is not necessary -to recompile for new versions of Node.js which are -listed as supporting a later version. +Up until version 9, Node-API versions are additive and versioned +independently from Node.js. For example, version 4 is an extension to version +3 in that it has all of the APIs from version 3 with some additions. Each +Node.js version only supported a single Node-API version. For example +For example v18.15.0 supports only Node-API version 8. ABI stability was +achieved because 8 was a strict superset of all previous versions. + +As of version 9, while Node-API versions continue to be versioned independently +an add-on that ran with Node-API version 9 may need updates to run with +Node-API version 10. ABI stability is maintained, however, because Node.js +versions that support Node-API versions higher than 8 will support all +versions between 8 and the highest version they support and will default +to providing the version 8 APIs unless an addon opts into a +higher Node-API version. This approach provides the flexibility +of better optimizing existing Node-API functions while maintaing ABI stability. +Existing addons can continue to run without recompilation using an earlier +version of Node-API. If an addon needs functionality from a newer Node-API +version, changes to existing code and recompilation will be needed to use +those new functions anyway. + +In versions of Node.js that support Node-API version 9 and later, defining +NAPI\_VERSION=X and using the existing addon initialization macros will bake +in the requested Node-API version that will be used at runtime into the addon. +If NAPI\_VERSION is not set it will default to 8. This table may not be up to date in older streams, the most up to date information is in the latest API documentation in: From 87155ef3da271fc909accc2e80716eb3d832245c Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Fri, 13 Oct 2023 15:48:55 -0400 Subject: [PATCH 02/15] Update n-api.md --- doc/api/n-api.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index f8cf144098069a..9d59d8871f4446 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -242,7 +242,7 @@ available to the module code. Up until version 9, Node-API versions are additive and versioned independently from Node.js. For example, version 4 is an extension to version 3 in that it has all of the APIs from version 3 with some additions. Each -Node.js version only supported a single Node-API version. For example +Node.js version only supported a single Node-API version. For example v18.15.0 supports only Node-API version 8. ABI stability was achieved because 8 was a strict superset of all previous versions. @@ -260,9 +260,9 @@ version, changes to existing code and recompilation will be needed to use those new functions anyway. In versions of Node.js that support Node-API version 9 and later, defining -NAPI\_VERSION=X and using the existing addon initialization macros will bake +NAPI_VERSION=X and using the existing addon initialization macros will bake in the requested Node-API version that will be used at runtime into the addon. -If NAPI\_VERSION is not set it will default to 8. +If NAPI_VERSION is not set it will default to 8. This table may not be up to date in older streams, the most up to date information is in the latest API documentation in: From aaad700fb15dc1f9c10e8d1b1ee3fa9ae971d2f0 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Fri, 13 Oct 2023 20:14:51 +0000 Subject: [PATCH 03/15] squash: make linter happy Signed-off-by: Michael Dawson --- doc/api/n-api.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 9d59d8871f4446..3206fd11ec3961 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -242,7 +242,7 @@ available to the module code. Up until version 9, Node-API versions are additive and versioned independently from Node.js. For example, version 4 is an extension to version 3 in that it has all of the APIs from version 3 with some additions. Each -Node.js version only supported a single Node-API version. +Node.js version only supported a single Node-API version. For example v18.15.0 supports only Node-API version 8. ABI stability was achieved because 8 was a strict superset of all previous versions. @@ -260,9 +260,9 @@ version, changes to existing code and recompilation will be needed to use those new functions anyway. In versions of Node.js that support Node-API version 9 and later, defining -NAPI_VERSION=X and using the existing addon initialization macros will bake +`NAPI_VERSION=X` and using the existing addon initialization macros will bake in the requested Node-API version that will be used at runtime into the addon. -If NAPI_VERSION is not set it will default to 8. +If `NAPI_VERSION` is not set it will default to 8. This table may not be up to date in older streams, the most up to date information is in the latest API documentation in: From 626e1a2498cdebee7c298634feae128d5ad440a4 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Tue, 17 Oct 2023 14:00:17 -0400 Subject: [PATCH 04/15] Update doc/api/n-api.md Co-authored-by: Alex Strizhak --- doc/api/n-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 3206fd11ec3961..51a23ef8c9e2f3 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -253,7 +253,7 @@ versions that support Node-API versions higher than 8 will support all versions between 8 and the highest version they support and will default to providing the version 8 APIs unless an addon opts into a higher Node-API version. This approach provides the flexibility -of better optimizing existing Node-API functions while maintaing ABI stability. +of better optimizing existing Node-API functions while maintaining ABI stability. Existing addons can continue to run without recompilation using an earlier version of Node-API. If an addon needs functionality from a newer Node-API version, changes to existing code and recompilation will be needed to use From fd3279c0ee639bcb0058dd77f8d905c1e9471665 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Tue, 17 Oct 2023 15:16:57 -0400 Subject: [PATCH 05/15] Update n-api.md --- doc/api/n-api.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 51a23ef8c9e2f3..767ea0abf36df4 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -253,11 +253,11 @@ versions that support Node-API versions higher than 8 will support all versions between 8 and the highest version they support and will default to providing the version 8 APIs unless an addon opts into a higher Node-API version. This approach provides the flexibility -of better optimizing existing Node-API functions while maintaining ABI stability. -Existing addons can continue to run without recompilation using an earlier -version of Node-API. If an addon needs functionality from a newer Node-API -version, changes to existing code and recompilation will be needed to use -those new functions anyway. +of better optimizing existing Node-API functions while +maintaining ABI stability. Existing addons can continue to run without +recompilation using an earlier version of Node-API. If an addon +needs functionality from a newer Node-API version, changes to existing +code and recompilation will be needed to use those new functions anyway. In versions of Node.js that support Node-API version 9 and later, defining `NAPI_VERSION=X` and using the existing addon initialization macros will bake From cfcc153328ee68256c35a5fe0eda017835cbbe4c Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Fri, 20 Oct 2023 09:34:22 -0400 Subject: [PATCH 06/15] Update doc/api/n-api.md Co-authored-by: Gabriel Schulhof --- doc/api/n-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 767ea0abf36df4..6d17aa6bc9f021 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -239,7 +239,7 @@ available to the module code. ## Node-API version matrix -Up until version 9, Node-API versions are additive and versioned +Up until version 9, Node-API versions were additive and versioned independently from Node.js. For example, version 4 is an extension to version 3 in that it has all of the APIs from version 3 with some additions. Each Node.js version only supported a single Node-API version. From 91db07920d539b2c4c1870b3cc6a7767882006b1 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Fri, 20 Oct 2023 09:34:32 -0400 Subject: [PATCH 07/15] Update doc/api/n-api.md Co-authored-by: Gabriel Schulhof --- doc/api/n-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 6d17aa6bc9f021..0983304424dcd6 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -240,8 +240,8 @@ available to the module code. ## Node-API version matrix Up until version 9, Node-API versions were additive and versioned -independently from Node.js. For example, version 4 is an extension to version -3 in that it has all of the APIs from version 3 with some additions. Each +independently from Node.js. This meant that any version was an extension to the previous version +in that it had all of the APIs from the previous version with some additions. Each Node.js version only supported a single Node-API version. For example v18.15.0 supports only Node-API version 8. ABI stability was achieved because 8 was a strict superset of all previous versions. From 59552c9fc1e2070de8492102dc87d7ec803f1a1e Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Fri, 20 Oct 2023 09:34:38 -0400 Subject: [PATCH 08/15] Update doc/api/n-api.md Co-authored-by: Gabriel Schulhof --- doc/api/n-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 0983304424dcd6..e50950fb9b7280 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -251,7 +251,7 @@ an add-on that ran with Node-API version 9 may need updates to run with Node-API version 10. ABI stability is maintained, however, because Node.js versions that support Node-API versions higher than 8 will support all versions between 8 and the highest version they support and will default -to providing the version 8 APIs unless an addon opts into a +to providing the version 8 APIs unless an add-on opts into a higher Node-API version. This approach provides the flexibility of better optimizing existing Node-API functions while maintaining ABI stability. Existing addons can continue to run without From bcaaf77d3619ef8fab6bc9f96519790eb7eaba42 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Fri, 20 Oct 2023 09:34:44 -0400 Subject: [PATCH 09/15] Update doc/api/n-api.md Co-authored-by: Gabriel Schulhof --- doc/api/n-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index e50950fb9b7280..1d6b013d90d623 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -247,7 +247,7 @@ For example v18.15.0 supports only Node-API version 8. ABI stability was achieved because 8 was a strict superset of all previous versions. As of version 9, while Node-API versions continue to be versioned independently -an add-on that ran with Node-API version 9 may need updates to run with +an add-on that ran with Node-API version 9 may need code updates to run with Node-API version 10. ABI stability is maintained, however, because Node.js versions that support Node-API versions higher than 8 will support all versions between 8 and the highest version they support and will default From ef41a2fab83686559f07af362b920b99170f9bf4 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Fri, 20 Oct 2023 09:34:50 -0400 Subject: [PATCH 10/15] Update doc/api/n-api.md Co-authored-by: Gabriel Schulhof --- doc/api/n-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 1d6b013d90d623..0eef01c4c23c79 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -254,7 +254,7 @@ versions between 8 and the highest version they support and will default to providing the version 8 APIs unless an add-on opts into a higher Node-API version. This approach provides the flexibility of better optimizing existing Node-API functions while -maintaining ABI stability. Existing addons can continue to run without +maintaining ABI stability. Existing add-ons can continue to run without recompilation using an earlier version of Node-API. If an addon needs functionality from a newer Node-API version, changes to existing code and recompilation will be needed to use those new functions anyway. From ec30e4f4d78560a28b924ee82c7e0af7de1e07aa Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Fri, 20 Oct 2023 09:34:55 -0400 Subject: [PATCH 11/15] Update doc/api/n-api.md Co-authored-by: Gabriel Schulhof --- doc/api/n-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 0eef01c4c23c79..df1d74a9e44ec2 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -255,7 +255,7 @@ to providing the version 8 APIs unless an add-on opts into a higher Node-API version. This approach provides the flexibility of better optimizing existing Node-API functions while maintaining ABI stability. Existing add-ons can continue to run without -recompilation using an earlier version of Node-API. If an addon +recompilation using an earlier version of Node-API. If an add-on needs functionality from a newer Node-API version, changes to existing code and recompilation will be needed to use those new functions anyway. From ef5fc045a907aec9a81a0b617ef192bc61df4468 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Fri, 20 Oct 2023 09:35:01 -0400 Subject: [PATCH 12/15] Update doc/api/n-api.md Co-authored-by: Gabriel Schulhof --- doc/api/n-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index df1d74a9e44ec2..8d8d667de35cb7 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -260,7 +260,7 @@ needs functionality from a newer Node-API version, changes to existing code and recompilation will be needed to use those new functions anyway. In versions of Node.js that support Node-API version 9 and later, defining -`NAPI_VERSION=X` and using the existing addon initialization macros will bake +`NAPI_VERSION=X` and using the existing add-on initialization macros will bake in the requested Node-API version that will be used at runtime into the addon. If `NAPI_VERSION` is not set it will default to 8. From 0231b66bd07857beff8354166aeda3e1dc0e7feb Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Fri, 20 Oct 2023 09:35:06 -0400 Subject: [PATCH 13/15] Update doc/api/n-api.md Co-authored-by: Gabriel Schulhof --- doc/api/n-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 8d8d667de35cb7..d665a567a428aa 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -261,7 +261,7 @@ code and recompilation will be needed to use those new functions anyway. In versions of Node.js that support Node-API version 9 and later, defining `NAPI_VERSION=X` and using the existing add-on initialization macros will bake -in the requested Node-API version that will be used at runtime into the addon. +in the requested Node-API version that will be used at runtime into the add-on. If `NAPI_VERSION` is not set it will default to 8. This table may not be up to date in older streams, the most up to date From 7fa9d66d0f0c2f0d6989ba3455c99dc56257fad7 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Mon, 23 Oct 2023 17:20:41 -0400 Subject: [PATCH 14/15] Update n-api.md --- doc/api/n-api.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index d665a567a428aa..9279c05b84831e 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -240,17 +240,19 @@ available to the module code. ## Node-API version matrix Up until version 9, Node-API versions were additive and versioned -independently from Node.js. This meant that any version was an extension to the previous version -in that it had all of the APIs from the previous version with some additions. Each +independently from Node.js. This meant that any version was +an extension to the previous version in that it had all of +the APIs from the previous version with some additions. Each Node.js version only supported a single Node-API version. For example v18.15.0 supports only Node-API version 8. ABI stability was achieved because 8 was a strict superset of all previous versions. -As of version 9, while Node-API versions continue to be versioned independently -an add-on that ran with Node-API version 9 may need code updates to run with -Node-API version 10. ABI stability is maintained, however, because Node.js -versions that support Node-API versions higher than 8 will support all -versions between 8 and the highest version they support and will default +As of version 9, while Node-API versions continue to be versioned +independently an add-on that ran with Node-API version 9 may need +code updates to run with Node-API version 10. ABI stability +is maintained, however, because Node.js versions that support +Node-API versions higher than 8 will support all versions +between 8 and the highest version they support and will default to providing the version 8 APIs unless an add-on opts into a higher Node-API version. This approach provides the flexibility of better optimizing existing Node-API functions while From e7fda3cdc1cd215e7e56aea26f1a08cd1155dc53 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Mon, 23 Oct 2023 17:22:12 -0400 Subject: [PATCH 15/15] Update n-api.md --- doc/api/n-api.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 9279c05b84831e..5fc05761d6d55a 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -262,9 +262,9 @@ needs functionality from a newer Node-API version, changes to existing code and recompilation will be needed to use those new functions anyway. In versions of Node.js that support Node-API version 9 and later, defining -`NAPI_VERSION=X` and using the existing add-on initialization macros will bake -in the requested Node-API version that will be used at runtime into the add-on. -If `NAPI_VERSION` is not set it will default to 8. +`NAPI_VERSION=X` and using the existing add-on initialization macros +will bake in the requested Node-API version that will be used at runtime +into the add-on. If `NAPI_VERSION` is not set it will default to 8. This table may not be up to date in older streams, the most up to date information is in the latest API documentation in: