[ios][precompile] add support for clang virtual file system

To solve our problem with header files from the React.XCFramework not being consumable due to the legacy Cocoapods headers, we used to point all header search / resolving into the Pods/Headers folder when building even with the framework installed.

This is a problem since an xcframework expects a modular header structure that can be consumed from within the headers folder of the framework.

The headers are used for both Objective-c compiling and for creating clang modules that can be consumed by Swift in our setup.

This commit fixes the above issues and makes a modular clang virtual file system from the header files we distribute. This vfs-overlay file will then be used by the `rncore.rb` script when installing the 'React-Core-prebuilt' pod and map the header files requested in the source code to the actual location on disk where the React.xcframework headers are installed.

Here are the changes:

- Added vfs.js with types for creating clang virtual file system overlays
- Added resolving the paths in the vfs file to the actual install path
- Added installing the vfs overlay with the switch `-ivfsoverlay <path>` to compiler settings for both obj-c and swift on pod installation
- Add vfs targets to the app target on post install

Author: chrfalch

packages/react-native/scripts/cocoapods/rncore.rb

@@ -13,10 +13,26 @@
 ### building ReactNativeCore from source (then this function does nothing).
 def add_rncore_dependency(s)
     if !ReactNativeCoreUtils.build_rncore_from_source()
+        # Add the dependency
+        s.dependency "React-Core-prebuilt"
+
         current_pod_target_xcconfig = s.to_hash["pod_target_xcconfig"] || {}
         current_pod_target_xcconfig = current_pod_target_xcconfig.to_h unless current_pod_target_xcconfig.is_a?(Hash)
-        s.dependency "React-Core-prebuilt"
-        current_pod_target_xcconfig["HEADER_SEARCH_PATHS"] ||= [] << "$(PODS_ROOT)/React-Core-prebuilt/React.xcframework/Headers"
+
+        # Add VFS overlay flags for both Objective-C and Swift
+        # The VFS overlay file is pre-resolved at pod install time for each platform slice.
+        # We reference it directly in the xcframework using the React-VFS.yaml file that
+        # is written to the React-Core-prebuilt folder during setup_vfs_overlay.
+        vfs_overlay_flag = "-ivfsoverlay $(PODS_ROOT)/React-Core-prebuilt/React-VFS.yaml"
+        current_pod_target_xcconfig["OTHER_CFLAGS"] ||= "$(inherited)"
+        current_pod_target_xcconfig["OTHER_CFLAGS"] += " #{vfs_overlay_flag}"
+        current_pod_target_xcconfig["OTHER_CPLUSPLUSFLAGS"] ||= "$(inherited)"
+        current_pod_target_xcconfig["OTHER_CPLUSPLUSFLAGS"] += " #{vfs_overlay_flag}"
+        # For Swift, we need to use -Xcc to pass flags to the underlying Clang compiler
+        # Both the flag and its argument need separate -Xcc prefixes
+        current_pod_target_xcconfig["OTHER_SWIFT_FLAGS"] ||= "$(inherited)"
+        current_pod_target_xcconfig["OTHER_SWIFT_FLAGS"] += " -Xcc -ivfsoverlay -Xcc $(PODS_ROOT)/React-Core-prebuilt/React-VFS.yaml"
+
         s.pod_target_xcconfig = current_pod_target_xcconfig
     end
 end
@@ -450,4 +466,79 @@ def self.get_nightly_npm_version()
         return latest_nightly
     end
 
+    # Processes the VFS overlay file from the React.xcframework to resolve the ${ROOT_PATH} placeholder.
+    # This method should be called from react_native_post_install after pod install completes.
+    #
+    # The VFS overlay file maps header import paths to their actual locations within the xcframework.
+    # Since the xcframework contains platform-specific slices, we generate a resolved VFS file for each
+    # slice and also create a default VFS file that can be used immediately (before script phases run).
+    def self.process_vfs_overlay()
+        return if @@build_from_source
+
+        prebuilt_path = File.join(Pod::Config.instance.project_pods_root, "React-Core-prebuilt")
+        xcframework_path = File.join(prebuilt_path, "React.xcframework")
+        vfs_template_path = File.join(xcframework_path, "React-VFS-template.yaml")
+
+        unless File.exist?(vfs_template_path)
+            rncore_log("VFS overlay template not found at #{vfs_template_path}", :error)
+            exit 1
+        end
+
+        rncore_log("Processing VFS overlay file...")
+
+        # Read the template content
+        vfs_template_content = File.read(vfs_template_path)
+
+        # Write the VFS file - use the top-level xcframework path
+        # so that ${ROOT_PATH}/Headers points to the xcframework's Headers folder
+        resolved_vfs_content = vfs_template_content.gsub('${ROOT_PATH}', xcframework_path)
+        resolved_vfs_path = File.join(prebuilt_path, "React-VFS.yaml")
+        File.write(resolved_vfs_path, resolved_vfs_content)
+        rncore_log("  Created VFS overlay at #{resolved_vfs_path}")
+
+        rncore_log("VFS overlay setup complete")
+    end
+
+    # Configures the xcconfig files for aggregate (main app) targets to enable VFS overlay for React Native Core.
+    # This is needed because the main app target does not go through podspec processing,
+    # so it won't get the VFS overlay flags from add_rncore_dependency.
+    #
+    # Parameters:
+    # - installer: The CocoaPods installer object
+    def self.configure_aggregate_xcconfig(installer)
+        return if @@build_from_source
+
+        prebuilt_path = File.join(Pod::Config.instance.project_pods_root, "React-Core-prebuilt")
+        vfs_overlay_path = File.join(prebuilt_path, "React-VFS.yaml")
+
+        unless File.exist?(vfs_overlay_path)
+            rncore_log("VFS overlay not found at #{vfs_overlay_path}, skipping prebuilt xcconfig configuration", :error)
+            exit 1
+        end
+
+        rncore_log("Configuring xcconfig for prebuilt React Native Core...")
+
+        vfs_overlay_flag = " -ivfsoverlay \"#{vfs_overlay_path}\""
+        swift_vfs_overlay_flag = " -Xcc -ivfsoverlay -Xcc \"#{vfs_overlay_path}\""
+
+        # Add flags to aggregate target xcconfigs (these are used by the main app target)
+        installer.aggregate_targets.each do |aggregate_target|
+            aggregate_target.xcconfigs.each do |config_name, config_file|
+                # Add VFS overlay to compiler flags (C/C++ and Swift)
+                ReactNativePodsUtils.add_flag_to_map_with_inheritance(config_file.attributes, "OTHER_CFLAGS", vfs_overlay_flag)
+                ReactNativePodsUtils.add_flag_to_map_with_inheritance(config_file.attributes, "OTHER_CPLUSPLUSFLAGS", vfs_overlay_flag)
+
+                # For Swift, we need to use -Xcc to pass the flag to the underlying Clang compiler
+                ReactNativePodsUtils.add_flag_to_map_with_inheritance(config_file.attributes, "OTHER_SWIFT_FLAGS", swift_vfs_overlay_flag)
+
+                # Suppress incomplete umbrella warnings for the prebuilt frameworks (it is expected, as our umbrella headers do not include all headers)
+                ReactNativePodsUtils.add_flag_to_map_with_inheritance(config_file.attributes, "OTHER_SWIFT_FLAGS",  " -Xcc -Wno-incomplete-umbrella")
+
+                xcconfig_path = aggregate_target.xcconfig_path(config_name)
+                config_file.save_as(xcconfig_path)
+            end
+        end
+
+        rncore_log("Prebuilt xcconfig configuration complete")
+    end
 end

packages/react-native/scripts/ios-prebuild/types.js

@@ -22,6 +22,24 @@ export type Destination =
 export type BuildFlavor = 'Debug' | 'Release';
 
 export type MavenSubGroup = 'hermes' | 'react';
+
+export type VFSEntry = {
+  name: string,
+  type: 'file' | 'directory',
+  'external-contents'?: string,
+  contents?: Array<VFSEntry>,
+};
+
+export type VFSOverlay = {
+  version: number,
+  'case-sensitive': boolean,
+  roots: Array<VFSEntry>,
+};
+
+export type HeaderMapping = {
+  key: string,
+  path: string,
+};
 */
 
 module.exports = {};