Android: dlopen conformance addons as dynamic .node backed by a shared libnapi.so

Replaces the interim static-link-into-host approach with the dynamic .node model used by
nodejs/node-api-cts (add_node_api_cts_addon), so the Android suite and a future node-api-cts
migration share one addon model.

- Core/Node-API: build napi as a SHARED library (libnapi.so) on Android. It exports all 106 napi_*
  (default visibility -- no global -fvisibility=hidden), and the host plus every addon depend on the
  one libnapi.so via a real DT_NEEDED, so there is a single napi instance. Static elsewhere.
- The conformance addons are again standalone SHARED lib<name>.so (packaged into nativeLibraryDir),
  now linking napi (DT_NEEDED libnapi.so) instead of -Wl,--unresolved-symbols=ignore-all.
- node_lite_android resolves entry points via dlopen(soname)+dlsym again; the addon's napi_* bind
  from libnapi.so at load. Reverts the static-link infra (entry_point.h JSR_NODE_API_STATIC_LINK
  branch, node_api.h overridable registrar macros, the host's per-addon OBJECT libraries).

Verified on device: lib2_function_arguments.so has DT_NEEDED [libnapi.so], its napi_* are imports,
libnapi.so exports the 106 napi_*, and all 4 v5 js-native-api tests pass in-process. macOS unchanged
(12/12; desktop keeps static napi + dlopen'd MODULE .node).

Author: matthargett

Core/Node-API/CMakeLists.txt

@@ -155,7 +155,17 @@ if(NAPI_BUILD_ABI)
     message(STATUS "Selected ${NAPI_JAVASCRIPT_ENGINE}")
 endif()
 
-add_library(napi ${SOURCES})
+# On Android the Node-API conformance addons are dlopen'd as standalone SHARED .node modules (matching
+# nodejs/node-api-cts's add_node_api_cts_addon model). For an addon's napi_* imports to bind at load,
+# napi must be a shared library that both the host and the addons depend on via a real DT_NEEDED
+# (libnapi.so) -- bionic will not surface a statically-linked host's napi to a dlopen'd module. There
+# is a single napi instance (one libnapi.so) shared by the host and every addon. Elsewhere (the
+# child-process desktop runner) napi stays a static library.
+if(ANDROID)
+    add_library(napi SHARED ${SOURCES})
+else()
+    add_library(napi ${SOURCES})
+endif()
 
 target_include_directories(napi ${INCLUDE_DIRECTORIES})
 target_link_libraries(napi ${LINK_LIBRARIES})

Tests/NodeApi/CMakeLists.txt

@@ -120,13 +120,6 @@ if(JSR_NODE_API_BUILD_NATIVE_TESTS)
 endif()
 
 function(add_node_api_module MODULE_TARGET)
-    if(ANDROID)
-        # On Android the conformance addons are statically linked into the in-process test host
-        # (Tests/UnitTests/Android/app/src/main/cpp/CMakeLists.txt) -- there is no standalone .node to
-        # build or dlopen, so this desktop helper builds nothing here.
-        return()
-    endif()
-
     cmake_parse_arguments(PARSE_ARGV 0 ARG "" "" "SOURCES;DEFINES")
 
     get_filename_component(FOLDER_NAME ${CMAKE_CURRENT_SOURCE_DIR} NAME)
@@ -135,8 +128,14 @@ function(add_node_api_module MODULE_TARGET)
         set(MODULE_TARGET "${FOLDER_NAME}_${MODULE_TARGET}")
     endif()
 
-    # The addon is a MODULE (dlopen-only) .node, loaded by the node_lite child-process runner.
-    add_library(${MODULE_TARGET} MODULE)
+    # On Android the addon is a SHARED lib<name>.so so AGP packages it into the APK's lib/<abi>/ (the
+    # app's nativeLibraryDir, the only place a native library may be dlopen'd from on API 29+).
+    # Elsewhere it is a MODULE (dlopen-only) .node loaded by the node_lite child-process runner.
+    if(ANDROID)
+        add_library(${MODULE_TARGET} SHARED)
+    else()
+        add_library(${MODULE_TARGET} MODULE)
+    endif()
     target_sources(${MODULE_TARGET} PRIVATE ${ARG_SOURCES})
     target_include_directories(${MODULE_TARGET}
         PRIVATE
@@ -161,36 +160,50 @@ function(add_node_api_module MODULE_TARGET)
             PRIVATE
                 "-undefined" "dynamic_lookup"
         )
+    elseif(ANDROID)
+        # Link the shared napi (libnapi.so) so the addon's napi_* imports resolve at dlopen via a real
+        # DT_NEEDED -- the same libnapi.so the host depends on, so there is a single napi instance.
+        target_link_libraries(${MODULE_TARGET} PRIVATE napi)
     endif()
 
-    set(MODULE_OUTPUT_DIR
-        ${CMAKE_CURRENT_BINARY_DIR}/build/$<IF:$<CONFIG:Debug>,Debug,Release>)
-    set_target_properties(${MODULE_TARGET}
-        PROPERTIES
-            PREFIX ""
-            SUFFIX ".node"
-            ARCHIVE_OUTPUT_DIRECTORY ${MODULE_OUTPUT_DIR}
-            LIBRARY_OUTPUT_DIRECTORY ${MODULE_OUTPUT_DIR}
-            RUNTIME_OUTPUT_DIRECTORY ${MODULE_OUTPUT_DIR}
-    )
+    if(ANDROID)
+        set_target_properties(${MODULE_TARGET}
+            PROPERTIES
+                PREFIX "lib"
+                SUFFIX ".so"
+        )
+    else()
+        set(MODULE_OUTPUT_DIR
+            ${CMAKE_CURRENT_BINARY_DIR}/build/$<IF:$<CONFIG:Debug>,Debug,Release>)
+        set_target_properties(${MODULE_TARGET}
+            PROPERTIES
+                PREFIX ""
+                SUFFIX ".node"
+                ARCHIVE_OUTPUT_DIRECTORY ${MODULE_OUTPUT_DIR}
+                LIBRARY_OUTPUT_DIRECTORY ${MODULE_OUTPUT_DIR}
+                RUNTIME_OUTPUT_DIRECTORY ${MODULE_OUTPUT_DIR}
+        )
+    endif()
 
     add_dependencies(NodeApiModules ${MODULE_TARGET})
 
-    # Stage the built .node next to the node_lite / NodeApiTests runners so they can dlopen it
-    # relative to the copied test files.
-    add_custom_command(TARGET ${MODULE_TARGET} POST_BUILD
-        COMMAND ${CMAKE_COMMAND} -E make_directory
-            $<TARGET_FILE_DIR:node_lite>/test/js-native-api/${FOLDER_NAME}/build
-        COMMAND ${CMAKE_COMMAND} -E copy_directory
-            ${CMAKE_CURRENT_BINARY_DIR}/build
-            $<TARGET_FILE_DIR:node_lite>/test/js-native-api/${FOLDER_NAME}/build
-        COMMAND ${CMAKE_COMMAND} -E make_directory
-            $<TARGET_FILE_DIR:NodeApiTests>/test/js-native-api/${FOLDER_NAME}/build
-        COMMAND ${CMAKE_COMMAND} -E copy_directory
-            ${CMAKE_CURRENT_BINARY_DIR}/build
-            $<TARGET_FILE_DIR:NodeApiTests>/test/js-native-api/${FOLDER_NAME}/build
-        COMMENT "Copying Node-API module ${MODULE_TARGET} outputs"
-    )
+    if(NOT ANDROID)
+        # Stage the built .node next to the node_lite / NodeApiTests runners so they can dlopen it
+        # relative to the copied test files.
+        add_custom_command(TARGET ${MODULE_TARGET} POST_BUILD
+            COMMAND ${CMAKE_COMMAND} -E make_directory
+                $<TARGET_FILE_DIR:node_lite>/test/js-native-api/${FOLDER_NAME}/build
+            COMMAND ${CMAKE_COMMAND} -E copy_directory
+                ${CMAKE_CURRENT_BINARY_DIR}/build
+                $<TARGET_FILE_DIR:node_lite>/test/js-native-api/${FOLDER_NAME}/build
+            COMMAND ${CMAKE_COMMAND} -E make_directory
+                $<TARGET_FILE_DIR:NodeApiTests>/test/js-native-api/${FOLDER_NAME}/build
+            COMMAND ${CMAKE_COMMAND} -E copy_directory
+                ${CMAKE_CURRENT_BINARY_DIR}/build
+                $<TARGET_FILE_DIR:NodeApiTests>/test/js-native-api/${FOLDER_NAME}/build
+            COMMENT "Copying Node-API module ${MODULE_TARGET} outputs"
+        )
+    endif()
 
     if(APPLE)
         # The copy_directory above runs as an Xcode "Run Script" phase, which executes BEFORE

Tests/NodeApi/include/node_api.h

@@ -35,16 +35,8 @@ typedef struct napi_module_s {
     void* reserved[4];
 } napi_module;
 
-// These may be overridden by the build (e.g. -DNODE_API_MODULE_REGISTER_FUNCTION=...) so that several
-// addons can be *statically* linked into a single host binary -- each with a uniquely suffixed entry
-// point -- without symbol clashes. The defaults are the canonical names a dynamic loader (dlsym)
-// looks up in a standalone .node.
-#ifndef NODE_API_MODULE_GET_API_VERSION_FUNCTION
 #define NODE_API_MODULE_GET_API_VERSION_FUNCTION node_api_module_get_api_version_v1
-#endif
-#ifndef NODE_API_MODULE_REGISTER_FUNCTION
 #define NODE_API_MODULE_REGISTER_FUNCTION napi_register_module_v1
-#endif
 
 #define NAPI_MODULE_INIT()                                                     \
     NODE_API_EXTERN_C_START                                                    \

Tests/NodeApi/node_lite.cpp

@@ -406,10 +406,10 @@ fs::path NodeLiteRuntime::ResolveModulePath(
       return node_module_path;
     }
 #if defined(__ANDROID__)
-    // On Android the conformance addons are statically linked into the host rather than present as
-    // .node files on disk, so the existence check above fails. Resolve to the .node path anyway so
-    // LoadNativeModule runs; node_lite_android resolves the entry points from the in-process static
-    // registry, keyed by this path's stem (the module name).
+    // On Android the addon ships as lib<name>.so in the app's nativeLibraryDir rather than as a .node
+    // file on disk, so the existence check above fails. Resolve to the .node path anyway so
+    // LoadNativeModule runs; node_lite_android dlopens it by soname (lib<stem>.so), resolving its
+    // napi_* imports from the shared libnapi.so.
     return node_module_path;
 #endif
     // See if the module was prefixed with the parent folder to disambiguate C++

Tests/NodeApi/node_lite_android.cpp

@@ -1,67 +1,27 @@
 #include "node_lite.h"
 
-#include <cstdint>
-#include <string>
-#include <vector>
+#include <dlfcn.h>
 
 namespace node_api_tests {
-namespace {
 
-// Registry of the Node-API conformance addons that are statically linked into this host binary. It is
-// populated at load time by the per-addon constructors emitted in entry_point.h under
-// JSR_NODE_API_STATIC_LINK, each registering its uniquely-suffixed entry points keyed by module name.
-// A function-local static (constructed on first registration) avoids any static-initialization-order
-// dependency between those constructors and this translation unit.
-struct StaticAddon {
-    std::string name;
-    int32_t (*get_api_version)(void);
-    napi_value (*register_module)(napi_env, napi_value);
-};
-
-std::vector<StaticAddon>& StaticAddonRegistry() {
-    static std::vector<StaticAddon> registry;
-    return registry;
-}
-
-} // namespace
-} // namespace node_api_tests
-
-// Called once per statically-linked addon from its load-time constructor (see entry_point.h). Declared
-// extern "C" to match the declaration the C addon translation units compile against.
-extern "C" void jsr_register_static_addon(
-    const char* name,
-    int32_t (*get_api_version)(void),
-    napi_value (*register_module)(napi_env, napi_value)) {
-    node_api_tests::StaticAddonRegistry().push_back(
-        {name, get_api_version, register_module});
-}
-
-namespace node_api_tests {
-
-// On Android the conformance addons are statically linked into the host rather than dlopen'd: dynamic
-// .node loading is never shipped to the Play / Quest stores, and bionic won't resolve a dlopen'd
-// addon's napi_* against the System.loadLibrary-loaded host anyway (see NAPI_VERSION_ROADMAP.md, and
-// task #9 for the shared-lib alternative). So resolve the requested entry point from the in-process
-// static registry, keyed by the module's file-stem name, instead of dlopen+dlsym.
 /*static*/ void* NodeLitePlatform::LoadFunction(
     napi_env /*env*/,
     const std::filesystem::path& lib_path,
     const std::string& function_name) noexcept
 {
-    const std::string module_name = lib_path.stem().string();
-    for (const StaticAddon& addon : StaticAddonRegistry()) {
-        if (addon.name != module_name) {
-            continue;
-        }
-        if (function_name == "napi_register_module_v1") {
-            return reinterpret_cast<void*>(addon.register_module);
-        }
-        if (function_name == "node_api_module_get_api_version_v1") {
-            return reinterpret_cast<void*>(addon.get_api_version);
-        }
+    // On Android the conformance addons are packaged as lib<name>.so in the app's nativeLibraryDir --
+    // the only location a native library may be dlopen'd from on API 29+. The resolved lib_path points
+    // at a (non-existent) <name>.node under the copied test tree, so load by soname and let the dynamic
+    // linker resolve it from nativeLibraryDir. The addon's napi_* imports resolve from libnapi.so -- a
+    // DT_NEEDED of both the addon and the host -- so RTLD_NOW binds them at load time.
+    std::string soname = "lib" + lib_path.stem().string() + ".so";
+    void* handle = dlopen(soname.c_str(), RTLD_NOW | RTLD_LOCAL);
+    if (handle == nullptr)
+    {
         return nullptr;
     }
-    return nullptr;
+
+    return dlsym(handle, function_name.c_str());
 }
 
 } // namespace node_api_tests

Tests/NodeApi/test/js-native-api/entry_point.h

@@ -1,38 +1,12 @@
-#ifndef JS_NATIVE_API_ENTRY_POINT_H_
-#define JS_NATIVE_API_ENTRY_POINT_H_
-
-#include <node_api.h>
-
-#if defined(JSR_NODE_API_STATIC_LINK)
-// Static-link mode (the Android in-process conformance runner): every addon is linked into one host
-// binary, so Init must have internal linkage to avoid one-definition clashes across addons. The
-// registrar/version functions are uniquely suffixed per-module by the build (NODE_API_MODULE_*_FUNCTION
-// in node_api.h). A later non-static definition of Init in the addon inherits this internal linkage.
-static napi_value Init(napi_env env, napi_value exports);
-#else
-EXTERN_C_START
-napi_value Init(napi_env env, napi_value exports);
-EXTERN_C_END
-#endif
-
-NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)
-
-#if defined(JSR_NODE_API_STATIC_LINK)
-// Self-register this addon's uniquely-named entry points with the host at load time, keyed by module
-// name, so the in-process loader (node_lite_android LoadFunction) can find them by name -- the static
-// equivalent of dlopen+dlsym. jsr_register_static_addon is implemented by the host.
-EXTERN_C_START
-void jsr_register_static_addon(
-    const char* name,
-    int32_t (*get_api_version)(void),
-    napi_value (*register_module)(napi_env, napi_value));
-EXTERN_C_END
-
-static void __attribute__((constructor)) jsr_register_static_addon_ctor(void) {
-  jsr_register_static_addon(NODE_GYP_MODULE_NAME,
-                            NODE_API_MODULE_GET_API_VERSION_FUNCTION,
-                            NODE_API_MODULE_REGISTER_FUNCTION);
-}
-#endif
-
-#endif  // JS_NATIVE_API_ENTRY_POINT_H_
+#ifndef JS_NATIVE_API_ENTRY_POINT_H_
+#define JS_NATIVE_API_ENTRY_POINT_H_
+
+#include <node_api.h>
+
+EXTERN_C_START
+napi_value Init(napi_env env, napi_value exports);
+EXTERN_C_END
+
+NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)
+
+#endif  // JS_NATIVE_API_ENTRY_POINT_H_

Tests/UnitTests/Android/app/src/main/cpp/CMakeLists.txt

@@ -73,33 +73,9 @@ target_link_libraries(UnitTestsJNI
 if(ANDROID)
     target_link_libraries(UnitTestsJNI PRIVATE dl)
 endif()
-set(JSR_NODE_API_NATIVE_TESTS 2_function_arguments 3_callbacks 4_object_factory 5_function_factory)
-string(JOIN "," JSR_NODE_API_NATIVE_TESTS_CSV ${JSR_NODE_API_NATIVE_TESTS})
 target_compile_definitions(UnitTestsJNI
-    PRIVATE NODE_API_AVAILABLE_NATIVE_TESTS="${JSR_NODE_API_NATIVE_TESTS_CSV}")
+    PRIVATE NODE_API_AVAILABLE_NATIVE_TESTS="2_function_arguments,3_callbacks,4_object_factory,5_function_factory")
 
-# --- Statically linked Node-API conformance addons (Android in-process runner) ------------------
-# Dynamic .node loading is never shipped to the Play / Quest stores, and bionic will not resolve a
-# dlopen'd addon's napi_* imports against the System.loadLibrary-loaded host anyway (see
-# NAPI_VERSION_ROADMAP.md; task #9 tracks the shared-lib alternative). So compile each addon into the
-# host with a uniquely suffixed entry point -- avoiding one-definition clashes between addons -- and
-# let node_lite resolve them from the in-process static registry (node_lite_android) instead of dlsym.
-# entry_point.h emits, per addon, a load-time constructor that self-registers those entry points.
-foreach(_mod ${JSR_NODE_API_NATIVE_TESTS})
-    add_library(jsr_addon_${_mod} OBJECT
-        ${TESTS_DIR}/NodeApi/test/js-native-api/${_mod}/${_mod}.c)
-    target_include_directories(jsr_addon_${_mod} PRIVATE
-        ${TESTS_DIR}/NodeApi/include
-        ${TESTS_DIR}/NodeApi/test/js-native-api
-        ${REPO_ROOT_DIR}/Core/Node-API/Include/Shared
-        ${REPO_ROOT_DIR}/Core/Node-API/Include/Shared/napi
-        ${REPO_ROOT_DIR}/Core/Node-API/Include/Engine/${NAPI_JAVASCRIPT_ENGINE}
-        ${REPO_ROOT_DIR}/Core/Node-API/Include/Engine/${NAPI_JAVASCRIPT_ENGINE}/napi)
-    target_compile_definitions(jsr_addon_${_mod} PRIVATE
-        JSR_NODE_API_STATIC_LINK
-        NODE_API_EXPERIMENTAL_NO_WARNING
-        NODE_GYP_MODULE_NAME=\"${_mod}\"
-        NODE_API_MODULE_REGISTER_FUNCTION=jsr_napi_register_${_mod}
-        NODE_API_MODULE_GET_API_VERSION_FUNCTION=jsr_get_api_version_${_mod})
-    target_sources(UnitTestsJNI PRIVATE $<TARGET_OBJECTS:jsr_addon_${_mod}>)
-endforeach()
+# The conformance addons are built as standalone SHARED lib<name>.so by Tests/NodeApi/CMakeLists.txt,
+# packaged by AGP into nativeLibraryDir, and dlopen'd in-process by node_lite_android. Both they and
+# this host link the shared napi (libnapi.so), so the addons' napi_* imports resolve at load.