From d513096133c6ee313dc025ea30b4a13ced9d7b6c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dawid=20Ma=C5=82ecki?= Date: Tue, 31 Mar 2026 08:32:57 -0700 Subject: [PATCH] Add `exclude_symbols` to the cxx-api parser config (#56240) Summary: Pull Request resolved: https://github.com/facebook/react-native/pull/56240 There are cases in which we want to strip particular symbols from the snapshot. This diff adds `exclude_symbols` to the parser config to enable definitions of symbol patterns that should be excluded from the snapshot. Changelog: [Internal] Reviewed By: cipolleschi Differential Revision: D98295409 fbshipit-source-id: 47414c1e5060a01dce76d1fc4fdd8ea355bb8d37 --- scripts/cxx-api/config.yml | 2 + scripts/cxx-api/parser/__main__.py | 6 +- scripts/cxx-api/parser/config.py | 4 ++ scripts/cxx-api/parser/main.py | 55 ++++++++++++++++-- scripts/cxx-api/tests/test_config.py | 87 ++++++++++++++++++++++++++++ 5 files changed, 148 insertions(+), 6 deletions(-) diff --git a/scripts/cxx-api/config.yml b/scripts/cxx-api/config.yml index aba88d8dacd..db9d429f2bb 100644 --- a/scripts/cxx-api/config.yml +++ b/scripts/cxx-api/config.yml @@ -4,6 +4,8 @@ exclude_patterns: - "*/test/*" - "*/stubs/*" +exclude_symbols: + platforms: ReactCommon: codegen: diff --git a/scripts/cxx-api/parser/__main__.py b/scripts/cxx-api/parser/__main__.py index 4d6e724b61b..d1aeef6a93c 100644 --- a/scripts/cxx-api/parser/__main__.py +++ b/scripts/cxx-api/parser/__main__.py @@ -89,6 +89,7 @@ def build_snapshot_for_view( verbose: bool = True, input_filter: str = None, work_dir: str | None = None, + exclude_symbols: list[str] | None = None, ) -> str: if verbose: print(f"[{api_view}] Generating API view") @@ -120,7 +121,9 @@ def build_snapshot_for_view( if verbose: print(f"[{api_view}] Building snapshot") - snapshot = build_snapshot(os.path.join(work_dir, "xml")) + snapshot = build_snapshot( + os.path.join(work_dir, "xml"), exclude_symbols=exclude_symbols + ) snapshot_string = snapshot.to_string() output_file = os.path.join(output_dir, f"{api_view}Cxx.api") @@ -185,6 +188,7 @@ def build_snapshots( verbose=verbose, input_filter=input_filter if config.input_filter else None, work_dir=work_dir, + exclude_symbols=config.exclude_symbols, ) futures[future] = config.snapshot_name diff --git a/scripts/cxx-api/parser/config.py b/scripts/cxx-api/parser/config.py index 9eab910ac28..9b351b968ba 100644 --- a/scripts/cxx-api/parser/config.py +++ b/scripts/cxx-api/parser/config.py @@ -38,6 +38,7 @@ class ApiViewSnapshotConfig: definitions: dict[str, str | int] codegen_platform: str | None = None input_filter: bool = False + exclude_symbols: list[str] = field(default_factory=list) def parse_config( @@ -60,6 +61,7 @@ def parse_config( Flattened list of ApiViewSnapshotConfig objects for all views and variants """ global_exclude_patterns: list[str] = raw_config.get("exclude_patterns") or [] + global_exclude_symbols: list[str] = raw_config.get("exclude_symbols") or [] platforms: dict = raw_config.get("platforms") or {} snapshot_configs = [] @@ -103,6 +105,7 @@ def parse_config( definitions=base_definitions, codegen_platform=codegen_platform, input_filter=input_filter, + exclude_symbols=global_exclude_symbols, ) ) else: @@ -117,6 +120,7 @@ def parse_config( definitions=merged_definitions, codegen_platform=codegen_platform, input_filter=input_filter, + exclude_symbols=global_exclude_symbols, ) ) diff --git a/scripts/cxx-api/parser/main.py b/scripts/cxx-api/parser/main.py index 082162b84b8..d5f629d7aa2 100644 --- a/scripts/cxx-api/parser/main.py +++ b/scripts/cxx-api/parser/main.py @@ -28,16 +28,32 @@ from .snapshot import Snapshot from .utils import has_scope_resolution_outside_angles, parse_qualified_path -def _process_namespace_sections(snapshot, namespace_scope, compound_object): +def _should_exclude_symbol(name: str, exclude_symbols: list[str]) -> bool: + """ + Check if a compound name should be excluded based on symbol patterns. + + Each pattern in exclude_symbols is treated as a substring match against + the compound's qualified name. + """ + return any(pattern in name for pattern in exclude_symbols) + + +def _process_namespace_sections( + snapshot, namespace_scope, compound_object, exclude_symbols: list[str] +): """ Process all section definitions inside a namespace compound. """ + compound_name = compound_object.compoundname for section_def in compound_object.sectiondef: if section_def.kind == "var": for variable_def in section_def.memberdef: # Skip out-of-class definitions (e.g. "Strct::VALUE") if has_scope_resolution_outside_angles(variable_def.get_name()): continue + qualified_name = f"{compound_name}::{variable_def.get_name()}" + if _should_exclude_symbol(qualified_name, exclude_symbols): + continue is_static = variable_def.static == "yes" namespace_scope.add_member( get_variable_member(variable_def, "public", is_static) @@ -47,6 +63,9 @@ def _process_namespace_sections(snapshot, namespace_scope, compound_object): # Skip out-of-class definitions (e.g. "Strct::convert") if has_scope_resolution_outside_angles(function_def.get_name()): continue + qualified_name = f"{compound_name}::{function_def.get_name()}" + if _should_exclude_symbol(qualified_name, exclude_symbols): + continue function_static = function_def.static == "yes" if not function_static: @@ -55,9 +74,15 @@ def _process_namespace_sections(snapshot, namespace_scope, compound_object): ) elif section_def.kind == "typedef": for typedef_def in section_def.memberdef: + qualified_name = f"{compound_name}::{typedef_def.get_name()}" + if _should_exclude_symbol(qualified_name, exclude_symbols): + continue namespace_scope.add_member(get_typedef_member(typedef_def, "public")) elif section_def.kind == "enum": for enum_def in section_def.memberdef: + qualified_name = f"{compound_name}::{enum_def.get_name()}" + if _should_exclude_symbol(qualified_name, exclude_symbols): + continue create_enum_scope(snapshot, enum_def) else: print( @@ -65,10 +90,13 @@ def _process_namespace_sections(snapshot, namespace_scope, compound_object): ) -def _handle_namespace_compound(snapshot, compound_object): +def _handle_namespace_compound(snapshot, compound_object, exclude_symbols=None): """ Handle a namespace compound definition. """ + if exclude_symbols is None: + exclude_symbols = [] + # Skip anonymous namespaces (internal linkage, not public API). # Doxygen encodes them with a '@' prefix in the compound name. if "@" in compound_object.compoundname: @@ -78,7 +106,9 @@ def _handle_namespace_compound(snapshot, compound_object): namespace_scope.location = compound_object.location.file - _process_namespace_sections(snapshot, namespace_scope, compound_object) + _process_namespace_sections( + snapshot, namespace_scope, compound_object, exclude_symbols + ) def _handle_concept_compound(snapshot, compound_object): @@ -140,10 +170,18 @@ _IGNORED_COMPOUNDS = frozenset( ) -def build_snapshot(xml_dir: str) -> Snapshot: +def build_snapshot(xml_dir: str, exclude_symbols: list[str] | None = None) -> Snapshot: """ Reads the Doxygen XML output and builds a snapshot of the C++ API. + + Args: + xml_dir: Path to the Doxygen XML output directory. + exclude_symbols: Optional list of substring patterns. Compounds whose + qualified name contains any of these patterns will be excluded. """ + if exclude_symbols is None: + exclude_symbols = [] + index_path = os.path.join(xml_dir, "index.xml") if not os.path.exists(index_path): raise RuntimeError(f"Doxygen entry point not found at {index_path}") @@ -163,12 +201,19 @@ def build_snapshot(xml_dir: str) -> Snapshot: if compound_object.prot == "private": continue + if _should_exclude_symbol(compound_object.compoundname, exclude_symbols): + continue + kind = compound_object.kind if kind in _IGNORED_COMPOUNDS: pass elif kind in _COMPOUND_HANDLERS: - _COMPOUND_HANDLERS[kind](snapshot, compound_object) + handler = _COMPOUND_HANDLERS[kind] + if handler == _handle_namespace_compound: + handler(snapshot, compound_object, exclude_symbols) + else: + handler(snapshot, compound_object) else: print(f"Unknown compound kind: {kind}") diff --git a/scripts/cxx-api/tests/test_config.py b/scripts/cxx-api/tests/test_config.py index 32a224e773d..c02ac412380 100644 --- a/scripts/cxx-api/tests/test_config.py +++ b/scripts/cxx-api/tests/test_config.py @@ -480,6 +480,93 @@ class TestParseConfig(unittest.TestCase): view_b = next(r for r in result if r.snapshot_name == "ViewB") self.assertEqual(view_b.exclude_patterns, ["*/test/*", "*/b_only/*"]) + # ========================================================================= + # Exclude symbols + # ========================================================================= + + def test_exclude_symbols_parsed(self): + """Global exclude_symbols are parsed and propagated""" + config = { + "exclude_symbols": ["Fantom", "::detail::"], + "platforms": { + "TestView": { + "inputs": [], + "definitions": {}, + } + }, + } + result = parse_config(config, "/base/dir") + + self.assertEqual(result[0].exclude_symbols, ["Fantom", "::detail::"]) + + def test_exclude_symbols_propagated_to_variants(self): + """Global exclude_symbols are propagated to all variant configs""" + config = { + "exclude_symbols": ["Fantom"], + "platforms": { + "TestView": { + "inputs": [], + "definitions": {}, + "variants": { + "debug": {"definitions": {"DEBUG": 1}}, + "release": {"definitions": {"NDEBUG": 1}}, + }, + } + }, + } + result = parse_config(config, "/base/dir") + + self.assertEqual(len(result), 2) + for r in result: + self.assertEqual(r.exclude_symbols, ["Fantom"]) + + def test_exclude_symbols_default_empty(self): + """Missing exclude_symbols defaults to empty list""" + config = { + "platforms": { + "TestView": { + "inputs": [], + "definitions": {}, + } + } + } + result = parse_config(config, "/base/dir") + + self.assertEqual(result[0].exclude_symbols, []) + + def test_exclude_symbols_none_treated_as_empty(self): + """None exclude_symbols treated as empty list""" + config = { + "exclude_symbols": None, + "platforms": { + "TestView": { + "inputs": [], + "definitions": {}, + } + }, + } + result = parse_config(config, "/base/dir") + + self.assertEqual(result[0].exclude_symbols, []) + + def test_exclude_symbols_applied_to_all_platforms(self): + """Global exclude_symbols apply to every platform""" + config = { + "exclude_symbols": ["Fantom"], + "platforms": { + "ViewA": { + "inputs": [], + }, + "ViewB": { + "inputs": [], + }, + }, + } + result = parse_config(config, "/base/dir") + + for r in result: + self.assertEqual(r.exclude_symbols, ["Fantom"]) + # ========================================================================= # Variant naming # =========================================================================