Add stable public Debug C++ entry point (#58160)

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

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

Add `<React/Debug.h>` as the canonical public C++ entry point for React Native's debug assertion macros: `react_native_assert`, `react_native_expect`, and the `REACT_NATIVE_DEBUG` / `REACT_NATIVE_PRODUCTION` flags. Guard direct leaf-header inclusion for strict API consumers while preserving existing React Native builds and legacy include paths.

Classify the `redbox/` headers as private instead. They live in namespace `unstable_redbox`, have no consumers outside React Native, and are reachable only from three dev-menu `.mm` files, so they are fenced off with the private guard and deliberately left out of the umbrella.

Changelog:
[Internal]

Reviewed By: cipolleschi

Differential Revision: D116930195

fbshipit-source-id: 8942eed7fc41982dbf5ab4aa0d2466703db8a81e
This commit is contained in:
Jakub Piasecki authored and meta-codesync[bot] committed 2026-08-28 03:45:50 -07:00
1 parent 42a37214b6
commit 20d0605c9a
11 files changed
+79 -2

No files matched your search

@@ -144,6 +144,7 @@ val preparePrefab by
Pair("../ReactCommon/react/renderer/css/", "react/renderer/css/"),
// react_debug
Pair("../ReactCommon/react/debug/", "react/debug/"),
Pair("../ReactCommon/react/debug/React/", "React/"),
// react_renderer_debug
Pair("../ReactCommon/react/renderer/debug/", "react/renderer/debug/"),
// react_renderer_graphics
@@ -265,6 +266,7 @@ val preparePrefab by
Pair("../ReactCommon/react/renderer/telemetry/", "react/renderer/telemetry/"),
Pair("../ReactCommon/react/renderer/uimanager/", "react/renderer/uimanager/"),
Pair("../ReactCommon/react/debug/", "react/debug/"),
Pair("../ReactCommon/react/debug/React/", "React/"),
Pair("../ReactCommon/react/cxxstableapi/", "react/cxxstableapi/"),
Pair("../ReactCommon/react/utils/", "react/utils/"),
Pair("src/main/jni/react/jni", "react/jni/"),
@@ -14,7 +14,7 @@ add_library(react_debug OBJECT ${react_debug_SRC} ${react_debug_redbox_SRC})
target_include_directories(react_debug PUBLIC ${REACT_COMMON_DIR})
target_link_libraries(react_debug folly_runtime)
target_link_libraries(react_debug folly_runtime react_cxxstableapi)
if(ANDROID)
target_link_libraries(react_debug log)
@@ -16,6 +16,12 @@ else
source[:tag] = "v#{version}"
end
header_search_paths = []
if ENV['USE_FRAMEWORKS']
header_search_paths << "\"$(PODS_TARGET_SRCROOT)/../..\"" # ReactCommon, for <react/cxxstableapi/...>
end
Pod::Spec.new do |s|
s.name = "React-debug"
s.version = version
@@ -28,15 +34,24 @@ Pod::Spec.new do |s|
s.source_files = podspec_sources("*.{cpp,h}", "*.h")
s.header_dir = "react/debug"
s.pod_target_xcconfig = { "CLANG_CXX_LANGUAGE_STANDARD" => rct_cxx_language_standard(),
"DEFINES_MODULE" => "YES" }
"DEFINES_MODULE" => "YES",
"HEADER_SEARCH_PATHS" => header_search_paths.join(' ') }
resolve_use_frameworks(s, header_mappings_dir: "../..", module_name: "React_debug")
s.subspec "DebugUmbrella" do |ss|
ss.source_files = "React/*.h"
ss.header_dir = "React"
ss.header_mappings_dir = "React"
end
s.subspec "redbox" do |ss|
ss.source_files = podspec_sources("redbox/*.{cpp,h}", "redbox/*.h")
ss.exclude_files = "redbox/tests/**/*.{cpp,h}"
ss.header_dir = "react/debug/redbox"
end
s.dependency "React-cxxstableapi"
mark_as_react_native_build(s)
end
@@ -0,0 +1,31 @@
/*
* Copyright (c) Meta Platforms, Inc. and affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*/
#pragma once
// =============================================================================
// Umbrella header for the `react/debug` module - public entry point.
//
// #include <React/Debug.h>
//
// Re-exports the module's public interface headers. React Native's own code
// should keep using the fine-grained `<react/debug/...>` includes; only outside
// consumers use this umbrella.
//
// The `redbox/` headers are deliberately absent: they are implementation
// details of the dev-menu red box and carry no stability guarantee.
// =============================================================================
// Marks that the following headers are pulled in through the umbrella, so their
// shared guard (<react/cxxstableapi/UmbrellaGuard.h>) accepts them.
#define RN_UMBRELLA_CONTEXT
#include <react/debug/flags.h>
#include <react/debug/react_native_assert.h>
#include <react/debug/react_native_expect.h>
#undef RN_UMBRELLA_CONTEXT
@@ -7,6 +7,8 @@
#pragma once
#include <react/cxxstableapi/UmbrellaGuard.h>
//
// Preprocessor flags which control whether code meant for debugging the
// internals of React Native is included in the build. E.g. debug assertions.
@@ -20,6 +20,8 @@
#pragma once
#include <react/cxxstableapi/UmbrellaGuard.h>
#include "flags.h"
#undef react_native_assert
@@ -22,6 +22,8 @@
#pragma once
#include <react/cxxstableapi/UmbrellaGuard.h>
#include "flags.h"
#undef react_native_expect
@@ -7,6 +7,8 @@
#pragma once
#include <react/cxxstableapi/PrivateGuard.h>
#include <optional>
#include <string>
#include <vector>
@@ -7,6 +7,8 @@
#pragma once
#include <react/cxxstableapi/PrivateGuard.h>
#include <string>
#include <string_view>
@@ -7,6 +7,8 @@
#pragma once
#include <react/cxxstableapi/PrivateGuard.h>
#include <optional>
#include <string>
@@ -526,6 +526,23 @@ const PodspecExceptions /*: {[key: string]: PodSpecConfiguration} */ = {
},
],
},
'ReactCommon/react/debug/React-debug.podspec': {
name: 'React-debug',
headerPatterns: ['*.h'],
headerDir: 'react/debug',
subSpecs: [
{
name: 'DebugUmbrella',
headerPatterns: ['React/*.h'],
headerDir: 'React',
},
{
name: 'redbox',
headerPatterns: ['redbox/*.h'],
headerDir: 'react/debug/redbox',
},
],
},
'React-Core.podspec': {
name: 'React-Core',
headerPatterns: [],