Files
react-native/scripts/cxx-api
Alan Hughes 8aea8d9bad Fix StatusBar style and visibility on iOS 27 (#58926)
Summary:
Fixes https://github.com/react/react-native/issues/58758.
In apps built with the iOS 27 SDK, `StatusBar.setBarStyle` and `StatusBar.setHidden` do nothing. `RCTStatusBarManager` uses the `UIApplication` status bar setters, and UIKit turns them into no-ops for apps linked against the iOS 27 SDK. Apps built with the iOS 26 SDK are not affected. A plain UIKit app built with the iOS 27 SDK shows that with `UIViewControllerBasedStatusBarAppearance` set to `NO`, nothing can change the status bar on iOS 27. With `YES`, the view controller methods still work.

This change moves `StatusBar` to the view controller model. The module stores the requested style, hidden state, and animation in a new `RCTStatusBarAppearance` class and calls `setNeedsStatusBarAppearanceUpdate` on the presented view controller. The default root view controller from `RCTDefaultReactNativeFactoryDelegate` and the Fabric modal controller return those values. The modal keeps the status bar that was on screen when it opened until JS changes it, so a status bar set natively (ie by react-native-screens) is not lost. With `NO`, the module still calls the `UIApplication` setters, so apps built with older SDKs keep working. When React Native is built with the iOS 27 SDK and runs on iOS 27, it also logs one warning that tells the developer to set the key to `YES`.

Apps that override `createRootViewController` need their view controller to return the `RCTStatusBarAppearance` values for `StatusBar` to work on iOS 27.

A similar change, https://github.com/react/react-native/issues/25919, landed in March 2020 and was reverted the next day

[IOS] [FIXED] - `StatusBar` style and visibility work on iOS 27 for apps built with the iOS 27 SDK when `UIViewControllerBasedStatusBarAppearance` is `YES`. Custom root view controllers must return the `RCTStatusBarAppearance` values.

Pull Request resolved: https://github.com/react/react-native/pull/58926

Test Plan:
12 new XCTest cases in `RCTStatusBarAppearanceTests`. The OSS XCTest file has no internal BUCK owner and was not run locally.

Validation for the review update:
- Applied the explicit legacy-API guard to both `setStyle:animated:` and `setHidden:withAnimation:`. The appearance-state update remains unconditional; UIKit setters and warnings remain limited to apps using app-level status bar appearance.
- Meta-managed `clang-format` and `arc lint` passed for `RCTStatusBarManager.mm`.
- Built `ReactApple`, `CoreModulesApple`, `RCTFabricApple` and `RCTAppDelegateApple` for `iphonesimulator-arm64` with annotation checks enabled.
- No public headers changed, so API snapshots are unchanged.
- Diff-time CI will rerun for the updated code.

Reviewed By: javache

Differential Revision: D127555263

Pulled By: cipolleschi

fbshipit-source-id: 9a6d21236987e309917e620387b34e88e7da24c7
(cherry picked from commit bd08dafc98)
2026-10-26 16:01:49 +00:00
..

scripts/cxx-api

Python build pipeline for React Native's C++ (and Objective-C) API snapshots.

Overview

scripts/cxx-api generates human-readable snapshots of React Native's public C++ API surface. It uses Doxygen to parse C/C++/Objective-C headers and a custom Python parser to produce a simplified, sorted representation of every public symbol.

The pipeline produces one .api snapshot file per configured API view × variant combination:

Snapshot Description
ReactCommonDebugCxx.api Platform-independent C++ API (debug)
ReactCommonReleaseCxx.api Platform-independent C++ API (release)
ReactAndroidDebugCxx.api Android-specific C++ API (debug)
ReactAndroidReleaseCxx.api Android-specific C++ API (release)
ReactAppleDebugCxx.api Apple-specific C++/Obj-C API (debug)
ReactAppleReleaseCxx.api Apple-specific C++/Obj-C API (release)

For each view, debug and release variants are generated with different preprocessor definitions (e.g. REACT_NATIVE_DEBUG vs NDEBUG), since #ifdef guards in the source headers can produce a different public API surface per variant.

Snapshot files are committed to the repo under scripts/cxx-api/api-snapshots/.

Usage

Generate snapshots

Maintainers should run this command whenever making intentional C++ API changes:

python -m scripts.cxx-api.parser

Validate snapshots against committed baseline

This mode generates snapshots to a temporary directory and compares them against the committed .api files. It is designed for CI:

python -m scripts.cxx-api.parser --validate

If any snapshot differs, a unified diff is printed and the process exits with a non-zero status. To fix a failing validation, regenerate the snapshots with python -m scripts.cxx-api.parser and commit the updated .api files.

How it works

The pipeline has two main stages:

1. Doxygen XML generation

Doxygen is configured via a generated config file (built from .doxygen.config.template) with the input directories, exclude patterns, and preprocessor definitions specified in config.yml. It outputs XML describing every symbol found in the headers.

2. Snapshot parsing

The Python parser (parser/) reads the Doxygen XML output and builds a scope tree of the public API surface. The tree is then serialized to a deterministically sorted, human-readable .api text format.

When to use it

The snapshot should be regenerated whenever making intentional changes to the public C++ API surface. This includes additions, removals, and changes to files located in:

  • xplat/js/react-native-github/
  • xplat/js/react-native-github/ReactCommon/
  • xplat/js/react-native-github/ReactAndroid/
  • xplat/js/react-native-github/ReactApple/
  • xplat/js/react-native-github/Libraries/

Configuration

All API views and their variants are defined in config.yml. Each view specifies:

Field Description
inputs Directories to scan for headers
exclude_patterns Glob patterns for files to skip
definitions Preprocessor macros to define
variants Named build variants (e.g. debug/release) with extra definitions
codegen Optional codegen platform (android, ios) to generate TurboModule/Component headers before scanning
private_directories Directories whose headers are scanned (they may be transitively included) but should not contribute public symbols. If any public API entity is defined in a private directory, a warning is printed to help catch accidental API exposure.

Snapshot format

The .api files use a minimal pseudo-C++ syntax designed for easy diffing:

namespace facebook::react {
  class ComponentDescriptor {
    public ComponentDescriptor(ComponentDescriptorParameters params);
    public ComponentHandle getComponentHandle();
  }

  enum class AccessibilityRole {
    None = 0,
    Button = 1,
  }
}
  • Scopes and members are sorted alphabetically.
  • Access specifiers (public, protected) are preserved.
  • Template parameters are included.
  • Doc comments and source file names are stripped.