From 566c7ac2d1722a4be33f3618cf53b00088ca14ca Mon Sep 17 00:00:00 2001 From: artus9033 Date: Mon, 20 Jul 2026 05:01:24 -0700 Subject: [PATCH] fix: stabilize CXX API generator on MacOS, make parser indempotent for nested enums (#57536) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Summary: Fixes C++ API snapshot generation failures for nested enums and macOS/Linux output drift due to platform-dependent behavior, in the CXX API generator. ### Problems 1. Duplicate enums: Doxygen parses codegen `EventEmitters.h` twice (direct codegen input + again via `.mm` includes). The parser raised `RuntimeError: Identifier OnOrientationChangeOrientation already exists in scope ModalHostViewEventEmitter` on `ReactApple*` views. 2. Inconsistent behaviour on MacOS vs Linux: - for codegen component aliases (`ConcreteComponentDescriptor`, `ConcreteViewShadowNode`), macOS Doxygen emits hybrid XML definitions (`typedef Type Name = Type`) while Linux CI emits `using Name = Type`. The parser keyed off `definition.startswith("typedef")`, so identical source produced different `.api` output per platform. - `CASE_SENSE_NAMES = SYSTEM` follows the host OS default (case-insensitive on macOS, case-sensitive on Linux), causing inconsistent symbol resolution. ### Resolution - `.doxygen.config.template` files: set `CASE_SENSE_NAMES = YES` for deterministic name matching across macOS and Linux. - `snapshot.py`: `create_enum()` returns an existing enum scope instead of raising when the enum is already registered. - `builders.py`: `create_enum_scope()` to skip enums that already exist; `get_typedef_member()` to normalize Doxygen’s `typedef ... = ...` form to `using` so the output format is unified. ## Changelog: [INTERNAL] [FIXED] - Fix C++ API snapshot generation crash on duplicate codegen enums [INTERNAL] [FIXED] - Fix platform-dependent inconsistent CXX API generator output Pull Request resolved: https://github.com/react/react-native/pull/57536 Test Plan: - [x] `yarn cxx-api-build` completes on macOS (tested locally) - [x] `yarn cxx-api-validate` passes (tested locally on MacOS & on the Linux CI) - [x] `validate-cxx-api-snapshots` passes on Linux (tested on CI) Reviewed By: j-piasecki Differential Revision: D112793182 Pulled By: coado fbshipit-source-id: ada818451fb1207d965c1bed4fb5ce23ee2fe00f --- .../react-native/.doxygen.config.template | 2 +- .../manual_test/.doxygen.config.template | 2 +- scripts/cxx-api/parser/builders.py | 25 ++++++++++++++++++- scripts/cxx-api/parser/snapshot.py | 2 ++ .../tests/snapshots/.doxygen.config.template | 2 +- 5 files changed, 29 insertions(+), 4 deletions(-) diff --git a/packages/react-native/.doxygen.config.template b/packages/react-native/.doxygen.config.template index f06eeddd9b5..03e2e697a52 100644 --- a/packages/react-native/.doxygen.config.template +++ b/packages/react-native/.doxygen.config.template @@ -653,7 +653,7 @@ INTERNAL_DOCS = NO # Possible values are: SYSTEM, NO and YES. # The default value is: SYSTEM. -CASE_SENSE_NAMES = SYSTEM +CASE_SENSE_NAMES = YES # If the HIDE_SCOPE_NAMES tag is set to NO then Doxygen will show members with # their full class and namespace scopes in the documentation. If set to YES, the diff --git a/scripts/cxx-api/manual_test/.doxygen.config.template b/scripts/cxx-api/manual_test/.doxygen.config.template index c8e1f2a82f0..4e46ff45e8a 100644 --- a/scripts/cxx-api/manual_test/.doxygen.config.template +++ b/scripts/cxx-api/manual_test/.doxygen.config.template @@ -653,7 +653,7 @@ INTERNAL_DOCS = NO # Possible values are: SYSTEM, NO and YES. # The default value is: SYSTEM. -CASE_SENSE_NAMES = SYSTEM +CASE_SENSE_NAMES = YES # If the HIDE_SCOPE_NAMES tag is set to NO then Doxygen will show members with # their full class and namespace scopes in the documentation. If set to YES, the diff --git a/scripts/cxx-api/parser/builders.py b/scripts/cxx-api/parser/builders.py index f217e594d2e..862c91eaaf6 100644 --- a/scripts/cxx-api/parser/builders.py +++ b/scripts/cxx-api/parser/builders.py @@ -28,6 +28,7 @@ from .member import ( TypedefMember, VariableMember, ) +from .member.base import is_function_pointer_argstring from .scope import InterfaceScopeKind, ProtocolScopeKind, StructLikeScopeKind from .snapshot import Snapshot from .template import Template @@ -460,7 +461,21 @@ def get_typedef_member( typedef_keyword = "using" if typedef_definition.startswith("typedef"): - typedef_keyword = "typedef" + # Doxygen's "combining using relations" pass can emit hybrid definitions + # like "typedef Type Name = Type" for using-declarations on macOS, while + # Linux builds report "using Name = Type". Normalise the hybrid form for + # codegen component aliases so snapshots are stable across platforms. + if ( + "=" in typedef_definition + and not is_function_pointer_argstring(typedef_argstring) + and ( + "ConcreteComponentDescriptor" in typedef_definition + or "ConcreteViewShadowNode" in typedef_definition + ) + ): + typedef_keyword = "using" + else: + typedef_keyword = "typedef" typedef = TypedefMember( typedef_name, @@ -605,6 +620,14 @@ def create_enum_scope(snapshot: Snapshot, enum_def: compound.EnumdefType) -> Non """ Create an enum scope in the snapshot. """ + path = parse_qualified_path(enum_def.qualifiedname) + parent_scope = snapshot.ensure_scope(path[0:-1]) + enum_name = path[-1] + if enum_name in parent_scope.inner_scopes: + existing = parent_scope.inner_scopes[enum_name] + if existing.kind.name == "enum": + return + scope = snapshot.create_enum(enum_def.qualifiedname) scope.kind.type = resolve_linked_text_name(enum_def.get_type())[0] scope.location = enum_def.location.file diff --git a/scripts/cxx-api/parser/snapshot.py b/scripts/cxx-api/parser/snapshot.py index eca55a0bcb2..2e854f3ac82 100644 --- a/scripts/cxx-api/parser/snapshot.py +++ b/scripts/cxx-api/parser/snapshot.py @@ -184,6 +184,8 @@ class Snapshot: scope = current_scope.inner_scopes[enum_name] if scope.kind.name == "temporary": scope.kind = EnumScopeKind() + elif scope.kind.name == "enum": + return scope else: raise RuntimeError( f"Identifier {enum_name} already exists in scope {current_scope.name}" diff --git a/scripts/cxx-api/tests/snapshots/.doxygen.config.template b/scripts/cxx-api/tests/snapshots/.doxygen.config.template index 00ae22eb9d2..057e757e174 100644 --- a/scripts/cxx-api/tests/snapshots/.doxygen.config.template +++ b/scripts/cxx-api/tests/snapshots/.doxygen.config.template @@ -653,7 +653,7 @@ INTERNAL_DOCS = NO # Possible values are: SYSTEM, NO and YES. # The default value is: SYSTEM. -CASE_SENSE_NAMES = SYSTEM +CASE_SENSE_NAMES = YES # If the HIDE_SCOPE_NAMES tag is set to NO then Doxygen will show members with # their full class and namespace scopes in the documentation. If set to YES, the