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
This commit is contained in:
Dawid Małecki authored and meta-codesync[bot] committed 2026-03-31 08:32:57 -07:00
1 parent 9bc2050a79
commit d513096133
5 files changed
+148 -6

No files matched your search

+2
View File
@@ -4,6 +4,8 @@ exclude_patterns:
- "*/test/*"
- "*/stubs/*"
exclude_symbols:
platforms:
ReactCommon:
codegen:
+5 -1
View File
@@ -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
+4
View File
@@ -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,
)
)
+50 -5
View File
@@ -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<T>::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<T>::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}")
+87
View File
@@ -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
# =========================================================================