Add CocoaPods opt-in for RN_STRICT_API (#59037)

Summary:

Let iOS apps that use CocoaPods enforce React Native's C++ stable API. Setting `RCT_STRICT_CXX_API=1` before `pod install` defines `RN_STRICT_API` in the app project and the Pods project, so the `react/cxxstableapi` guards apply to the app, third-party pods and app codegen. React Native's own pods are unaffected because they define `RN_BUILDING`.

Under the flag, a direct include of a public module header is an error that points to the module's umbrella (`<React/<Module>.h>`), a private header is an error, and a "for frameworks" header is a warning that `RN_ALLOW_FRAMEWORKS` silences.

The flag is off by default: libraries that still include React Native's internal headers would stop compiling. Turning it back off removes the define on the next `pod install`. This mirrors the existing `RCT_REMOVE_LEGACY_*` opt-ins and matches the scope of the Android opt-in.

Changelog:
[iOS][Added] - Add `RCT_STRICT_CXX_API` CocoaPods opt-in to enforce React Native's C++ stable API in app and library native code

Differential Revision: D124979668

Author: coado

packages/react-native/scripts/cocoapods/__tests__/utils-test.rb

@@ -39,6 +39,8 @@ def teardown
         ENV['USE_FRAMEWORKS'] = nil
         ENV['RCT_REMOVE_LEGACY_MODULE_INTEROP'] = nil
         ENV['RCT_REMOVE_LEGACY_COMPONENT_INTEROP'] = nil
+        ENV['RCT_STRICT_CXX_API'] = nil
+        ENV['RCT_ALLOW_FRAMEWORKS'] = nil
         system_reset_commands
         $RN_PLATFORMS = nil
     end
@@ -613,6 +615,79 @@ def test_setLegacyInteropRemovalFlags_whenEnabledWithPrebuiltRNCore_warns
         assert(Pod::UI.collected_warns.first.include?("RCT_USE_PREBUILT_RNCORE=0"))
     end
 
+    # ==================================== #
+    # Test - Set strict C++ API flags      #
+    # ==================================== #
+
+    def strict_cxx_api_installer_mock(user_project_mock, pods_project_mock)
+        return InstallerMock.new(pods_project_mock, [AggregatedProjectMock.new(user_project_mock)])
+    end
+
+    def strict_cxx_api_pods_project_mock
+        return PodsProjectMock.new([], {"hermes-engine" => {}}, "test/path-pod.xcodeproj", [
+            BuildConfigurationMock.new("Debug"),
+            BuildConfigurationMock.new("Release"),
+        ])
+    end
+
+    def assert_strict_cxx_api_flags(project_mock, strict:, allow_frameworks:)
+        project_mock.build_configurations.each do |config|
+            ["OTHER_CFLAGS", "OTHER_CPLUSPLUSFLAGS"].each do |key|
+                setting = config.build_settings[key]
+                assert_equal(strict, setting.include?("-DRN_STRICT_API"))
+                assert_equal(allow_frameworks, setting.include?("-DRN_ALLOW_FRAMEWORKS"))
+            end
+        end
+    end
+
+    def run_set_strict_cxx_api_flags
+        user_project_mock = prepare_empty_user_project_mock()
+        pods_project_mock = strict_cxx_api_pods_project_mock()
+        ReactNativePodsUtils.set_strict_cxx_api_flags(
+            strict_cxx_api_installer_mock(user_project_mock, pods_project_mock)
+        )
+        return [user_project_mock, pods_project_mock]
+    end
+
+    def test_setStrictCxxApiFlags_whenUnset_addsNothing
+        run_set_strict_cxx_api_flags().each do |project_mock|
+            assert_strict_cxx_api_flags(project_mock, strict: false, allow_frameworks: false)
+        end
+    end
+
+    def test_setStrictCxxApiFlags_whenStrictEnabled_addsRnStrictApiToUserAndPodsProjects
+        ENV['RCT_STRICT_CXX_API'] = '1'
+        run_set_strict_cxx_api_flags().each do |project_mock|
+            assert_strict_cxx_api_flags(project_mock, strict: true, allow_frameworks: false)
+        end
+    end
+
+    def test_setStrictCxxApiFlags_whenAllowFrameworksEnabled_addsRnAllowFrameworksToUserAndPodsProjects
+        ENV['RCT_ALLOW_FRAMEWORKS'] = '1'
+        run_set_strict_cxx_api_flags().each do |project_mock|
+            assert_strict_cxx_api_flags(project_mock, strict: false, allow_frameworks: true)
+        end
+    end
+
+    def test_setStrictCxxApiFlags_whenDisabled_removesPreviouslyAddedFlags
+        # Arrange
+        ENV['RCT_STRICT_CXX_API'] = '1'
+        ENV['RCT_ALLOW_FRAMEWORKS'] = '1'
+        user_project_mock = prepare_empty_user_project_mock()
+        pods_project_mock = strict_cxx_api_pods_project_mock()
+        installer = strict_cxx_api_installer_mock(user_project_mock, pods_project_mock)
+        ReactNativePodsUtils.set_strict_cxx_api_flags(installer)
+
+        # Act
+        ENV['RCT_STRICT_CXX_API'] = '0'
+        ENV['RCT_ALLOW_FRAMEWORKS'] = '0'
+        ReactNativePodsUtils.set_strict_cxx_api_flags(installer)
+
+        # Assert
+        assert_strict_cxx_api_flags(user_project_mock, strict: false, allow_frameworks: false)
+        assert_strict_cxx_api_flags(pods_project_mock, strict: false, allow_frameworks: false)
+    end
+
     # ==================================== #
     # Test - Set build setting             #
     # ==================================== #

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

@@ -24,6 +24,14 @@ class ReactNativePodsUtils
         'RCT_REMOVE_LEGACY_COMPONENT_INTEROP',
     ]
 
+    # Opt-in C++ stable API settings, each env var mapped to the macro it defines.
+    # RN_STRICT_API arms the react/cxxstableapi guards; RN_ALLOW_FRAMEWORKS
+    # silences their "for frameworks" warning.
+    STRICT_CXX_API_FLAGS = {
+        'RCT_STRICT_CXX_API' => 'RN_STRICT_API',
+        'RCT_ALLOW_FRAMEWORKS' => 'RN_ALLOW_FRAMEWORKS',
+    }
+
     # URI::File.build validates path components as ASCII, so escape the filesystem path first.
     def self.local_file_uri(path)
         URI::File.build(path: URI::DEFAULT_PARSER.escape(path)).to_s
@@ -598,6 +606,19 @@ def self.set_legacy_interop_removal_flags(installer, build_rncore_from_source:)
         end
     end
 
+    # The macros reach every target that inherits the project settings: the app,
+    # third-party pods and app codegen. React Native's own pods define RN_BUILDING,
+    # which keeps the guards inert for them.
+    def self.set_strict_cxx_api_flags(installer)
+        STRICT_CXX_API_FLAGS.each do |env_var, macro|
+            if ENV[env_var] == '1'
+                self.add_compiler_flag_to_project(installer, "-D#{macro}")
+            else
+                self.remove_compiler_flag_from_project(installer, "-D#{macro}")
+            end
+        end
+    end
+
     def self.add_compiler_flag_to_pods(installer, flag, configuration: nil)
         installer.target_installation_results.pod_target_installation_results.each do |pod_name, target_installation_result|
             target_installation_result.native_target.build_configurations.each do |config|

packages/react-native/scripts/codegen/__tests__/__snapshots__/generate-artifacts-executor-test.js.snap

@@ -103,7 +103,9 @@ Pod::Spec.new do |s|
   # This guard prevent to install the dependencies when we run \`pod install\` in the old architecture.
   s.pod_target_xcconfig    = {
     \\"CLANG_CXX_LANGUAGE_STANDARD\\" => rct_cxx_language_standard(),
-    \\"DEFINES_MODULE\\" => \\"YES\\"
+    \\"DEFINES_MODULE\\" => \\"YES\\",
+    # Generated code: see ReactCodegen.podspec.
+    \\"GCC_PREPROCESSOR_DEFINITIONS\\" => \\"$(inherited) RN_ALLOW_FRAMEWORKS=1\\"
   }
 
   s.dependency \\"ReactCodegen\\"
@@ -458,7 +460,10 @@ Pod::Spec.new do |s|
   s.pod_target_xcconfig = {
     \\"HEADER_SEARCH_PATHS\\" => header_search_paths.join(' '),
     \\"FRAMEWORK_SEARCH_PATHS\\" => framework_search_paths,
-    \\"OTHER_CPLUSPLUSFLAGS\\" => \\"$(inherited) #{folly_compiler_flags} #{boost_compiler_flags}\\"
+    \\"OTHER_CPLUSPLUSFLAGS\\" => \\"$(inherited) #{folly_compiler_flags} #{boost_compiler_flags}\\",
+    # Generated code: nobody can act on a C++ stable API \\"for frameworks\\" warning
+    # here. Libraries are held to the API in their own pods.
+    \\"GCC_PREPROCESSOR_DEFINITIONS\\" => \\"$(inherited) RN_ALLOW_FRAMEWORKS=1\\"
   }
 
   s.dependency \\"React-jsiexecutor\\"
@@ -615,7 +620,9 @@ Pod::Spec.new do |s|
   # This guard prevent to install the dependencies when we run \`pod install\` in the old architecture.
   s.pod_target_xcconfig    = {
     \\"CLANG_CXX_LANGUAGE_STANDARD\\" => rct_cxx_language_standard(),
-    \\"DEFINES_MODULE\\" => \\"YES\\"
+    \\"DEFINES_MODULE\\" => \\"YES\\",
+    # Generated code: see ReactCodegen.podspec.
+    \\"GCC_PREPROCESSOR_DEFINITIONS\\" => \\"$(inherited) RN_ALLOW_FRAMEWORKS=1\\"
   }
 
   s.dependency \\"ReactCodegen\\"
@@ -942,7 +949,10 @@ Pod::Spec.new do |s|
   s.pod_target_xcconfig = {
     \\"HEADER_SEARCH_PATHS\\" => header_search_paths.join(' '),
     \\"FRAMEWORK_SEARCH_PATHS\\" => framework_search_paths,
-    \\"OTHER_CPLUSPLUSFLAGS\\" => \\"$(inherited) #{folly_compiler_flags} #{boost_compiler_flags}\\"
+    \\"OTHER_CPLUSPLUSFLAGS\\" => \\"$(inherited) #{folly_compiler_flags} #{boost_compiler_flags}\\",
+    # Generated code: nobody can act on a C++ stable API \\"for frameworks\\" warning
+    # here. Libraries are held to the API in their own pods.
+    \\"GCC_PREPROCESSOR_DEFINITIONS\\" => \\"$(inherited) RN_ALLOW_FRAMEWORKS=1\\"
   }
 
   s.dependency \\"React-jsiexecutor\\"

packages/react-native/scripts/codegen/templates/ReactAppDependencyProvider.podspec.template

@@ -27,7 +27,9 @@ Pod::Spec.new do |s|
   # This guard prevent to install the dependencies when we run `pod install` in the old architecture.
   s.pod_target_xcconfig    = {
     "CLANG_CXX_LANGUAGE_STANDARD" => rct_cxx_language_standard(),
-    "DEFINES_MODULE" => "YES"
+    "DEFINES_MODULE" => "YES",
+    # Generated code: see ReactCodegen.podspec.
+    "GCC_PREPROCESSOR_DEFINITIONS" => "$(inherited) RN_ALLOW_FRAMEWORKS=1"
   }
 
   s.dependency "ReactCodegen"

packages/react-native/scripts/codegen/templates/ReactCodegen.podspec.template

@@ -62,7 +62,10 @@ Pod::Spec.new do |s|
   s.pod_target_xcconfig = {
     "HEADER_SEARCH_PATHS" => header_search_paths.join(' '),
     "FRAMEWORK_SEARCH_PATHS" => framework_search_paths,
-    "OTHER_CPLUSPLUSFLAGS" => "$(inherited) #{folly_compiler_flags} #{boost_compiler_flags}"
+    "OTHER_CPLUSPLUSFLAGS" => "$(inherited) #{folly_compiler_flags} #{boost_compiler_flags}",
+    # Generated code: nobody can act on a C++ stable API "for frameworks" warning
+    # here. Libraries are held to the API in their own pods.
+    "GCC_PREPROCESSOR_DEFINITIONS" => "$(inherited) RN_ALLOW_FRAMEWORKS=1"
   }
 
   s.dependency "React-jsiexecutor"

packages/react-native/scripts/react_native_pods.rb

@@ -122,6 +122,12 @@ def use_react_native! (
   # layers are still supported. Both will default to 1 in a future React Native release.
   ENV['RCT_REMOVE_LEGACY_MODULE_INTEROP'] = ENV['RCT_REMOVE_LEGACY_MODULE_INTEROP'] == '1' ? '1' : '0'
   ENV['RCT_REMOVE_LEGACY_COMPONENT_INTEROP'] = ENV['RCT_REMOVE_LEGACY_COMPONENT_INTEROP'] == '1' ? '1' : '0'
+  # Enforcing the C++ stable API is opt-in: third-party libraries that still include
+  # React Native's internal headers would stop compiling.
+  ENV['RCT_STRICT_CXX_API'] = ENV['RCT_STRICT_CXX_API'] == '1' ? '1' : '0'
+  # Silences the stable API's "for frameworks" warning in the app, and in libraries that
+  # use those headers without declaring RN_ALLOW_FRAMEWORKS themselves.
+  ENV['RCT_ALLOW_FRAMEWORKS'] = ENV['RCT_ALLOW_FRAMEWORKS'] == '1' ? '1' : '0'
 
   ReactNativePodsUtils.check_minimum_required_xcode()
 
@@ -631,6 +637,8 @@ def react_native_post_install(
     build_rncore_from_source: ReactNativeCoreUtils.build_rncore_from_source()
   )
 
+  ReactNativePodsUtils.set_strict_cxx_api_flags(installer)
+
   ReactNativePodsUtils.set_ccache_compiler_and_linker_build_settings(installer, react_native_path, ccache_enabled)
   ReactNativePodsUtils.updateOSDeploymentTarget(installer)
   ReactNativePodsUtils.set_dynamic_frameworks_flags(installer)