Add support for versioned frameworks

kraenhansen · kraenhansen · commit 36ba0ae63df2 · 2026-02-14T21:54:11.000+01:00
diff --git a/.changeset/rich-weeks-cry.md b/.changeset/rich-weeks-cry.md
@@ -0,0 +1,7 @@
+---
+"cmake-rn": minor
+"ferric-cli": minor
+"react-native-node-api": minor
+---
+
+Add support for building versioned frameworks for Apple Darwin / macOS
diff --git a/packages/cmake-rn/src/platforms/apple.ts b/packages/cmake-rn/src/platforms/apple.ts
@@ -417,7 +417,7 @@ export const platform: Platform<Triplet[], AppleOpts> = {
       const [artifact] = artifacts;
       await createAppleFramework({
         libraryPath: path.join(buildPath, artifact.path),
-        versioned: triplet.endsWith("-darwin"),
+        kind: triplet.endsWith("-darwin") ? "versioned" : "flat",
         bundleIdentifier: appleBundleIdentifier,
       });
     }
diff --git a/packages/ferric/src/build.ts b/packages/ferric/src/build.ts
@@ -309,8 +309,8 @@ export const buildCommand = new Command("build")
                 limit(() =>
                   createAppleFramework({
                     libraryPath: library.path,
+                    kind: library.os === "darwin" ? "versioned" : "flat",
                     bundleIdentifier: appleBundleIdentifier,
-                    versioned: library.os === "darwin",
                   }),
                 ),
               ),
@@ -399,7 +399,7 @@ async function createUniversalAppleLibraries(
       groups.map(async ({ os, paths }) => {
         if (paths.length === 0) {
           return [];
-        } else if (paths.length == 1) {
+        } else if (paths.length === 1) {
           return [{ os, path: paths[0] }];
         } else {
           return [
diff --git a/packages/host/src/node/prebuilds/apple.ts b/packages/host/src/node/prebuilds/apple.ts
@@ -22,64 +22,184 @@ export function escapeBundleIdentifier(input: string) {
   return input.replace(/[^A-Za-z0-9-.]/g, "-");
 }
 
+/** Serialize a plist object and write it to the given path. */
+async function writeInfoPlist(
+  infoPlistPath: string,
+  plistDict: Record<string, unknown>,
+) {
+  await fs.promises.writeFile(infoPlistPath, plist.build(plistDict), "utf8");
+}
+
+/** Build and write the framework Info.plist to the given path. */
+async function writeFrameworkInfoPlist(
+  infoPlistPath: string,
+  libraryName: string,
+  bundleIdentifier?: string,
+) {
+  await writeInfoPlist(infoPlistPath, {
+    CFBundleDevelopmentRegion: "en",
+    CFBundleExecutable: libraryName,
+    CFBundleIdentifier: escapeBundleIdentifier(
+      bundleIdentifier ?? `com.callstackincubator.node-api.${libraryName}`,
+    ),
+    CFBundleInfoDictionaryVersion: "6.0",
+    CFBundleName: libraryName,
+    CFBundlePackageType: "FMWK",
+    CFBundleShortVersionString: "1.0",
+    CFBundleVersion: "1",
+    NSPrincipalClass: "",
+  });
+}
+
+/** Update the library binary’s install name so it resolves correctly at load time. */
+async function updateLibraryInstallName(
+  binaryPath: string,
+  libraryName: string,
+  cwd: string,
+) {
+  await spawn(
+    "install_name_tool",
+    ["-id", `@rpath/${libraryName}.framework/${libraryName}`, binaryPath],
+    { outputMode: "buffered", cwd },
+  );
+}
+
 type CreateAppleFrameworkOptions = {
   libraryPath: string;
-  versioned?: boolean;
+  kind: "flat" | "versioned";
   bundleIdentifier?: string;
 };
 
-export async function createAppleFramework({
+/**
+ * Creates a flat (non-versioned) .framework bundle:
+ * MyFramework.framework/MyFramework, Info.plist, Headers/
+ */
+async function createFlatFramework({
   libraryPath,
-  versioned = false,
+  frameworkPath,
+  libraryName,
   bundleIdentifier,
-}: CreateAppleFrameworkOptions) {
-  if (versioned) {
-    // TODO: Add support for generating a Versions/Current/Resources/Info.plist convention framework
-    throw new Error("Creating versioned frameworks is not supported yet");
-  }
-  assert(fs.existsSync(libraryPath), `Library not found: ${libraryPath}`);
-  // Write a info.plist file to the framework
-  const libraryName = path.basename(libraryPath, path.extname(libraryPath));
-  const frameworkPath = path.join(
-    path.dirname(libraryPath),
-    `${libraryName}.framework`,
-  );
-  // Create the framework from scratch
-  await fs.promises.rm(frameworkPath, { recursive: true, force: true });
+}: {
+  libraryPath: string;
+  frameworkPath: string;
+  libraryName: string;
+  bundleIdentifier?: string;
+}): Promise<string> {
   await fs.promises.mkdir(frameworkPath);
   await fs.promises.mkdir(path.join(frameworkPath, "Headers"));
-  // Create an empty Info.plist file
-  await fs.promises.writeFile(
+  await writeFrameworkInfoPlist(
     path.join(frameworkPath, "Info.plist"),
-    plist.build({
-      CFBundleDevelopmentRegion: "en",
-      CFBundleExecutable: libraryName,
-      CFBundleIdentifier: escapeBundleIdentifier(
-        bundleIdentifier ?? `com.callstackincubator.node-api.${libraryName}`,
-      ),
-      CFBundleInfoDictionaryVersion: "6.0",
-      CFBundleName: libraryName,
-      CFBundlePackageType: "FMWK",
-      CFBundleShortVersionString: "1.0",
-      CFBundleVersion: "1",
-      NSPrincipalClass: "",
-    }),
-    "utf8",
+    libraryName,
+    bundleIdentifier,
   );
   const newLibraryPath = path.join(frameworkPath, libraryName);
   // TODO: Consider copying the library instead of renaming it
   await fs.promises.rename(libraryPath, newLibraryPath);
-  // Update the name of the library
-  await spawn(
-    "install_name_tool",
-    ["-id", `@rpath/${libraryName}.framework/${libraryName}`, newLibraryPath],
-    {
-      outputMode: "buffered",
-    },
+  await updateLibraryInstallName(libraryName, libraryName, frameworkPath);
+  return frameworkPath;
+}
+
+/**
+ * Version identifier for the single version we create.
+ * Apple uses A, B, ... for major versions; we only ever create one version.
+ */
+const VERSIONED_FRAMEWORK_VERSION = "A";
+
+/**
+ * Creates a versioned .framework bundle (Versions/Current convention):
+ * MyFramework.framework/
+ *   MyFramework -> Versions/Current/MyFramework
+ *   Resources -> Versions/Current/Resources
+ *   Headers -> Versions/Current/Headers
+ *   Versions/
+ *     A/MyFramework, Resources/Info.plist, Headers/
+ *     Current -> A
+ * See: https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPFrameworks/Concepts/FrameworkAnatomy.html
+ */
+async function createVersionedFramework({
+  libraryPath,
+  frameworkPath,
+  libraryName,
+  bundleIdentifier,
+}: {
+  libraryPath: string;
+  frameworkPath: string;
+  libraryName: string;
+  bundleIdentifier?: string;
+}): Promise<string> {
+  const versionsDir = path.join(frameworkPath, "Versions");
+  const versionDir = path.join(versionsDir, VERSIONED_FRAMEWORK_VERSION);
+  const versionResourcesDir = path.join(versionDir, "Resources");
+  const versionHeadersDir = path.join(versionDir, "Headers");
+
+  await fs.promises.mkdir(versionResourcesDir, { recursive: true });
+  await fs.promises.mkdir(versionHeadersDir, { recursive: true });
+
+  await writeFrameworkInfoPlist(
+    path.join(versionResourcesDir, "Info.plist"),
+    libraryName,
+    bundleIdentifier,
+  );
+
+  const versionBinaryPath = path.join(versionDir, libraryName);
+  await fs.promises.rename(libraryPath, versionBinaryPath);
+  await updateLibraryInstallName(
+    path.join("Versions", VERSIONED_FRAMEWORK_VERSION, libraryName),
+    libraryName,
+    frameworkPath,
+  );
+
+  const currentLink = path.join(versionsDir, "Current");
+  await fs.promises.symlink(VERSIONED_FRAMEWORK_VERSION, currentLink);
+
+  await fs.promises.symlink(
+    "Versions/Current/Resources",
+    path.join(frameworkPath, "Resources"),
+  );
+  await fs.promises.symlink(
+    "Versions/Current/Headers",
+    path.join(frameworkPath, "Headers"),
   );
+  await fs.promises.symlink(
+    path.join("Versions", "Current", libraryName),
+    path.join(frameworkPath, libraryName),
+  );
+
   return frameworkPath;
 }
 
+export async function createAppleFramework({
+  libraryPath,
+  kind,
+  bundleIdentifier,
+}: CreateAppleFrameworkOptions) {
+  assert(fs.existsSync(libraryPath), `Library not found: ${libraryPath}`);
+  const libraryName = path.basename(libraryPath, path.extname(libraryPath));
+  const frameworkPath = path.join(
+    path.dirname(libraryPath),
+    `${libraryName}.framework`,
+  );
+  await fs.promises.rm(frameworkPath, { recursive: true, force: true });
+
+  if (kind === "versioned") {
+    return createVersionedFramework({
+      libraryPath,
+      frameworkPath,
+      libraryName,
+      bundleIdentifier,
+    });
+  } else if (kind === "flat") {
+    return createFlatFramework({
+      libraryPath,
+      frameworkPath,
+      libraryName,
+      bundleIdentifier,
+    });
+  } else {
+    throw new Error(`Unexpected framework kind: ${kind as string}`);
+  }
+}
+
 export async function createXCframework({
   frameworkPaths,
   outputPath,

Original file line number	Diff line number	Diff line change
`@@ -417,7 +417,7 @@ export const platform: Platform<Triplet[], AppleOpts> = {`
`417`	`417`	`const [artifact] = artifacts;`
`418`	`418`	`await createAppleFramework({`
`419`	`419`	`libraryPath: path.join(buildPath, artifact.path),`
`420`		`- versioned: triplet.endsWith("-darwin"),`
	`420`	`+ kind: triplet.endsWith("-darwin") ? "versioned" : "flat",`
`421`	`421`	`bundleIdentifier: appleBundleIdentifier,`
`422`	`422`	`});`
`423`	`423`	`}`