Make injection of CMAKE_JS_* variables opt-in and provide our own explicit way of linking with Node-API

Author: kraenhansen

.changeset/open-ducks-shop.md

@@ -0,0 +1,5 @@
+---
+"cmake-rn": minor
+---
+
+Breaking: CMAKE*JS*\* defines are no longer injected by default (use --cmake-js to opt-in)

packages/cmake-rn/README.md

@@ -3,3 +3,24 @@
 A wrapper around Cmake making it easier to produce prebuilt binaries targeting iOS and Android matching [the prebuilt binary specification](https://github.com/callstackincubator/react-native-node-api/blob/main/docs/PREBUILDS.md).
 
 Serves the same purpose as `cmake-js` does for the Node.js community and could potentially be upstreamed into `cmake-js` eventually.
+
+## Linking against Node-API
+
+Android's dynamic linker impose restrictions on the access to global symbols (such as the Node-API free functions): A dynamic library must explicitly declare any dependency bringing symbols it needs as `DT_NEEDED`.
+
+The implementation of Node-API is split between Hermes and our host package and to avoid addons having to explicitly link against either, we've introduced a `weak-node-api` library (published in `react-native-node-api` package). This library expose only Node-API and will have it's implementation injected by the host.
+
+To link against `weak-node-api` just include the CMake config exposed through `WEAK_NODE_API_CONFIG` and add `weak-node-api` to the `target_link_libraries` of the addon's library target.
+
+```cmake
+cmake_minimum_required(VERSION 3.15...3.31)
+project(tests-buffers)
+
+include(${WEAK_NODE_API_CONFIG})
+
+add_library(addon SHARED addon.c)
+target_link_libraries(addon PRIVATE weak-node-api)
+target_compile_features(addon PRIVATE cxx_std_20)
+```
+
+This is different from how `cmake-js` "injects" the Node-API for linking (via `${CMAKE_JS_INC}`, `${CMAKE_JS_SRC}` and `${CMAKE_JS_LIB}`). To allow for interoperability between these tools, we inject these when you pass `--cmake-js` to `cmake-rn`.

packages/cmake-rn/src/cli.ts

@@ -14,7 +14,10 @@ import {
 } from "@react-native-node-api/cli-utils";
 import { isSupportedTriplet } from "react-native-node-api";
 
-import { getWeakNodeApiVariables } from "./weak-node-api.js";
+import {
+  getCmakeJSVariables,
+  getWeakNodeApiVariables,
+} from "./weak-node-api.js";
 import {
   platforms,
   allTriplets as allTriplets,
@@ -117,6 +120,11 @@ const noWeakNodeApiLinkageOption = new Option(
   "Don't pass the path of the weak-node-api library from react-native-node-api",
 );
 
+const cmakeJsOption = new Option(
+  "--cmake-js",
+  "Define CMAKE_JS_* variables used for compatibility with cmake-js",
+).default(false);
+
 let program = new Command("cmake-rn")
   .description("Build React Native Node API modules with CMake")
   .addOption(tripletOption)
@@ -129,7 +137,8 @@ let program = new Command("cmake-rn")
   .addOption(cleanOption)
   .addOption(targetOption)
   .addOption(noAutoLinkOption)
-  .addOption(noWeakNodeApiLinkageOption);
+  .addOption(noWeakNodeApiLinkageOption)
+  .addOption(cmakeJsOption);
 
 for (const platform of platforms) {
   const allOption = new Option(
@@ -296,16 +305,23 @@ async function configureProject<T extends string>(
   options: BaseOpts,
 ) {
   const { triplet, buildPath, outputPath } = context;
-  const { verbose, source, weakNodeApiLinkage } = options;
+  const { verbose, source, weakNodeApiLinkage, cmakeJs } = options;
+
+  // TODO: Make the two following definitions a part of the platform definition
 
   const nodeApiDefinitions =
     weakNodeApiLinkage && isSupportedTriplet(triplet)
-      ? getWeakNodeApiVariables(triplet)
-      : // TODO: Make this a part of the platform definition
-        [];
+      ? [getWeakNodeApiVariables(triplet)]
+      : [];
+
+  const cmakeJsDefinitions =
+    cmakeJs && isSupportedTriplet(triplet)
+      ? [getCmakeJSVariables(triplet)]
+      : [];
 
   const definitions = [
     ...nodeApiDefinitions,
+    ...cmakeJsDefinitions,
     ...options.define,
     { CMAKE_LIBRARY_OUTPUT_DIRECTORY: outputPath },
   ];

packages/cmake-rn/src/weak-node-api.ts

@@ -41,22 +41,36 @@ export function getWeakNodeApiPath(triplet: SupportedTriplet): string {
   }
 }
 
-export function getWeakNodeApiVariables(triplet: SupportedTriplet) {
+function getNodeApiIncludePaths() {
   const includePaths = [getNodeApiHeadersPath(), getNodeAddonHeadersPath()];
   for (const includePath of includePaths) {
     assert(
       !includePath.includes(";"),
       `Include path with a ';' is not supported: ${includePath}`,
     );
   }
-  const cmakeConfigPath = path.join(weakNodeApiPath, "weak-node-api.cmake");
-  const libraryPath = getWeakNodeApiPath(triplet);
+  return includePaths;
+}
+
+export function getWeakNodeApiVariables(
+  triplet: SupportedTriplet,
+): Record<string, string> {
   return {
     // Expose an includable CMake config file declaring the weak-node-api target
-    WEAK_NODE_API_CONFIG: cmakeConfigPath,
-    WEAK_NODE_API_LIB: libraryPath,
-    // For compatibility with cmake-js
-    CMAKE_JS_INC: includePaths.join(";"),
-    CMAKE_JS_LIB: libraryPath,
+    WEAK_NODE_API_CONFIG: path.join(weakNodeApiPath, "weak-node-api.cmake"),
+    WEAK_NODE_API_INC: getNodeApiIncludePaths().join(";"),
+    WEAK_NODE_API_LIB: getWeakNodeApiPath(triplet),
+  };
+}
+
+/**
+ * For compatibility with cmake-js
+ */
+export function getCmakeJSVariables(
+  triplet: SupportedTriplet,
+): Record<string, string> {
+  return {
+    CMAKE_JS_INC: getNodeApiIncludePaths().join(";"),
+    CMAKE_JS_LIB: getWeakNodeApiPath(triplet),
   };
 }