diff --git a/packages/react-native/scripts/ios-prebuild/__docs__/headers-rules.md b/packages/react-native/scripts/ios-prebuild/__docs__/headers-rules.md index ed27ae500e25..baa0c3700042 100644 --- a/packages/react-native/scripts/ios-prebuild/__docs__/headers-rules.md +++ b/packages/react-native/scripts/ios-prebuild/__docs__/headers-rules.md @@ -234,27 +234,28 @@ emitted as a one-line redirect shim (`#import `). Shims that are namespace-module members are fine: they import the owning module, so declarations stay single-owned. -**R12 — a namespace module's own umbrella stays in ReactNativeHeaders.** The C++ -stable API ships one umbrella per module, physically nested inside it -(`ReactCommon/react/debug/React/Debug.h`), so its natural path is -`React/Debug.h` and R1 would hoist it into the framework. It must not be: -**ReactNativeHeaders is the lower layer** — `React.framework` imports it -(`RCTCallInvoker.h` → ``). A framework-owned umbrella -makes every `#include ` inside a lowercase-namespace header an import -of module `React`, closing a cycle: +**R12 — a namespace module's own umbrella is an `exclude header` of module +`React`.** The C++ stable API ships one umbrella per module, physically nested +inside it (`ReactCommon/react/debug/React/Debug.h`), so its natural path is +`React/Debug.h` and R1 hoists it into the framework. **ReactNativeHeaders is the +lower layer** — `React.framework` imports it (`RCTCallInvoker.h` → +``). A framework header that belongs to module +`React` makes every `#include ` inside a lowercase-namespace header +an import of module `React`, closing a cycle: ```text React -> ReactNativeHeaders_react -> React ``` -Found empirically: `react/timing/primitives.h` -> ``. This is the -same two-module-ownership failure as `UMBRELLA_CXX_GUARDED_EXCLUSIONS` -(`RCTFrameTimingsObserver.h`, which reaches the same `primitives.h`), in the -opposite direction. They are `objc-blocked` by construction (they re-export -their module's C++ surface), so they were never R4 umbrella or R5 module -members; `planFromInventory` fails closed if one ever becomes a modular -candidate, since its R5 module would be named `React` and alias the framework -module. +Found empirically: `react/timing/primitives.h` -> ``. The React +module map therefore lists each of these umbrellas as `exclude header`, so it is +included textually and creates no module edge. They cannot ship in +ReactNativeHeaders instead: a `React/` dir next to `react/` in one `Headers/` +root merges with it on a case-insensitive filesystem, and every `` +include then warns with `-Wnonportable-include-path` (or does not resolve on a +case-sensitive one). `planFromInventory` fails closed if one ever becomes a +modular candidate, since it would then join the umbrella and bring the cycle +back. ## Stage 3 — Emission (headers-compose.js) diff --git a/packages/react-native/scripts/ios-prebuild/__tests__/framework-resources-test.js b/packages/react-native/scripts/ios-prebuild/__tests__/framework-resources-test.js index 70b97d5d1290..410242d95dca 100644 --- a/packages/react-native/scripts/ios-prebuild/__tests__/framework-resources-test.js +++ b/packages/react-native/scripts/ios-prebuild/__tests__/framework-resources-test.js @@ -352,6 +352,7 @@ describe('emitReactFrameworkHeaders resource landing (integration)', () => { react: [], umbrella: [], privateReactHeaders: {modular: [], textual: []}, + excludedReactHeaders: [], }, rnRoot, ); diff --git a/packages/react-native/scripts/ios-prebuild/__tests__/headers-spec-test.js b/packages/react-native/scripts/ios-prebuild/__tests__/headers-spec-test.js index e4a9eba55694..575089be4027 100644 --- a/packages/react-native/scripts/ios-prebuild/__tests__/headers-spec-test.js +++ b/packages/react-native/scripts/ios-prebuild/__tests__/headers-spec-test.js @@ -370,8 +370,8 @@ describe('R11 redirect shims for dual-identity headers', () => { }); }); -describe('R12 namespace module umbrellas stay in ReactNativeHeaders', () => { - test('a module-nested React/ umbrella is not hoisted into the framework', () => { +describe('R12 namespace module umbrellas are excluded from the React module', () => { + test('a module-nested React/ umbrella ships in the framework as `exclude header`', () => { const m = validManifest(); m.headers.push( entry( @@ -381,17 +381,17 @@ describe('R12 namespace module umbrellas stay in ReactNativeHeaders', () => { ), ); const plan = planFromInventoryForTest(m); - // Lower layer: including it from a react/-namespace header cannot create a - // React module edge (React -> ReactNativeHeaders_react -> React). expect( - plan.reactNativeHeaders.find(e => e.naturalPath === 'React/Debug.h') - ?.relPath, - ).toBe('React/Debug.h'); + plan.react.find(e => e.naturalPath === 'React/Debug.h')?.relPath, + ).toBe('Debug.h'); expect( - plan.react.find(e => e.naturalPath === 'React/Debug.h'), - ).toBeUndefined(); + plan.reactNativeHeaders.some(e => e.relPath.startsWith('React/')), + ).toBe(false); expect(plan.umbrella).not.toContain('React/Debug.h'); - expect(Object.keys(plan.namespaceModules)).not.toContain('React'); + expect(plan.excludedReactHeaders).toEqual(['Debug.h']); + expect( + renderReactModuleMap(plan.privateReactHeaders, plan.excludedReactHeaders), + ).toContain(' exclude header "Debug.h"'); }); test('genuine React.framework headers are still hoisted (R1)', () => { diff --git a/packages/react-native/scripts/ios-prebuild/headers-compose.js b/packages/react-native/scripts/ios-prebuild/headers-compose.js index 426d8b45b1e7..20d813b48f7b 100644 --- a/packages/react-native/scripts/ios-prebuild/headers-compose.js +++ b/packages/react-native/scripts/ios-prebuild/headers-compose.js @@ -211,7 +211,7 @@ function emitReactFrameworkHeaders( fs.mkdirSync(path.join(fwk, 'Modules'), {recursive: true}); fs.writeFileSync( path.join(fwk, 'Modules', 'module.modulemap'), - renderReactModuleMap(plan.privateReactHeaders), + renderReactModuleMap(plan.privateReactHeaders, plan.excludedReactHeaders), ); if (privacyManifest != null) { fs.writeFileSync( diff --git a/packages/react-native/scripts/ios-prebuild/headers-spec.js b/packages/react-native/scripts/ios-prebuild/headers-spec.js index 5b24e11eb394..52310c093e27 100644 --- a/packages/react-native/scripts/ios-prebuild/headers-spec.js +++ b/packages/react-native/scripts/ios-prebuild/headers-spec.js @@ -79,19 +79,17 @@ * module members are fine: they import the owning module, so declarations * stay single-owned. * R12. A namespace module's OWN umbrella (ReactCommon//React/.h, - * natural path React/.h) ships in ReactNativeHeaders — it is NOT - * hoisted into React.framework by R1. ReactNativeHeaders is the LOWER - * layer (React.framework imports it: RCTCallInvoker.h pulls + * natural path React/.h) is hoisted into React.framework by R1, but + * declared `exclude header` in the React module map. ReactNativeHeaders + * is the LOWER layer (React.framework imports it: RCTCallInvoker.h pulls * ), so a framework-owned umbrella turns every * `#include ` inside a lowercase-namespace header into an import * of module React and closes a cycle: * React -> ReactNativeHeaders_react -> React - * Found empirically: react/timing/primitives.h -> . Kept in - * ReactNativeHeaders the same spelling still resolves — framework lookup - * misses and clang falls back to the header search path — textually and - * within one artifact, so no module edge is created. These umbrellas are - * objc-blocked by construction (they re-export their module's C++ - * surface), so they were never R4 umbrella or R5 module members anyway. + * Found empirically: react/timing/primitives.h -> . An + * excluded header is included textually, so no module edge is created. + * It cannot ship in ReactNativeHeaders instead: a `React/` dir next to + * `react/` merges with it on a case-insensitive filesystem. * R13. The C++ stable API guards (react/cxxstableapi/*Guard.h) are * `textual header` members of their R5 module, as is every R5 member that * reaches one through unguarded includes. A guard decides at each @@ -139,6 +137,8 @@ export type HeadersSpecPlan = { namespaceUmbrellas: Array<{relPath: string, content: string}>, // R9: private headers added to the React module map (allowlist). privateReactHeaders: {modular: Array, textual: Array}, + // R12: React.framework headers declared `exclude header`. + excludedReactHeaders: Array, collisions: Array, }; */ @@ -362,6 +362,7 @@ function planFromInventory( const react /*: Array */ = []; const reactNativeHeaders /*: Array */ = []; const umbrella /*: Array */ = []; + const excludedReactHeaders /*: Array */ = []; const namespaceModules /*: {[string]: Array} */ = {}; const textualNamespaceHeaders /*: Array */ = []; const guardedHeaders = stableApiGuardedHeaders(manifest); @@ -374,13 +375,7 @@ function planFromInventory( let bucketKey; let entryList; let relPath; - if (np.startsWith('React/') && NS_MODULE_UMBRELLA_RE.test(source)) { - // R12: a namespace module's own umbrella stays in the LOWER layer, so - // including it from that namespace cannot create a React module edge. - relPath = np; - bucketKey = `ReactNativeHeaders/${relPath}`; - entryList = reactNativeHeaders; - } else if (np.startsWith('React/')) { + if (np.startsWith('React/')) { relPath = np.slice(6); // R1: hoist React/ to the framework Headers root bucketKey = `React.framework/${relPath}`; entryList = react; @@ -405,13 +400,18 @@ function planFromInventory( seen.set(bucketKey, source); entryList.push({relPath, source, naturalPath: np}); - // R4: React umbrella membership. Only headers the framework actually ships - // (R12 umbrellas carry a React/ natural path but live in ReactNativeHeaders). - if ( - entryList === react && - np.startsWith('React/') && - isUmbrellaSafe(h, root) - ) { + if (np.startsWith('React/') && NS_MODULE_UMBRELLA_RE.test(source)) { + // R12: fail closed, an umbrella member would bring the cycle back. + if (isUmbrellaSafe(h, root)) { + throw new Error( + `R12: '${np}' is a modular candidate. As a React module member it ` + + `would close the React -> ReactNativeHeaders_react -> React ` + + `cycle. Keep it out of the modular surface.`, + ); + } + excludedReactHeaders.push(relPath); + } else if (np.startsWith('React/') && isUmbrellaSafe(h, root)) { + // R4: React umbrella membership. umbrella.push(np); } // R5: namespace modules (only for ReactNativeHeaders namespaces). Every @@ -424,19 +424,6 @@ function planFromInventory( if (entryList === reactNativeHeaders) { const ns = np.split('/')[0]; if (isUmbrellaSafe(h, root)) { - // R12 assert: an R12-routed umbrella lands under the `React` namespace - // here, and renderNamespaceModuleMap only renames the lowercase `react` - // one — so its module would be named `React` and alias the framework - // module, reintroducing the cycle R12 exists to break. These umbrellas - // are objc-blocked today so they never reach this branch; fail closed - // if that ever changes. - if (ns === 'React') { - throw new Error( - `R12: '${np}' is a modular candidate in ReactNativeHeaders. Its ` + - `namespace module would be named 'React' and alias the React ` + - `framework module. Keep it out of the modular surface.`, - ); - } // R5 exemption assert: a namespace whose name is not a valid module // identifier cannot get a module, so a modular-candidate header in it // would be silently non-modular — consumers importing it from a @@ -463,6 +450,7 @@ function planFromInventory( } umbrella.sort(); + excludedReactHeaders.sort(); for (const ns of Object.keys(namespaceModules)) { namespaceModules[ns].sort(); } @@ -539,23 +527,27 @@ function planFromInventory( textualNamespaceHeaders, namespaceUmbrellas, privateReactHeaders: PRIVATE_REACT_HEADERS, + excludedReactHeaders, collisions, }; } /** - * Renders React.framework's module map (R4 + R9). The umbrella covers the + * Renders React.framework's module map (R4 + R9 + R12). The umbrella covers the * public modular surface; the allowlisted private headers (R9) are appended as * explicit `header` (modular) / `textual header` (objc-blocked) entries so * `#import ` of them stays modular without polluting the umbrella. + * The R12 umbrellas are appended as `exclude header` entries. */ function renderReactModuleMap( privateReactHeaders /*:: ?: {modular: Array, textual: Array} */, + excludedReactHeaders /*: ReadonlyArray */ = [], ) /*: string */ { const pv = privateReactHeaders ?? {modular: [], textual: []}; const extra = [ ...pv.modular.map(h => ` header "${h}"`), ...pv.textual.map(h => ` textual header "${h}"`), + ...excludedReactHeaders.map(h => ` exclude header "${h}"`), ]; const extraBlock = extra.length > 0 ? '\n' + extra.join('\n') : ''; return `framework module React { diff --git a/packages/react-native/scripts/ios-prebuild/headers-verify.js b/packages/react-native/scripts/ios-prebuild/headers-verify.js index 960bed8ac796..a7014077749d 100644 --- a/packages/react-native/scripts/ios-prebuild/headers-verify.js +++ b/packages/react-native/scripts/ios-prebuild/headers-verify.js @@ -211,7 +211,7 @@ function verifyStructural( const fwk = path.join(reactSlice, 'React.framework'); assertFileEquals( path.join(fwk, 'Modules', 'module.modulemap'), - renderReactModuleMap(plan.privateReactHeaders), + renderReactModuleMap(plan.privateReactHeaders, plan.excludedReactHeaders), 'React module map', ); assertFileEquals( @@ -593,6 +593,8 @@ function runCompileGates( SIM_TARGET, '-module-cache-path', path.join(tmp, 'mc-swift-cxx-interop-probe'), + '-F', + reactSlice, '-I', cxxInteropProbeHeaders, '-I',