name : maintaining-shared-library-support.md # Maintaining shared library support 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). 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. Currently, shared library support has only been tested on: * Linux * macOS * Windows * AIX ## Building with shared library option On non-Windows platforms, Node.js is built with the shared library option by adding `--shared` to the configure step. On Windows platforms Node.js is built with the shared library option by adding `dll` to the vcbuild command line. 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 library. 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 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 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 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 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. 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 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 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 For regular Node.js builds, running native addons relies on symbols exported by the node executable. As a result any pre-built binaries expect symbols to be exported from the executable instead of the shared library itself. 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 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/) * <https://ci.nodejs.org/view/All/job/node-test-commit-osx-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 library support these CI jobs should run and it should be validated that there are no regressions in the test suite.