Multi addon projects

[kraenhansen]

Adds an ability for cmake-rn to build projects declaring multiple addons in a single invocation.

Supersedes #363, which this started as a follow-up to. It carries that PR's commits, rebased onto next, plus the work needed to resolve the question it was drafted on — where the final output should go.

Building many addons at once

gyp-to-cmake gains --namespaced-targets. CMake requires target names to be unique across a project tree, so sub-projects that each declare an addon target cannot be added to one root project. The flag prefixes the target name with the project name.

cmake-rn then handles a project with more than one shared library target, rather than asserting there is exactly one. packages/node-addon-examples uses this: instead of running cmake-rn once per example, a generated root project adds every example as a sub-directory and a single invocation builds them all.

Where the output goes

Naming the artifacts after the (now namespaced) CMake target and writing them all into one directory breaks the consumer side in two ways:

• Location. The Babel plugin resolves requires literally against the requiring file's directory (plugin.ts, and findNodeAddonForBindings in path-utils.ts), so a prebuild collected into one shared directory is invisible to it.
• Name. getLibraryName derives the library name from the prebuild's path within its package, and the auto-linker renames the .so to lib${libraryName}.so. The plugin derives the same name from the require path. Move or rename the prebuild and the two disagree.

So both are derived per target from the CMake File API instead:

• The output directory defaults to {targetSourceDir}/build/{configuration}. The new {targetSourceDir} placeholder expands to target.paths.source, resolved against --source. A project declaring a single addon at the top level reports ., so it resolves to the same path as before.
• The prebuild is named after the artifact on disk — the target's OUTPUT_NAME, which --namespaced-targets sets back to the original addon name — rather than the CMake target name. Any lib prefix CMake adds is stripped, so a target that does not clear PREFIX (weak-node-api builds a libweak-node-api.so) keeps emitting the prebuild name it does today — the one packages/host/android/build.gradle points its jniLibs at.

The net effect is that each addon lands exactly where building it on its own would have put it, and --namespaced-targets stays an internal CMake concern that nothing downstream can observe.

Grouping is keyed by CMake target name, which CMake guarantees unique within a project. The artifact name is deliberately not used as the key, since every addon may well build an addon.node.

The Apple build directory has to be per target

Because every target now shares one OUTPUT_NAME, the CMAKE_LIBRARY_OUTPUT_DIRECTORY the Apple path sets (to work around CMake #24161) can no longer be shared. With one directory, all 14 example targets resolve to just 3 artifact paths:

BEFORE (shared dir): targets: 14 | unique artifact paths: 3
  collapsed to: out/addon.node, out/binding.node, out/hello.node

Every target then overwrites the previous one's framework, and each prebuild gets assembled from whichever target built last. Test app (iOS) caught this on an earlier push: the app archived fine but simctl install refused it, because two addons carried the same framework identity —

Found bundle at …/Frameworks/example-9--addon.framework with the same identifier
(threadsafe-function-test.addon) as bundle at …/Frameworks/example-6--addon.framework

tests/threadsafe-function sorts last among the sub-projects, so its framework was the one left behind for all of them. Appending $<TARGET_PROPERTY:NAME> to the output directory keeps the #24161 workaround while giving each target its own: 14 targets, 14 distinct artifact paths, verified against real CMake.

Verified against real CMake

Configuring the generated root project and running the resolver over the File API output:

async-test-addon                 -> tests/async/build/RelWithDebInfo/addon.android.node
example-0-hello                  -> examples/1-getting-started/1_hello_world/napi/build/RelWithDebInfo/hello.android.node
example-10-binding               -> examples/5-async-work/async_work_thread_safe_function/napi/build/RelWithDebInfo/binding.android.node
threadsafe-function-test-addon   -> tests/threadsafe-function/build/RelWithDebInfo/addon.android.node
...
targets: 14 | unique outputs: 14

./build/RelWithDebInfo is on the bindings lookup path and the basenames are the original addon names, so require('bindings')('hello') resolves. Separately confirmed against real CMake: a single-addon project reports paths.source === "." and emits to exactly the path it does today, and a target that does not clear PREFIX reports a libweak-node-api.so artifact.

Also in here

• cmake-rn gains --concurrency, bounding how many build tasks run at once. It defaults to the available parallelism, or 1 under --verbose, since interleaved output from concurrent builds is unreadable. EventEmitter.defaultMaxListeners is derived from it — each spawned child attaches three process listeners and removes them on exit, so the live count tracks concurrent children.
• On Apple, xcodebuild invocations run in sequence per build directory, since concurrent invocations against a single Xcode project and its derived data are not reliable. xcodebuild -list runs once per build directory and asynchronously, rather than once per library as a synchronous spawn. cmake --build builds all requested targets in one invocation.
• The root example project is generated by scripts/generate-root-project.mts rather than globbed. A file(GLOB_RECURSE ...) is evaluated once at configure time, so it would miss examples copied in afterwards, and being recursive it would add_subdirectory() both a parent and a nested project — three allow-list entries in copy-examples.mts are commented out as "Brings its own CMake project 👀". The generator stops recursing at the first CMakeLists.txt on a path. Being generated from examples/ (gitignored), the file is gitignored too.
• verify-prebuilds now covers tests/ as well as examples/, and asserts it found a non-zero number of prebuilds, so it cannot pass by simply finding none.
• findCMakeProjects/findCMakeProjectsRecursively are gone along with build-examples.mts.

Changesets

• cmake-rn (minor) — multi-addon support, the per-target output location and naming, and --concurrency. Notes the two things an existing user can observe: --out no longer defaults inside --build (same path unless --build points outside the source directory), and the artifact is named after OUTPUT_NAME (the same thing unless it is set explicitly).
• gyp-to-cmake (minor) — --namespaced-targets.

node-addon-examples is private, so it gets none.

Testing

Run on Linux, against next rebased onto main:

• pnpm run build, pnpm exec eslint ., pnpm exec prettier --check . — all clean.
• pnpm --filter gyp-to-cmake run test — 30 pass, including new --namespaced-targets coverage, of which there was none.
• pnpm --filter cmake-rn run test — 12 pass, including new coverage for the output-path resolution and artifact naming.
• pnpm --filter react-native-node-api run test — 50 pass, 4 fail. The 4 are path-utils permission tests that cannot pass as root (chmod 000 does not stop root); nothing in packages/host is touched here.
• Re-ran the example pipeline end to end and configured the resulting 14-project tree against a stubbed weak-node-api config: it configures without duplicate targets, and all 14 targets resolve to distinct prebuild paths next to their own sources.

The native builds could not be run locally — this is a Linux worker, and per AGENTS.md native builds are not bootstrapped there — so Test app (Android) and Test app (iOS), plus the Weak Node-API jobs, are the real end-to-end check. The last of those covers the PREFIX case described above, and the iOS job is what surfaced the shared-output-directory collision.

Test app (macOS) is deliberately not labelled: it stays blocked on react-native-macos shipping a release based on React Native ≥ 0.82, per #392. Enabling it earlier reproduced exactly the Please set CMAKE_BUILD_TYPE Hermesc failure that issue documents, which is unrelated to this change.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KfKQDvEkxNtkSE4aaF9yG8