Skip to content

Commit e75c50a

Browse files
committed
Move the stub into a node-api-stub package and link it as node-api
- Add a `node-api-stub` package holding `getNodeApiFunctions()`, `generateFunction` and the stub generator with its CMake project. weak-node-api's generator and the host's injector generator now read the function list from it, and weak-node-api no longer builds a stub. - In `hermes` mode, cmake-rn adds the stub to the addon's own build (and leaves it out of the prebuilds), so the addon doesn't need weak-node-api to be built. - Rename the CMake target to `node-api` (`node-api-config.cmake`). - Remove `tests/async/binding.gyp`, which made gyp-to-cmake overwrite the hand-written CMakeLists.txt with one linking weak-node-api. - Port verify-hermes-linkage to TypeScript, comparing the real Hermes against node-api-headers' symbol list instead of a stub binary. Refs #494 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U2xSE4PR7T7WFxexRhihBT
1 parent 27f63dc commit e75c50a

46 files changed

Lines changed: 401 additions & 240 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.changeset/node-api-linkage.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,11 @@
22
"cmake-rn": major
33
"react-native-node-api": minor
44
"weak-node-api": minor
5+
"node-api-stub": minor
56
---
67

78
Add `--node-api-linkage <weak-node-api|hermes|none>` to `cmake-rn`, replacing `--no-weak-node-api-linkage` (use `--node-api-linkage none`).
89

9-
Addons linking the new neutral `node-api-linkage` CMake target (`find_package(node-api-linkage REQUIRED CONFIG)`) link whatever the mode selects. With `hermes` they link a link-time stub of `libhermesvm`, so they record `hermesvm` and call Hermes directly instead of going through `weak-node-api`. The stub is generated from the Node-API headers and built alongside `weak-node-api`; it never ships in an app. Addons naming the `weak-node-api` target directly keep linking it in every mode but `none`. The default stays `weak-node-api`.
10+
Addons linking the new `node-api` CMake target (`find_package(node-api REQUIRED CONFIG)`) link whatever the mode selects. With `hermes` they link a link-time stub of `libhermesvm`, built along with the addon, so they record `hermesvm` and call Hermes directly instead of going through `weak-node-api`, which doesn't need to be built. The stub never ships in an app. Addons naming the `weak-node-api` target directly keep building alongside. The default stays `weak-node-api`.
11+
12+
The new `node-api-stub` package holds the stub and `getNodeApiFunctions()`, which moved there from `weak-node-api`.

‎.github/workflows/check.yml‎

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -321,10 +321,9 @@ jobs:
321321
# The async test addon is built with `--node-api-linkage hermes` (#494).
322322
- name: Verify the async addon links Hermes directly
323323
run: |
324-
./scripts/verify-hermes-linkage.sh \
324+
node --run verify:hermes-linkage -- \
325325
tests/async/build/RelWithDebInfo/addon.apple.node/ios-*-simulator/addon.framework/addon \
326-
../../apps/test-app/ios/build/test-app.xcarchive/Products/Applications/ReactTestApp.app/Frameworks/hermesvm.framework/hermesvm \
327-
../weak-node-api/stub/build/Release/hermesvm.xcframework/ios-*-simulator/hermesvm.framework/hermesvm
326+
../../apps/test-app/ios/build/test-app.xcarchive/Products/Applications/ReactTestApp.app/Frameworks/hermesvm.framework/hermesvm
328327
working-directory: packages/node-addon-examples
329328
- name: Run test app
330329
run: |
@@ -487,10 +486,9 @@ jobs:
487486
echo "Extracting Hermes from $APK"
488487
unzip -o -j "$APK" lib/x86_64/libhermesvm.so -d "$RUNNER_TEMP/apk"
489488
export LLVM_BIN="$ANDROID_HOME/ndk/$NDK_VERSION/toolchains/llvm/prebuilt/linux-x86_64/bin"
490-
./scripts/verify-hermes-linkage.sh \
489+
node --run verify:hermes-linkage -- \
491490
tests/async/build/RelWithDebInfo/addon.android.node/x86_64/libaddon.so \
492-
"$RUNNER_TEMP/apk/libhermesvm.so" \
493-
../weak-node-api/stub/build/Release/hermesvm.android.node/x86_64/libhermesvm.so
491+
"$RUNNER_TEMP/apk/libhermesvm.so"
494492
working-directory: packages/node-addon-examples
495493
- name: Upload device logs
496494
if: always()

‎packages/cmake-rn/README.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -88,19 +88,19 @@ endif()
8888

8989
### Choosing what to link with `--node-api-linkage`
9090

91-
An addon can instead link the neutral `node-api-linkage` target, which links whatever `--node-api-linkage <mode>` selects:
91+
An addon can instead link the `node-api` target, which links whatever `--node-api-linkage <mode>` selects:
9292

9393
- `weak-node-api` (the default): the `weak-node-api` library described above.
94-
- `hermes`: a link-time stub of Hermes' `hermesvm` library, so the addon records `hermesvm` and calls Hermes' Node-API directly. The stub is never loaded or shipped: the app's own Hermes provides the implementation at runtime. This requires a Hermes exporting Node-API (such as the one vendored by `react-native-node-api`), and the addon gets Hermes' own `napi_fatal_error` instead of the host's.
94+
- `hermes`: a link-time stub of Hermes' `hermesvm` library from [`node-api-stub`](../node-api-stub), built along with the addon, so the addon records `hermesvm` and calls Hermes' Node-API directly. The stub is never shipped: the app's own Hermes provides the implementation at runtime. This doesn't need `weak-node-api` to be built, but requires a Hermes exporting Node-API (such as the one vendored by `react-native-node-api`), and the addon gets Hermes' own `napi_fatal_error` instead of the host's.
9595
- `none`: neither target is defined.
9696

9797
```cmake
98-
# Defines the "node-api-linkage" target
99-
find_package(node-api-linkage REQUIRED CONFIG)
98+
# Defines the "node-api" target
99+
find_package(node-api REQUIRED CONFIG)
100100
101-
target_link_libraries(addon PRIVATE node-api-linkage)
101+
target_link_libraries(addon PRIVATE node-api)
102102
```
103103

104-
The `weak-node-api` target stays available in every mode but `none`, so addons linking it directly can be built alongside.
104+
Addons linking the `weak-node-api` target directly can be built alongside: it's defined in the `weak-node-api` mode, and in the `hermes` mode whenever `weak-node-api` is built.
105105

106106
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`.
Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Defines the `node-api` target, linking what cmake-rn's --node-api-linkage
2+
# selected (NODE_API_LINKAGE).
3+
4+
if(TARGET node-api)
5+
return()
6+
endif()
7+
8+
foreach(variable NODE_API_LINKAGE NODE_API_INC)
9+
if(NOT DEFINED ${variable})
10+
message(FATAL_ERROR "${variable} is not set: build with cmake-rn and a --node-api-linkage other than 'none'")
11+
endif()
12+
endforeach()
13+
14+
if(NODE_API_LINKAGE STREQUAL "hermes")
15+
if(NOT TARGET node-api-stub)
16+
add_subdirectory("${NODE_API_STUB_DIR}" "${CMAKE_BINARY_DIR}/node-api-stub")
17+
endif()
18+
add_library(node-api INTERFACE)
19+
target_link_libraries(node-api INTERFACE node-api-stub)
20+
target_include_directories(node-api INTERFACE ${NODE_API_INC})
21+
message(STATUS "Linking Node-API against a stub of Hermes")
22+
else()
23+
if(NOT DEFINED NODE_API_LIB)
24+
message(FATAL_ERROR "NODE_API_LIB is not set")
25+
endif()
26+
add_library(node-api SHARED IMPORTED)
27+
set_target_properties(node-api PROPERTIES
28+
IMPORTED_LOCATION "${NODE_API_LIB}"
29+
INTERFACE_INCLUDE_DIRECTORIES "${NODE_API_INC}"
30+
)
31+
message(STATUS "Linking Node-API against ${NODE_API_LINKAGE}: ${NODE_API_LIB}")
32+
endif()

‎packages/cmake-rn/cmake/node-api-linkage-config.cmake‎

Lines changed: 0 additions & 21 deletions
This file was deleted.

‎packages/cmake-rn/package.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,8 @@
3030
"cmake-file-api": "workspace:*",
3131
"react-native-node-api": "workspace:*",
3232
"zod": "^4.1.11",
33-
"weak-node-api": "workspace:*"
33+
"weak-node-api": "workspace:*",
34+
"node-api-stub": "workspace:*"
3435
},
3536
"peerDependencies": {
3637
"node-addon-api": "^8.3.1",

‎packages/cmake-rn/src/platforms/android.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ import {
1313
AndroidTriplet as Triplet,
1414
} from "react-native-node-api";
1515
import * as cmakeFileApi from "cmake-file-api";
16+
import { NODE_API_STUB_TARGET } from "node-api-stub";
1617

1718
import type { BaseOpts, Platform } from "./types.js";
1819
import { getArtifactName, toDefineArguments } from "../helpers.js";
@@ -280,6 +281,7 @@ export const platform: Platform<Triplet[], AndroidOpts> = {
280281
const sharedLibraries = targets.filter(
281282
({ type, name }) =>
282283
type === "SHARED_LIBRARY" &&
284+
name !== NODE_API_STUB_TARGET &&
283285
(target.length === 0 || target.includes(name)),
284286
);
285287
await Promise.all(

‎packages/cmake-rn/src/platforms/apple.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ import {
1919

2020
import type { Platform } from "./types.js";
2121
import * as cmakeFileApi from "cmake-file-api";
22+
import { NODE_API_STUB_TARGET } from "node-api-stub";
2223
import { getArtifactName, toDefineArguments } from "../helpers.js";
2324
import {
2425
getCmakeJSVariables,
@@ -189,6 +190,7 @@ async function readCmakeSharedLibraryTargets(
189190
return targets.filter(
190191
({ type, name }) =>
191192
type === "SHARED_LIBRARY" &&
193+
name !== NODE_API_STUB_TARGET &&
192194
(target.length === 0 || target.includes(name)),
193195
);
194196
}

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

Lines changed: 31 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -12,10 +12,9 @@ import {
1212
import {
1313
applePrebuildPath,
1414
androidPrebuildPath,
15-
hermesStubApplePrebuildPath,
16-
hermesStubAndroidPrebuildPath,
1715
weakNodeApiCmakePath,
1816
} from "weak-node-api";
17+
import { nodeApiStubPath } from "node-api-stub";
1918

2019
import { ANDROID_ARCHITECTURES } from "./platforms/android.js";
2120
import { getNodeAddonHeadersPath, getNodeApiHeadersPath } from "./headers.js";
@@ -26,44 +25,26 @@ export function toCmakePath(input: string) {
2625

2726
const NODE_API_CONFIG_DIR = path.resolve(import.meta.dirname, "../cmake");
2827

29-
function getPrebuildPath(
30-
triplet: SupportedTriplet | "apple",
31-
{
32-
apple,
33-
android,
34-
libraryName,
35-
}: { apple: string; android: string; libraryName: string },
36-
): string {
28+
function findWeakNodeApiPath(triplet: SupportedTriplet | "apple") {
3729
if (triplet === "apple" || isAppleTriplet(triplet)) {
38-
assert(fs.existsSync(apple), `Expected an XCFramework at ${apple}`);
39-
return apple;
30+
return applePrebuildPath;
4031
} else if (isAndroidTriplet(triplet)) {
41-
const libraryPath = path.join(
42-
android,
32+
return path.join(
33+
androidPrebuildPath,
4334
ANDROID_ARCHITECTURES[triplet],
44-
`lib${libraryName}.so`,
35+
"libweak-node-api.so",
4536
);
46-
assert(fs.existsSync(libraryPath), `Expected library at ${libraryPath}`);
47-
return libraryPath;
4837
} else {
4938
throw new Error(`Unexpected triplet: ${triplet as string}`);
5039
}
5140
}
5241

53-
export function getWeakNodeApiPath(triplet: SupportedTriplet | "apple") {
54-
return getPrebuildPath(triplet, {
55-
apple: applePrebuildPath,
56-
android: androidPrebuildPath,
57-
libraryName: "weak-node-api",
58-
});
59-
}
60-
61-
export function getHermesStubPath(triplet: SupportedTriplet | "apple") {
62-
return getPrebuildPath(triplet, {
63-
apple: hermesStubApplePrebuildPath,
64-
android: hermesStubAndroidPrebuildPath,
65-
libraryName: "hermesvm",
66-
});
42+
export function getWeakNodeApiPath(
43+
triplet: SupportedTriplet | "apple",
44+
): string {
45+
const result = findWeakNodeApiPath(triplet);
46+
assert(fs.existsSync(result), `Expected weak-node-api at ${result}`);
47+
return result;
6748
}
6849

6950
function getNodeApiIncludePaths() {
@@ -91,9 +72,7 @@ export function getWeakNodeApiVariables(
9172
}
9273

9374
/**
94-
* Variables for the selected --node-api-linkage: the neutral `node-api-linkage`
95-
* target follows the mode, while the `weak-node-api` target stays available so
96-
* addons naming it directly keep building alongside.
75+
* Variables for the selected --node-api-linkage, which the `node-api` target follows.
9776
*/
9877
export function getNodeApiLinkageVariables(
9978
linkage: NodeApiLinkage,
@@ -102,16 +81,26 @@ export function getNodeApiLinkageVariables(
10281
if (linkage === "none") {
10382
return {};
10483
}
84+
const nodeApiVariables = {
85+
// Enable use of `find_package(node-api REQUIRED CONFIG)`
86+
"node-api_DIR": NODE_API_CONFIG_DIR,
87+
NODE_API_LINKAGE: linkage,
88+
NODE_API_INC: getNodeApiIncludePaths().join(";"),
89+
};
90+
if (linkage === "hermes") {
91+
return {
92+
// Keeps the `weak-node-api` target available to addons naming it, without requiring it
93+
...(fs.existsSync(findWeakNodeApiPath(triplet))
94+
? getWeakNodeApiVariables(triplet)
95+
: {}),
96+
...nodeApiVariables,
97+
NODE_API_STUB_DIR: nodeApiStubPath,
98+
};
99+
}
105100
return {
106101
...getWeakNodeApiVariables(triplet),
107-
// Enable use of `find_package(node-api-linkage REQUIRED CONFIG)`
108-
"node-api-linkage_DIR": NODE_API_CONFIG_DIR,
109-
NODE_API_LINKAGE: linkage,
110-
NODE_API_LINKAGE_INC: getNodeApiIncludePaths().join(";"),
111-
NODE_API_LINKAGE_LIB:
112-
linkage === "hermes"
113-
? getHermesStubPath(triplet)
114-
: getWeakNodeApiPath(triplet),
102+
...nodeApiVariables,
103+
NODE_API_LIB: getWeakNodeApiPath(triplet),
115104
};
116105
}
117106

‎packages/cmake-rn/tsconfig.node.json‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,5 +8,10 @@
88
"types": ["node"]
99
},
1010
"include": ["src/**/*.ts"],
11-
"exclude": ["**/*.test.ts"]
11+
"exclude": ["**/*.test.ts"],
12+
"references": [
13+
{
14+
"path": "../node-api-stub/tsconfig.node.json"
15+
}
16+
]
1217
}

0 commit comments

Comments
 (0)