From 04fc7e63b99baf6e21639093718d5bc002bbe5ad Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Tue, 29 Mar 2022 17:54:40 -0400 Subject: [PATCH 01/26] doc: add maintaining info for shared libary option Refs: https://github.com/nodejs/node/pull/41850 I think it would be good to have some info/context for maintainers on the shared library option. Add that based on disussion in https://github.com/nodejs/node/pull/41850 Signed-off-by: Michael Dawson --- .../maintaining-shared-library-support.md | 117 ++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 doc/contributing/maintaining-shared-library-support.md diff --git a/doc/contributing/maintaining-shared-library-support.md b/doc/contributing/maintaining-shared-library-support.md new file mode 100644 index 00000000000000..9be947df7b951a --- /dev/null +++ b/doc/contributing/maintaining-shared-library-support.md @@ -0,0 +1,117 @@ +# Maintaining shared library support + +Node.js unofficially supports a build option where Node.js is built as +a shared library (node.dll/libnode.so). The shared library provides +an easy way to way to embed Node.js into other aplications and to +have multiple applications use a single copy of Node.js instead +of having to bundle in the full Node.js footprint into each application. + +This doc provides an outline of the approach and things to look +out for when maintaining the shared library support. + +Currently shared libary support has only be tested on: + +* Linux +* OSX +* Windows +* AIX + +## Building with shared libary option + +Node.js is built with the shared libary option by adding `--shared` +to the configure step before building on non-windows platforms +and adding `dll` when building on windows. + +Once built there are two key components: + +* executable - node +* library - libnode + +The node executable is a thin wrapper around libnode which is +generated so that we can run the standard Node.js test suite +against the shared libary. + +The executable and library will have extensions as appropriate +for the platform on which they are built. For +example, node.exe on windows and node on other platforms for +the executable. + +libnode may have additional naming components, as an example +in a build on OSX `libnode.105.dylib`. + +In cases where an application links against the shared +library it is up to the application developer to add options +so that the shared libary can be found by the application or +to set the LIBPATH (AIX), LD\_LIBRARY\_PATH (Linux/Unix), etc. +so that it is found at runtime. + +For the node.exe wrapper, it is built so that it can +find the shared library in one of the following: + +* the same directory as the node executable +* ../lib with the expectation that the executable is + installed in a `bin` directory at the same level + as a `lib` directory in which the shared library is + installed. This is where the default package that + is build with the shared library option will + place the executable and library. + +## Exports + +On windows, functions that may be linked from native +addons or additional Node.js executables need to have +NODE\_EXTERN otherwise they will not be exported by +the shared library. In the case of functions used +by additional Node.js executables (ex: `mksnapshot`) +a missing NODE\_EXTERN will cause the build to fail. + +## Native addons + +For regular Node.js builds, native addons rely on symbols +exported by the node executable. As a result any +pre-built binaries will expect symbols from the executable +instead of the shared libary itself. + +The current node executable wrapper addresses this by +ensuring that node.lib from node.exe does not get generated +and instead copy libnode.lib to node.lib. This means addons +compiled when referencing the correct node.lib file will correctly +depend on libnode.dll. The down side is that native addons compiled +with stock Node.js will still try to resolve symbols against +node.exe rather than libnode.dll. This would be a problem for +package that use node-addon-api pre-compiled binaries with the +goal of them working across different Node.js versions and +types (stadard versus shared libary). At this point the +main purpose for the node exectuable wrapper is for testing +so this is not considered a major issue. + +For applications that use the shared library and also +want to support pre-compiled addons it should be possible +to use an approach as follows on windows (and something similar +on other platforms): + +* the exports from libnode using dumpbin +* process the dumpbin output to generate a node.def file to be linked + into node.exe with the /DEF:node.def flag. + The export entries in node.def would all read my\_symbol=libnode.my\_symbol + so that node.exe will redirect all exported symbols back to libnode.dll. + +However, this has not been validated/tested. It would be +a good contribution for somebody to extend the node executable +wrapper to do this. + +## Testing + +There is currently no testing in the regular CI run for PRs. There +are some CI jobs that can be used to test the shared library support and +some are run as part of daily testing. These include: + +* [node-test-commit-linux-as-shared-lib](https://ci.nodejs.org/view/Node.js%20Daily/job/node-test-commit-linux-as-shared-lib/) +* +* [node-test-commit-aix-shared-lib](https://ci.nodejs.org/view/Node.js%20Daily/job/node-test-commit-aix-shared-lib/) + +TODO: add a Job for windows + +For code that modifies/affects shared libary support these CI jobs should +run and it should be validate that there are no regressions in +the test suite. From d8689796013d5811791290f45e1e5c07f9418a86 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Tue, 29 Mar 2022 18:03:04 -0400 Subject: [PATCH 02/26] fix typo --- doc/contributing/maintaining-shared-library-support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/contributing/maintaining-shared-library-support.md b/doc/contributing/maintaining-shared-library-support.md index 9be947df7b951a..cb0528a8514aff 100644 --- a/doc/contributing/maintaining-shared-library-support.md +++ b/doc/contributing/maintaining-shared-library-support.md @@ -113,5 +113,5 @@ some are run as part of daily testing. These include: TODO: add a Job for windows For code that modifies/affects shared libary support these CI jobs should -run and it should be validate that there are no regressions in +run and it should be validated that there are no regressions in the test suite. From 31a712dc796b055e92f5d58663c66e926cc4c6e9 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Wed, 30 Mar 2022 09:20:11 -0400 Subject: [PATCH 03/26] Update doc/contributing/maintaining-shared-library-support.md Co-authored-by: mscdex --- doc/contributing/maintaining-shared-library-support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/contributing/maintaining-shared-library-support.md b/doc/contributing/maintaining-shared-library-support.md index cb0528a8514aff..2916ab9e206f3f 100644 --- a/doc/contributing/maintaining-shared-library-support.md +++ b/doc/contributing/maintaining-shared-library-support.md @@ -2,7 +2,7 @@ Node.js unofficially supports a build option where Node.js is built as a shared library (node.dll/libnode.so). The shared library provides -an easy way to way to embed Node.js into other aplications and to +an easy way to way to embed Node.js into other applications and to have multiple applications use a single copy of Node.js instead of having to bundle in the full Node.js footprint into each application. From 00f1f2bce7c9a3d665125bbb88d61301710bd258 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Wed, 30 Mar 2022 09:20:17 -0400 Subject: [PATCH 04/26] Update doc/contributing/maintaining-shared-library-support.md Co-authored-by: mscdex --- doc/contributing/maintaining-shared-library-support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/contributing/maintaining-shared-library-support.md b/doc/contributing/maintaining-shared-library-support.md index 2916ab9e206f3f..af4f7ba6fa5694 100644 --- a/doc/contributing/maintaining-shared-library-support.md +++ b/doc/contributing/maintaining-shared-library-support.md @@ -16,7 +16,7 @@ Currently shared libary support has only be tested on: * Windows * AIX -## Building with shared libary option +## Building with shared library option Node.js is built with the shared libary option by adding `--shared` to the configure step before building on non-windows platforms From e3d1085382cb9739653178ba5e52d633ed72e0c0 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Wed, 30 Mar 2022 09:20:22 -0400 Subject: [PATCH 05/26] Update doc/contributing/maintaining-shared-library-support.md Co-authored-by: mscdex --- doc/contributing/maintaining-shared-library-support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/contributing/maintaining-shared-library-support.md b/doc/contributing/maintaining-shared-library-support.md index af4f7ba6fa5694..6c5d0cc8cd920d 100644 --- a/doc/contributing/maintaining-shared-library-support.md +++ b/doc/contributing/maintaining-shared-library-support.md @@ -18,7 +18,7 @@ Currently shared libary support has only be tested on: ## Building with shared library option -Node.js is built with the shared libary option by adding `--shared` +Node.js is built with the shared library option by adding `--shared` to the configure step before building on non-windows platforms and adding `dll` when building on windows. From e06601856172508684c52e439317a21e3ef266f8 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Wed, 30 Mar 2022 09:20:28 -0400 Subject: [PATCH 06/26] Update doc/contributing/maintaining-shared-library-support.md Co-authored-by: mscdex --- doc/contributing/maintaining-shared-library-support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/contributing/maintaining-shared-library-support.md b/doc/contributing/maintaining-shared-library-support.md index 6c5d0cc8cd920d..02191b5a8a6f21 100644 --- a/doc/contributing/maintaining-shared-library-support.md +++ b/doc/contributing/maintaining-shared-library-support.md @@ -29,7 +29,7 @@ Once built there are two key components: The node executable is a thin wrapper around libnode which is generated so that we can run the standard Node.js test suite -against the shared libary. +against the shared library. The executable and library will have extensions as appropriate for the platform on which they are built. For From 2dea68bb16f2ac72fa53fc2221903722f8cbb913 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Wed, 30 Mar 2022 09:20:33 -0400 Subject: [PATCH 07/26] Update doc/contributing/maintaining-shared-library-support.md Co-authored-by: mscdex --- doc/contributing/maintaining-shared-library-support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/contributing/maintaining-shared-library-support.md b/doc/contributing/maintaining-shared-library-support.md index 02191b5a8a6f21..1be033cc9267fa 100644 --- a/doc/contributing/maintaining-shared-library-support.md +++ b/doc/contributing/maintaining-shared-library-support.md @@ -70,7 +70,7 @@ a missing NODE\_EXTERN will cause the build to fail. For regular Node.js builds, native addons rely on symbols exported by the node executable. As a result any pre-built binaries will expect symbols from the executable -instead of the shared libary itself. +instead of the shared library itself. The current node executable wrapper addresses this by ensuring that node.lib from node.exe does not get generated From b81291cba117ba29b88f69e3a9b46d1d360d6e8d Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Wed, 30 Mar 2022 09:20:39 -0400 Subject: [PATCH 08/26] Update doc/contributing/maintaining-shared-library-support.md Co-authored-by: mscdex --- doc/contributing/maintaining-shared-library-support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/contributing/maintaining-shared-library-support.md b/doc/contributing/maintaining-shared-library-support.md index 1be033cc9267fa..2cf09cb9049ef4 100644 --- a/doc/contributing/maintaining-shared-library-support.md +++ b/doc/contributing/maintaining-shared-library-support.md @@ -82,7 +82,7 @@ node.exe rather than libnode.dll. This would be a problem for package that use node-addon-api pre-compiled binaries with the goal of them working across different Node.js versions and types (stadard versus shared libary). At this point the -main purpose for the node exectuable wrapper is for testing +main purpose for the node executable wrapper is for testing so this is not considered a major issue. For applications that use the shared library and also From 8f5935e7af88c0ee88b081dcf5d5c2a2670a1916 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Wed, 30 Mar 2022 09:20:44 -0400 Subject: [PATCH 09/26] Update doc/contributing/maintaining-shared-library-support.md Co-authored-by: mscdex --- doc/contributing/maintaining-shared-library-support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/contributing/maintaining-shared-library-support.md b/doc/contributing/maintaining-shared-library-support.md index 2cf09cb9049ef4..96d9c1b130cefa 100644 --- a/doc/contributing/maintaining-shared-library-support.md +++ b/doc/contributing/maintaining-shared-library-support.md @@ -112,6 +112,6 @@ some are run as part of daily testing. These include: TODO: add a Job for windows -For code that modifies/affects shared libary support these CI jobs should +For code that modifies/affects shared library support these CI jobs should run and it should be validated that there are no regressions in the test suite. From a5b3e46824f91e301ffc37591a81181b968930de Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Wed, 30 Mar 2022 09:21:42 -0400 Subject: [PATCH 10/26] Update doc/contributing/maintaining-shared-library-support.md Co-authored-by: mscdex --- doc/contributing/maintaining-shared-library-support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/contributing/maintaining-shared-library-support.md b/doc/contributing/maintaining-shared-library-support.md index 96d9c1b130cefa..1f8122ec59866b 100644 --- a/doc/contributing/maintaining-shared-library-support.md +++ b/doc/contributing/maintaining-shared-library-support.md @@ -81,7 +81,7 @@ with stock Node.js will still try to resolve symbols against node.exe rather than libnode.dll. This would be a problem for package that use node-addon-api pre-compiled binaries with the goal of them working across different Node.js versions and -types (stadard versus shared libary). At this point the +types (standard versus shared library). At this point the main purpose for the node executable wrapper is for testing so this is not considered a major issue. From c7213558259e101f14154569d2eed24db85f0db5 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Wed, 30 Mar 2022 09:21:52 -0400 Subject: [PATCH 11/26] Update doc/contributing/maintaining-shared-library-support.md Co-authored-by: mscdex --- doc/contributing/maintaining-shared-library-support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/contributing/maintaining-shared-library-support.md b/doc/contributing/maintaining-shared-library-support.md index 1f8122ec59866b..3278990787b565 100644 --- a/doc/contributing/maintaining-shared-library-support.md +++ b/doc/contributing/maintaining-shared-library-support.md @@ -41,7 +41,7 @@ in a build on OSX `libnode.105.dylib`. In cases where an application links against the shared library it is up to the application developer to add options -so that the shared libary can be found by the application or +so that the shared library can be found by the application or to set the LIBPATH (AIX), LD\_LIBRARY\_PATH (Linux/Unix), etc. so that it is found at runtime. From b3c5a0affe276239fca0a7ef0aad31a68da378ab Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Wed, 30 Mar 2022 09:21:58 -0400 Subject: [PATCH 12/26] Update doc/contributing/maintaining-shared-library-support.md Co-authored-by: mscdex --- doc/contributing/maintaining-shared-library-support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/contributing/maintaining-shared-library-support.md b/doc/contributing/maintaining-shared-library-support.md index 3278990787b565..d2020570257eca 100644 --- a/doc/contributing/maintaining-shared-library-support.md +++ b/doc/contributing/maintaining-shared-library-support.md @@ -9,7 +9,7 @@ of having to bundle in the full Node.js footprint into each application. This doc provides an outline of the approach and things to look out for when maintaining the shared library support. -Currently shared libary support has only be tested on: +Currently shared library support has only be tested on: * Linux * OSX From 4ce8d4a85a9cad76c54869d5203f5f2d5beea74e Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Wed, 30 Mar 2022 09:23:36 -0400 Subject: [PATCH 13/26] squash: address comments --- doc/contributing/maintaining-shared-library-support.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/contributing/maintaining-shared-library-support.md b/doc/contributing/maintaining-shared-library-support.md index d2020570257eca..6d8d9a1d02dded 100644 --- a/doc/contributing/maintaining-shared-library-support.md +++ b/doc/contributing/maintaining-shared-library-support.md @@ -2,9 +2,11 @@ Node.js unofficially supports a build option where Node.js is built as a shared library (node.dll/libnode.so). The shared library provides -an easy way to way to embed Node.js into other applications and to +an easy way to embed Node.js into other applications and to have multiple applications use a single copy of Node.js instead of having to bundle in the full Node.js footprint into each application. +For workloads that require multiple node instances this can result +in a significant footprint savings. This doc provides an outline of the approach and things to look out for when maintaining the shared library support. From 6b136cdae5cbf85e294a41ffb57dcbb288145635 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Thu, 31 Mar 2022 17:33:30 -0400 Subject: [PATCH 14/26] Update doc/contributing/maintaining-shared-library-support.md Co-authored-by: Richard Lau --- doc/contributing/maintaining-shared-library-support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/contributing/maintaining-shared-library-support.md b/doc/contributing/maintaining-shared-library-support.md index 6d8d9a1d02dded..102d71a42f39a0 100644 --- a/doc/contributing/maintaining-shared-library-support.md +++ b/doc/contributing/maintaining-shared-library-support.md @@ -14,7 +14,7 @@ out for when maintaining the shared library support. Currently shared library support has only be tested on: * Linux -* OSX +* macOS * Windows * AIX From 487a5c2fdebaf532c89f066e3d59312e3f989dbb Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Thu, 31 Mar 2022 17:34:35 -0400 Subject: [PATCH 15/26] squash: address comments --- doc/contributing/maintaining-shared-library-support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/contributing/maintaining-shared-library-support.md b/doc/contributing/maintaining-shared-library-support.md index 102d71a42f39a0..18d7afa254f11e 100644 --- a/doc/contributing/maintaining-shared-library-support.md +++ b/doc/contributing/maintaining-shared-library-support.md @@ -39,7 +39,7 @@ example, node.exe on windows and node on other platforms for the executable. libnode may have additional naming components, as an example -in a build on OSX `libnode.105.dylib`. +in a build on macOS `libnode.105.dylib`. In cases where an application links against the shared library it is up to the application developer to add options From 3f0212bf654628b8d1f0e4d74094139d977e94d1 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Thu, 7 Apr 2022 16:52:03 -0400 Subject: [PATCH 16/26] Update doc/contributing/maintaining-shared-library-support.md Co-authored-by: Tierney Cyren --- doc/contributing/maintaining-shared-library-support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/contributing/maintaining-shared-library-support.md b/doc/contributing/maintaining-shared-library-support.md index 18d7afa254f11e..7e3f346a6d73d8 100644 --- a/doc/contributing/maintaining-shared-library-support.md +++ b/doc/contributing/maintaining-shared-library-support.md @@ -8,7 +8,7 @@ of having to bundle in the full Node.js footprint into each application. For workloads that require multiple node instances this can result in a significant footprint savings. -This doc provides an outline of the approach and things to look +This document provides an outline of the approach and things to look out for when maintaining the shared library support. Currently shared library support has only be tested on: From 5ca69c292e4676e37bb6cbd6fbf670a7724cc3ed Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Thu, 7 Apr 2022 16:52:09 -0400 Subject: [PATCH 17/26] Update doc/contributing/maintaining-shared-library-support.md Co-authored-by: Tierney Cyren --- doc/contributing/maintaining-shared-library-support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/contributing/maintaining-shared-library-support.md b/doc/contributing/maintaining-shared-library-support.md index 7e3f346a6d73d8..cda674d9d2be90 100644 --- a/doc/contributing/maintaining-shared-library-support.md +++ b/doc/contributing/maintaining-shared-library-support.md @@ -11,7 +11,7 @@ in a significant footprint savings. This document provides an outline of the approach and things to look out for when maintaining the shared library support. -Currently shared library support has only be tested on: +Currently, shared library support has only been tested on: * Linux * macOS From 1646f22791c5b21e5d33554e05575b7b55c606f0 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Thu, 7 Apr 2022 17:01:07 -0400 Subject: [PATCH 18/26] squash: address comments --- .../maintaining-shared-library-support.md | 20 ++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/doc/contributing/maintaining-shared-library-support.md b/doc/contributing/maintaining-shared-library-support.md index cda674d9d2be90..62e8d404561981 100644 --- a/doc/contributing/maintaining-shared-library-support.md +++ b/doc/contributing/maintaining-shared-library-support.md @@ -1,12 +1,13 @@ # Maintaining shared library support Node.js unofficially supports a build option where Node.js is built as -a shared library (node.dll/libnode.so). The shared library provides -an easy way to embed Node.js into other applications and to -have multiple applications use a single copy of Node.js instead -of having to bundle in the full Node.js footprint into each application. -For workloads that require multiple node instances this can result -in a significant footprint savings. +a shared library. The shared library is node.dll on windows, and +libnode on other platforms. +The shared library provides a way to embed Node.js into other +applications and to have multiple applications use a single copy of +Node.js instead of having to bundle in the full Node.js footprint +into each application. For workloads that require multiple Node.js +instances this can result in a significant footprint savings. This document provides an outline of the approach and things to look out for when maintaining the shared library support. @@ -20,9 +21,10 @@ Currently, shared library support has only been tested on: ## Building with shared library option -Node.js is built with the shared library option by adding `--shared` -to the configure step before building on non-windows platforms -and adding `dll` when building on windows. +On non-Windows platoforms, Node.js is built with the shared library +option by adding `--shared` to the configure step. On Windows +platofrms Node.js is built with the shared library option by +adding `dll` to the vcbuild command line. Once built there are two key components: From 2136f11ae3426e9b01a1b30bbec09d7cea3d9a72 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Thu, 7 Apr 2022 17:09:29 -0400 Subject: [PATCH 19/26] squash: satisfy the linter --- doc/contributing/maintaining-shared-library-support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/contributing/maintaining-shared-library-support.md b/doc/contributing/maintaining-shared-library-support.md index 62e8d404561981..c8336e70d23118 100644 --- a/doc/contributing/maintaining-shared-library-support.md +++ b/doc/contributing/maintaining-shared-library-support.md @@ -1,7 +1,7 @@ # Maintaining shared library support Node.js unofficially supports a build option where Node.js is built as -a shared library. The shared library is node.dll on windows, and +a shared library. The shared library is node.dll on windows, and libnode on other platforms. The shared library provides a way to embed Node.js into other applications and to have multiple applications use a single copy of From b165ebd496ea72791608650f92bcb86fbd805ac5 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Thu, 21 Apr 2022 18:14:39 -0400 Subject: [PATCH 20/26] Update doc/contributing/maintaining-shared-library-support.md --- doc/contributing/maintaining-shared-library-support.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/contributing/maintaining-shared-library-support.md b/doc/contributing/maintaining-shared-library-support.md index c8336e70d23118..cf8f5ab7407995 100644 --- a/doc/contributing/maintaining-shared-library-support.md +++ b/doc/contributing/maintaining-shared-library-support.md @@ -1,8 +1,8 @@ # Maintaining shared library support Node.js unofficially supports a build option where Node.js is built as -a shared library. The shared library is node.dll on windows, and -libnode on other platforms. +a shared library. The shared library is called libnode with additional postfixes +as appropriate for the platform (for example libnode.dll on windows). The shared library provides a way to embed Node.js into other applications and to have multiple applications use a single copy of Node.js instead of having to bundle in the full Node.js footprint From 86b1571fe11e622767685b1ade7674fd7b60586b Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Thu, 21 Apr 2022 18:20:25 -0400 Subject: [PATCH 21/26] squash: address comments --- .../maintaining-shared-library-support.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/doc/contributing/maintaining-shared-library-support.md b/doc/contributing/maintaining-shared-library-support.md index cf8f5ab7407995..78a67ead9fb628 100644 --- a/doc/contributing/maintaining-shared-library-support.md +++ b/doc/contributing/maintaining-shared-library-support.md @@ -64,10 +64,14 @@ find the shared library in one of the following: On windows, functions that may be linked from native addons or additional Node.js executables need to have -NODE\_EXTERN otherwise they will not be exported by -the shared library. In the case of functions used -by additional Node.js executables (ex: `mksnapshot`) -a missing NODE\_EXTERN will cause the build to fail. +NODE_EXTERN_PRIVATE or NODE_EXTERN otherwise they will +not be exported by the shared library. In the case of +functions used by additional Node.js executables +(ex: `mksnapshot`) a missing NODE_EXTERN or +NODE_EXTERN_PRIVATE will cause the build to fail. +NODE_EXTERN_PRIVATE should be used in these cases +unless the intent is to add the function to the +public embedder API. ## Native addons From 1912c7c5d81abaef9c9ba79a8518890bde962075 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Thu, 21 Apr 2022 18:32:50 -0400 Subject: [PATCH 22/26] squash: address comments --- .../maintaining-shared-library-support.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/doc/contributing/maintaining-shared-library-support.md b/doc/contributing/maintaining-shared-library-support.md index 78a67ead9fb628..fbc5d02e12719c 100644 --- a/doc/contributing/maintaining-shared-library-support.md +++ b/doc/contributing/maintaining-shared-library-support.md @@ -49,8 +49,9 @@ so that the shared library can be found by the application or to set the LIBPATH (AIX), LD\_LIBRARY\_PATH (Linux/Unix), etc. so that it is found at runtime. -For the node.exe wrapper, it is built so that it can -find the shared library in one of the following: +For the node wrapper, on linux and macOS it is built +so that it can find the shared library in one of +the following: * the same directory as the node executable * ../lib with the expectation that the executable is @@ -59,6 +60,15 @@ find the shared library in one of the following: installed. This is where the default package that is build with the shared library option will place the executable and library. + +For the node wrapper on windows it is built expecting +that both the executable and shared library will +be in the same directory as it common practice on +that platform. + +For the node wrapper on AIX, it is built with +the path to the shared library hardcoded as that +is the only option. ## Exports From fa7895098e8b8acc3bfe23a2467b171623b4ebbf Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Tue, 10 May 2022 09:51:08 -0400 Subject: [PATCH 23/26] Update doc/contributing/maintaining-shared-library-support.md --- doc/contributing/maintaining-shared-library-support.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/contributing/maintaining-shared-library-support.md b/doc/contributing/maintaining-shared-library-support.md index fbc5d02e12719c..1d0d6c414d3279 100644 --- a/doc/contributing/maintaining-shared-library-support.md +++ b/doc/contributing/maintaining-shared-library-support.md @@ -41,7 +41,9 @@ example, node.exe on windows and node on other platforms for the executable. libnode may have additional naming components, as an example -in a build on macOS `libnode.105.dylib`. +in a build on macOS `libnode.105.dylib`. For non-windows platforms +the additional naming components include the `NODE_MODULE_VERSION` and +the appropriate postfix used for shared libraries on the platform. In cases where an application links against the shared library it is up to the application developer to add options From 7703b6eea9a4676ae2f9d79b4d17d1ef4e5145c2 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Tue, 10 May 2022 09:59:50 -0400 Subject: [PATCH 24/26] squash: update to reflect current approach --- .../maintaining-shared-library-support.md | 38 +++++-------------- 1 file changed, 9 insertions(+), 29 deletions(-) diff --git a/doc/contributing/maintaining-shared-library-support.md b/doc/contributing/maintaining-shared-library-support.md index 1d0d6c414d3279..40ac0087e00350 100644 --- a/doc/contributing/maintaining-shared-library-support.md +++ b/doc/contributing/maintaining-shared-library-support.md @@ -87,38 +87,18 @@ public embedder API. ## Native addons -For regular Node.js builds, native addons rely on symbols +For regular Node.js builds, running native addons relies on symbols exported by the node executable. As a result any -pre-built binaries will expect symbols from the executable +pre-built binaries expect symbols to be exported from the executable instead of the shared library itself. -The current node executable wrapper addresses this by -ensuring that node.lib from node.exe does not get generated -and instead copy libnode.lib to node.lib. This means addons -compiled when referencing the correct node.lib file will correctly -depend on libnode.dll. The down side is that native addons compiled -with stock Node.js will still try to resolve symbols against -node.exe rather than libnode.dll. This would be a problem for -package that use node-addon-api pre-compiled binaries with the -goal of them working across different Node.js versions and -types (standard versus shared library). At this point the -main purpose for the node executable wrapper is for testing -so this is not considered a major issue. - -For applications that use the shared library and also -want to support pre-compiled addons it should be possible -to use an approach as follows on windows (and something similar -on other platforms): - -* the exports from libnode using dumpbin -* process the dumpbin output to generate a node.def file to be linked - into node.exe with the /DEF:node.def flag. - The export entries in node.def would all read my\_symbol=libnode.my\_symbol - so that node.exe will redirect all exported symbols back to libnode.dll. - -However, this has not been validated/tested. It would be -a good contribution for somebody to extend the node executable -wrapper to do this. +The node executable and shared library are built and linked +so that the required symbols are exported from the node +executable. This requires some extra work on some platforms +and the process to build the node executable is a good example +of how this can be achieved. Applications that use the shared +library and want to support native addons should employ +a similar technique. ## Testing From 0a42b27a1b637938e04f1062ea62b7264fb27fc5 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Tue, 10 May 2022 10:25:24 -0400 Subject: [PATCH 25/26] squash: address linter issues --- doc/contributing/maintaining-shared-library-support.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/contributing/maintaining-shared-library-support.md b/doc/contributing/maintaining-shared-library-support.md index 40ac0087e00350..a1f7d2e77def03 100644 --- a/doc/contributing/maintaining-shared-library-support.md +++ b/doc/contributing/maintaining-shared-library-support.md @@ -2,7 +2,7 @@ Node.js unofficially supports a build option where Node.js is built as a shared library. The shared library is called libnode with additional postfixes -as appropriate for the platform (for example libnode.dll on windows). +as appropriate for the platform (for example libnode.dll on windows). The shared library provides a way to embed Node.js into other applications and to have multiple applications use a single copy of Node.js instead of having to bundle in the full Node.js footprint @@ -62,7 +62,7 @@ the following: installed. This is where the default package that is build with the shared library option will place the executable and library. - + For the node wrapper on windows it is built expecting that both the executable and shared library will be in the same directory as it common practice on @@ -79,7 +79,7 @@ addons or additional Node.js executables need to have NODE_EXTERN_PRIVATE or NODE_EXTERN otherwise they will not be exported by the shared library. In the case of functions used by additional Node.js executables -(ex: `mksnapshot`) a missing NODE_EXTERN or +(ex: `mksnapshot`) a missing NODE_EXTERN or NODE_EXTERN_PRIVATE will cause the build to fail. NODE_EXTERN_PRIVATE should be used in these cases unless the intent is to add the function to the From a89bafa660ec2da2f92187b05fb9943c9ab1773a Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Tue, 10 May 2022 10:56:10 -0400 Subject: [PATCH 26/26] squash: stand on head to make linter happy Signed-off-by: Michael Dawson --- doc/contributing/maintaining-shared-library-support.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/contributing/maintaining-shared-library-support.md b/doc/contributing/maintaining-shared-library-support.md index a1f7d2e77def03..45d0bc279673f0 100644 --- a/doc/contributing/maintaining-shared-library-support.md +++ b/doc/contributing/maintaining-shared-library-support.md @@ -76,12 +76,12 @@ is the only option. On windows, functions that may be linked from native addons or additional Node.js executables need to have -NODE_EXTERN_PRIVATE or NODE_EXTERN otherwise they will +NODE\_EXTERN\_PRIVATE or NODE\_EXTERN otherwise they will not be exported by the shared library. In the case of functions used by additional Node.js executables -(ex: `mksnapshot`) a missing NODE_EXTERN or -NODE_EXTERN_PRIVATE will cause the build to fail. -NODE_EXTERN_PRIVATE should be used in these cases +(ex: `mksnapshot`) a missing NODE\_EXTERN or +NODE\_EXTERN\_PRIVATE will cause the build to fail. +NODE\_EXTERN\_PRIVATE should be used in these cases unless the intent is to add the function to the public embedder API.