Add documentation for Cxx API snapshot generation (#56146)

Summary:
Pull Request resolved: https://github.com/facebook/react-native/pull/56146

Adds documentation for the cxx-api snapshot generation pipeline, covering usage commands for generating and checking snapshots, and configuration.

It answers:
1. What the script does.
2. What the output looks like.
3. How to use it (generate, check).
4. How it works (Doxygen → parser → .api files).
5. How it can be configured (config.yml).
6. What to do when snapshots differ.

Changelog:
[Internal]

Reviewed By: huntie

Differential Revision: D96316004

fbshipit-source-id: b527606b87efb2af72680b572135a5fc595ab85e
This commit is contained in:
Dawid Małecki authored and meta-codesync[bot] committed 2026-03-19 05:19:51 -07:00
1 parent 7ece7bd3a8
commit 25ef8444ef
1 file changed
+99
+99
View File
@@ -0,0 +1,99 @@
# 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](https://www.doxygen.nl/) 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:
```sh
python -m scripts.cxx-api.parser
```
#### Check 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:
```sh
python -m scripts.cxx-api.parser --check
```
If any snapshot differs, a unified diff is printed and the process exits with a non-zero status. To fix a failing check, 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.