Emit prebuilds per target, next to their sources

A project declaring multiple addons wrote every prebuild into a single
output directory, named after the CMake target. Both the location and the
name are now derived per target from the CMake File API:

- The output directory defaults to {targetSourceDir}/build/{configuration},
  where the new {targetSourceDir} placeholder expands to the target's own
  source directory. A single-addon project reports "." and so resolves to
  the same path as before.
- The prebuild is named after the artifact on disk (the target's
  OUTPUT_NAME) rather than the target name, so a target renamed to avoid a
  clash within the project still produces the name the JS require expects.

Together this keeps a prebuild where the Babel plugin and auto-linking
resolve it from, and reduces --namespaced-targets to an internal concern.

Also fixes, in the same area:

- gyp-to-cmake emitted OUTPUT_NAME regardless of --namespaced-targets, due
  to an always-truthy condition, and never emitted it for Apple framework
  targets, which CMake names after it.
- The Apple build ran a full "cmake --build" once per shared library,
  concurrently against one build tree, and called "xcodebuild -list" (a
  synchronous spawn) once per library per triplet.
- xcodebuild invocations now run in sequence per build directory, as
  concurrent invocations against a single Xcode project are not reliable.
- postBuild looked for "<target name>.framework" while createAppleFramework
  names it after the artifact, so the two diverged under namespacing.
- --concurrency accepted any value, and did not implement the documented
  fallback to 1 under --verbose. Max listeners is now derived from it.
- verify-prebuilds globbed a directory the prebuilds had moved out of, so
  it passed by finding nothing. It now covers tests/ too and requires a
  non-zero count.
- The root example project globbed recursively, which both missed examples
  copied in after configure and would add a nested project twice. It is
  now generated from the same script pipeline.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KfKQDvEkxNtkSE4aaF9yG8

Author: claude

.changeset/chilly-trains-nail.md

@@ -2,4 +2,22 @@
 "cmake-rn": minor
 ---
 
-Add support for building projects declaring multiple shared object libraries into Node-API addons
+Add support for building projects declaring multiple shared object libraries into Node-API addons.
+
+Each addon is emitted next to the sources it was built from, so that a project
+declaring many addons produces the same layout as building each of them on its
+own. Both the location and the name of an artifact are derived from the target
+that produced it:
+
+- `--out` supports a new `{targetSourceDir}` placeholder, expanding to the source
+  directory of the target being emitted, and now defaults to
+  `{targetSourceDir}/build/{configuration}`. This resolves to the same path as
+  before, unless `--build` is pointed outside of the source directory.
+- The artifact is named after the target's `OUTPUT_NAME` rather than the CMake
+  target name. These are the same unless `OUTPUT_NAME` is set explicitly, which is
+  how a project can give its targets the unique names CMake requires without
+  affecting the name of the addon.
+
+Also adds `--concurrency`, limiting how many build tasks run at once. It defaults
+to the available parallelism, or to 1 when `--verbose` is enabled, since
+interleaved output from concurrent builds is hard to read.

.changeset/real-emus-jam.md

@@ -2,4 +2,9 @@
 "gyp-to-cmake": minor
 ---
 
-Add --namespaced-targets to allow a root project to add many sub-projects
+Add --namespaced-targets to allow a root project to add many sub-projects.
+
+CMake requires target names to be unique across a project tree, so sub-projects
+that each declare an `addon` target cannot be added to a single root project. This
+prefixes the target name with the project name, while setting `OUTPUT_NAME` so the
+artifact keeps the name a `require` resolves against.

packages/cmake-rn/src/cli.ts

@@ -13,6 +13,7 @@ import {
   assertFixable,
   wrapAction,
   pLimit,
+  InvalidArgumentError,
 } from "@react-native-node-api/cli-utils";
 
 import {
@@ -23,9 +24,22 @@ import {
 } from "./platforms.js";
 import { Platform } from "./platforms/types.js";
 import { getCcachePath } from "./ccache.js";
-
-// We're attaching a lot of listeners when spawning in parallel
-EventEmitter.defaultMaxListeners = 500;
+import { createOutputPathResolver, expandTemplate } from "./output-path.js";
+
+/**
+ * Every spawned child attaches a "SIGINT", "SIGTERM" and "exit" listener to the
+ * process, which are removed again once the child exits. The number of live
+ * listeners therefore tracks the number of *concurrently* running children, so
+ * the limit is derived from the concurrency rather than being a magic constant.
+ */
+function raiseMaxListeners(concurrency: number) {
+  const LISTENERS_PER_CHILD = 3;
+  const HEADROOM = 10;
+  EventEmitter.defaultMaxListeners = Math.max(
+    EventEmitter.defaultMaxListeners,
+    concurrency * LISTENERS_PER_CHILD + HEADROOM,
+  );
+}
 
 const verboseOption = new Option(
   "--verbose",
@@ -77,8 +91,8 @@ const cleanOption = new Option(
 
 const outPathOption = new Option(
   "--out <path>",
-  "Specify the output directory to store the final build artifacts",
-).default("{build}/{configuration}");
+  "Specify the output directory to store the final build artifacts. Supports the {targetSourceDir} placeholder, which expands to the source directory of the target being emitted",
+).default("{targetSourceDir}/build/{configuration}");
 
 const defineOption = new Option(
   "-D,--define <entry...>",
@@ -135,10 +149,16 @@ const concurrencyOption = new Option(
   "--concurrency <limit>",
   "Limit the number of concurrent tasks",
 )
-  .argParser((value) => parseInt(value, 10))
+  .argParser((value) => {
+    const result = Number(value);
+    if (!Number.isSafeInteger(result) || result < 1) {
+      throw new InvalidArgumentError("Expected a positive integer.");
+    }
+    return result;
+  })
   .default(
-    os.availableParallelism(),
-    `${os.availableParallelism()} or 1 when verbose is enabled`,
+    undefined,
+    `${os.availableParallelism()} or 1 when --verbose is enabled`,
   );
 
 let program = new Command("cmake-rn")
@@ -168,33 +188,22 @@ for (const platform of platforms) {
   program = platform.amendCommand(program);
 }
 
-function expandTemplate(
-  input: string,
-  values: Record<string, unknown>,
-): string {
-  return input.replaceAll(/{([^}]+)}/g, (_, key: string) =>
-    typeof values[key] === "string" ? values[key] : "",
-  );
-}
-
 program = program.action(
   wrapAction(async ({ triplet: requestedTriplets, ...baseOptions }) => {
     baseOptions.build = path.resolve(
       process.cwd(),
       expandTemplate(baseOptions.build, baseOptions),
     );
-    baseOptions.out = path.resolve(
-      process.cwd(),
-      expandTemplate(baseOptions.out, baseOptions),
-    );
+    // Note: {targetSourceDir} is deliberately left unexpanded here, as it is
+    // only known per target, once the CMake File API has been read.
+    baseOptions.out = expandTemplate(baseOptions.out, baseOptions);
     const {
       verbose,
       clean,
       source,
       out,
       build: buildPath,
       ccachePath,
-      concurrency,
     } = baseOptions;
 
     assertFixable(
@@ -246,7 +255,13 @@ program = program.action(
       }
     }
 
+    // Interleaved output from concurrent builds is unreadable, so verbose
+    // builds default to running one task at a time.
+    const concurrency =
+      baseOptions.concurrency ?? (verbose ? 1 : os.availableParallelism());
+    raiseMaxListeners(concurrency);
     const limit = pLimit(concurrency);
+    const resolveOutputPath = createOutputPathResolver(out, source);
 
     const tripletContexts = [...triplets].map((triplet) => {
       const platform = findPlatformForTriplet(triplet);
@@ -351,7 +366,11 @@ program = program.action(
       if (relevantTriplets.length == 0) {
         continue;
       }
-      await platform.postBuild(out, relevantTriplets, baseOptions);
+      await platform.postBuild(
+        resolveOutputPath,
+        relevantTriplets,
+        baseOptions,
+      );
     }
   }),
 );

packages/cmake-rn/src/helpers.ts

@@ -1,3 +1,24 @@
+import path from "node:path";
+
+/**
+ * The name of the emitted prebuild is derived from the artifact on disk (i.e.
+ * the target's OUTPUT_NAME) rather than the CMake target name.
+ *
+ * A project declaring multiple addons has to give its targets unique names,
+ * which for generated projects means namespacing them (see gyp-to-cmake's
+ * --namespaced-targets). The artifact keeps the name the JS `require` expects,
+ * so deriving from it keeps the prebuild's name independent of how the target
+ * had to be named to avoid a clash.
+ */
+export function getArtifactName(artifactPath: string) {
+  const basename = path.basename(artifactPath, path.extname(artifactPath));
+  // Unless a target clears PREFIX (as the generated addon projects do), CMake
+  // prefixes a shared library with "lib". The prebuild is named after the
+  // library rather than the file, mirroring how createAndroidLibsDirectory adds
+  // the prefix back when copying the library into the libs directory.
+  return basename.startsWith("lib") ? basename.slice("lib".length) : basename;
+}
+
 export function toDefineArguments(
   declarations: Array<Record<string, string | undefined>>,
 ) {

packages/cmake-rn/src/output-path.test.ts

@@ -0,0 +1,89 @@
+import assert from "node:assert/strict";
+import path from "node:path";
+import { describe, it } from "node:test";
+
+import { createOutputPathResolver, expandTemplate } from "./output-path.js";
+import { getArtifactName } from "./helpers.js";
+
+describe("expandTemplate", () => {
+  it("expands known placeholders", () => {
+    assert.equal(
+      expandTemplate("{build}/{configuration}", {
+        build: "/tmp/build",
+        configuration: "Release",
+      }),
+      "/tmp/build/Release",
+    );
+  });
+
+  it("leaves unknown placeholders untouched, to allow a later pass", () => {
+    assert.equal(
+      expandTemplate("{targetSourceDir}/build/{configuration}", {
+        configuration: "Release",
+      }),
+      "{targetSourceDir}/build/Release",
+    );
+  });
+});
+
+describe("createOutputPathResolver", () => {
+  const source = path.resolve("/projects/my-app");
+
+  it("resolves a top-level target next to the source directory", () => {
+    const resolve = createOutputPathResolver(
+      "{targetSourceDir}/build/Release",
+      source,
+    );
+    // A single-addon project reports "." as the target's source directory,
+    // which has to keep emitting where it always has.
+    assert.equal(resolve("."), path.join(source, "build/Release"));
+  });
+
+  it("resolves each target of a multi-addon project next to its own sources", () => {
+    const resolve = createOutputPathResolver(
+      "{targetSourceDir}/build/Release",
+      source,
+    );
+    assert.equal(
+      resolve("examples/hello"),
+      path.join(source, "examples/hello/build/Release"),
+    );
+    assert.equal(
+      resolve("examples/goodbye"),
+      path.join(source, "examples/goodbye/build/Release"),
+    );
+  });
+
+  it("handles a target source directory outside the top-level source", () => {
+    const resolve = createOutputPathResolver(
+      "{targetSourceDir}/build/Release",
+      source,
+    );
+    const outside = path.resolve("/elsewhere/vendored");
+    assert.equal(resolve(outside), path.join(outside, "build/Release"));
+  });
+
+  it("supports a template without the placeholder", () => {
+    const resolve = createOutputPathResolver("/tmp/out", source);
+    assert.equal(resolve("examples/hello"), path.resolve("/tmp/out"));
+  });
+});
+
+describe("getArtifactName", () => {
+  it("derives the name from the artifact rather than the target", () => {
+    // gyp-to-cmake --namespaced-targets builds "addon.node" from a target named
+    // "<project>-addon", and the prebuild has to keep the artifact's name.
+    assert.equal(getArtifactName("examples/hello/addon.node"), "addon");
+  });
+
+  it("handles framework artifacts", () => {
+    assert.equal(getArtifactName("out/addon.framework/addon"), "addon");
+  });
+
+  it("strips the prefix CMake adds to shared libraries", () => {
+    // weak-node-api does not clear PREFIX, so it builds a "libweak-node-api.so"
+    // and has to keep emitting a "weak-node-api.android.node" — the path
+    // packages/host/android/build.gradle points its jniLibs at.
+    assert.equal(getArtifactName("libweak-node-api.so"), "weak-node-api");
+  });
+});

packages/cmake-rn/src/output-path.ts

@@ -0,0 +1,35 @@
+import path from "node:path";
+
+/**
+ * Expand `{placeholder}` occurrences in a template.
+ *
+ * Placeholders without a value are left untouched, so a template can be expanded
+ * in multiple passes as more values become known.
+ */
+export function expandTemplate(
+  input: string,
+  values: Record<string, unknown>,
+): string {
+  return input.replaceAll(/{([^}]+)}/g, (match, key: string) =>
+    typeof values[key] === "string" ? values[key] : match,
+  );
+}
+
+/**
+ * The final artifacts are emitted per target, relative to the source directory
+ * of the target itself. This keeps a target's prebuild next to the sources it
+ * was built from, even when a single project declares many addons, which is what
+ * the Babel plugin and auto-linking rely on to resolve a `require`.
+ */
+export function createOutputPathResolver(outTemplate: string, source: string) {
+  return function resolveOutputPath(targetSourceDir: string) {
+    return path.resolve(
+      process.cwd(),
+      expandTemplate(outTemplate, {
+        // `paths.source` is relative to the top-level source directory, unless
+        // the target lives outside of it, in which case it is already absolute.
+        targetSourceDir: path.resolve(source, targetSourceDir),
+      }),
+    );
+  };
+}

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

@@ -14,7 +14,7 @@ import {
 import * as cmakeFileApi from "cmake-file-api";
 
 import type { BaseOpts, Platform } from "./types.js";
-import { toDefineArguments } from "../helpers.js";
+import { getArtifactName, toDefineArguments } from "../helpers.js";
 import {
   getCmakeJSVariables,
   getWeakNodeApiVariables,
@@ -208,13 +208,20 @@ export const platform: Platform<Triplet[], AndroidOpts> = {
     return typeof ANDROID_HOME === "string" && fs.existsSync(ANDROID_HOME);
   },
   async postBuild(
-    outputPath,
+    resolveOutputPath,
     triplets,
     { autoLink, configuration, target, build, strip, ndkVersion },
   ) {
+    // Keyed by CMake target name, which CMake guarantees to be unique within a
+    // project. The artifact name is not: every addon of a multi-addon project
+    // may well build an "addon.node".
     const prebuilds: Record<
       string,
-      { triplet: Triplet; libraryPath: string }[]
+      {
+        artifactName: string;
+        targetSourceDir: string;
+        libraries: { triplet: Triplet; libraryPath: string }[];
+      }
     > = {};
 
     for (const { triplet, spawn } of triplets) {
@@ -240,7 +247,11 @@ export const platform: Platform<Triplet[], AndroidOpts> = {
           const [artifact] = artifacts;
           // Add prebuild entry, creating a new entry if needed
           if (!(sharedLibrary.name in prebuilds)) {
-            prebuilds[sharedLibrary.name] = [];
+            prebuilds[sharedLibrary.name] = {
+              artifactName: getArtifactName(artifact.path),
+              targetSourceDir: sharedLibrary.paths.source,
+              libraries: [],
+            };
           }
           const libraryPath = path.join(buildPath, artifact.path);
           assert(
@@ -257,18 +268,20 @@ export const platform: Platform<Triplet[], AndroidOpts> = {
             );
             await spawn(stripToolPath, [libraryPath]);
           }
-          prebuilds[sharedLibrary.name].push({
+          prebuilds[sharedLibrary.name].libraries.push({
             triplet,
             libraryPath,
           });
         }),
       );
     }
 
-    for (const [libraryName, libraries] of Object.entries(prebuilds)) {
+    for (const { artifactName, targetSourceDir, libraries } of Object.values(
+      prebuilds,
+    )) {
       const prebuildOutputPath = path.resolve(
-        outputPath,
-        `${libraryName}.android.node`,
+        resolveOutputPath(targetSourceDir),
+        `${artifactName}.android.node`,
       );
       await oraPromise(
         createAndroidLibsDirectory({
@@ -277,10 +290,10 @@ export const platform: Platform<Triplet[], AndroidOpts> = {
           autoLink,
         }),
         {
-          text: `Assembling Android libs directory (${libraryName})`,
-          successText: `Android libs directory (${libraryName}) assembled into ${prettyPath(prebuildOutputPath)}`,
+          text: `Assembling Android libs directory (${artifactName})`,
+          successText: `Android libs directory (${artifactName}) assembled into ${prettyPath(prebuildOutputPath)}`,
           failText: ({ message }) =>
-            `Failed to assemble Android libs directory (${libraryName}): ${message}`,
+            `Failed to assemble Android libs directory (${artifactName}): ${message}`,
         },
       );
     }