Skip to content

Commit 7a66582

Browse files
chrfalchmeta-codesync[bot]
chrfalch
authored and
meta-codesync[bot]
committed
added readme/doc files for precompile (#54137)
Summary: Added readme files for both RN dependencies and RN Core precompiled ## Changelog: [IOS] [FIXED] - Added documentation for the prebuild scripts for precompiling React Native Core and React Native Dependencies. Pull Request resolved: #54137 Reviewed By: cipolleschi Differential Revision: D84506769 Pulled By: cortinico fbshipit-source-id: 628f5b335619f67637f582f45180fd0d16e872c4
1 parent 1d9d3ae commit 7a66582

File tree

2 files changed

+212
-0
lines changed
  • packages/react-native/scripts/ios-prebuild/__docs__
  • scripts/releases/ios-prebuild/__docs__

2 files changed

+212
-0
lines changed

‎packages/react-native/scripts/ios-prebuild/__docs__/README.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# iOS Prebuild Scripts
2+
3+
This directory contains scripts for prebuilding React Native itself into
4+
XCFrameworks for iOS and related platforms.
5+
6+
## Overview
7+
8+
These scripts automate the process of building React Native as a Swift Package
9+
and packaging it into XCFrameworks that can be distributed and consumed by iOS
10+
applications. The build process creates optimized frameworks for multiple
11+
architectures and platforms.
12+
13+
## Purpose
14+
15+
The prebuild scripts are used to:
16+
17+
- Build React Native itself (not its dependencies) as XCFrameworks
18+
- Create distributable binaries for iOS, iOS Simulator, Catalyst.
19+
- Support both Debug and Release build configurations
20+
- Generate Debug Symbol (dSYM) files for debugging
21+
22+
## Usage
23+
24+
Run the prebuild script from the command line:
25+
26+
```bash
27+
cd packages/react-native
28+
node scripts/ios-prebuild
29+
```
30+
31+
If no options are passed, the script executes all the steps in this order:
32+
33+
- setup the codebase for all platforms and flavors
34+
- build for all platforms and flavors
35+
- compose xcframeworks
36+
- sign (if an identity is passed)
37+
38+
### Options
39+
40+
| Option | Alias | Type | Default | Description |
41+
| ------------- | ----- | ------- | ------------------------------------------ | ------------------------------------------------------------------- |
42+
| `--setup` | `-s` | boolean | - | Download and setup dependencies |
43+
| `--build` | `-b` | boolean | - | Build dependencies/platforms |
44+
| `--compose` | `-c` | boolean | - | Compose XCFramework from built dependencies |
45+
| `--platforms` | `-p` | array | `['ios', 'ios-simulator', 'mac-catalyst']` | Specify one or more platforms to build for |
46+
| `--flavor` | `-f` | string | `Debug` | Specify the flavor to build: `Debug` or `Release` |
47+
| `--identity` | `-i` | string | - | Specify the code signing identity to use for signing the frameworks |
48+
| `--help` | - | boolean | - | Show help information |
49+
50+
### Output Structure
51+
52+
The build produces:
53+
54+
- XCFrameworks in the specified output directory
55+
- Debug symbols (dSYM files) for debugging
56+
- Build products organized by platform and configuration
57+
58+
## Architecture
59+
60+
The build system consists of several components:
61+
62+
### `cli.js`
63+
64+
The main entry point that orchestrates the build process. It:
65+
66+
- Parses command-line arguments
67+
- Validates build parameters
68+
- Coordinates the build, archiving, and XCFramework creation steps
69+
70+
### `build.js`
71+
72+
Handles the Swift Package build process. It:
73+
74+
- Executes `xcodebuild` commands with appropriate flags
75+
- Builds for specific platforms and build types (Debug/Release)
76+
- Locates and validates the generated framework artifacts
77+
- Uses build settings like `BUILD_LIBRARY_FOR_DISTRIBUTION=YES` for binary
78+
compatibility
79+
80+
### `types.js`
81+
82+
Defines TypeScript/Flow type definitions for:
83+
84+
- `BuildFlavor`: Debug or Release configurations
85+
- `Destination`: Target platforms (iOS, iOS Simulator, Catalyst, Vision,
86+
visionOS)
87+
- `ArchiveOptions`: Configuration options for the build process
88+
89+
### `utils.js`
90+
91+
Provides utility functions including:
92+
93+
- Logging functionality with prefixed output
94+
- Common helper functions used across scripts
95+
96+
## Build Flags
97+
98+
The build process uses specific `xcodebuild` flags:
99+
100+
- `BUILD_LIBRARY_FOR_DISTRIBUTION=YES`: Enables module stability
101+
- `SKIP_INSTALL=NO`: Ensures frameworks are properly installed
102+
- `DEBUG_INFORMATION_FORMAT="dwarf-with-dsym"`: Generates debug symbols
103+
- `OTHER_SWIFT_FLAGS="-no-verify-emitted-module-interface"`: Skips interface
104+
verification (useful for React Native modules due to the header structure not
105+
beeing modular)
106+
107+
## Notes
108+
109+
- These scripts build React Native itself, not third-party dependencies
110+
- The build process requires significant disk space for derived data
111+
- Build times vary depending on the target platform and configuration
112+
- XCFrameworks support multiple architectures in a single bundle
113+
114+
## Known Issues
115+
116+
The generated XCFrameworks currently use CocoaPods-style header structures
117+
rather than standard framework header conventions. This may cause modularity
118+
issues when:
119+
120+
- Consuming the XCFrameworks in projects that expect standard framework headers
121+
- Building dependent frameworks that rely on proper module boundaries
122+
- Integrating with Swift Package Manager projects expecting modular headers
123+
124+
## Integrating in your project with Cocoapods
125+
126+
For consuming, debugging or troubleshooting when using Cocoapods scripts, you
127+
can use the following environment variables:
128+
129+
- `RCT_USE_PREBUILT_RNCORE`: If set to 1, it will use the release tarball from
130+
Maven instead of building from source.
131+
- `RCT_TESTONLY_RNCORE_TARBALL_PATH`: **TEST ONLY** If set, it will use a local
132+
tarball of RNCore if it exists.
133+
- `RCT_TESTONLY_RNCORE_VERSION`: **TEST ONLY** If set, it will override the
134+
version of RNCore to be used.
135+
- `RCT_SYMBOLICATE_PREBUILT_FRAMEWORKS`: If set to 1, it will download the dSYMs
136+
for the prebuilt RNCore frameworks and install these in the framework folders

‎scripts/releases/ios-prebuild/__docs__/README.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# iOS Prebuild Scripts Documentation
2+
3+
This folder contains scripts for creating precompiled XCFrameworks for React
4+
Native's dependencies. These scripts automate the process of downloading,
5+
building, and packaging third-party libraries into distributable XCFramework
6+
bundles for iOS.
7+
8+
## Overview
9+
10+
The iOS prebuild system creates precompiled frameworks to reduce build times for
11+
React Native iOS apps. Instead of compiling dependencies from source during
12+
every build, these scripts package them as ready-to-use XCFrameworks.
13+
14+
The prebuild process creates a Swift package that builds frameworks for the
15+
following 3rd party libraries:
16+
17+
- boost
18+
- folly
19+
- glog
20+
- fmt
21+
- double-conversion
22+
- socketrocket
23+
- fast-float
24+
25+
## Main Scripts
26+
27+
### `cli.js`
28+
29+
Command-line interface for the prebuild system.
30+
31+
```bash
32+
node scripts/releases/prepare-ios-prebuilds.js
33+
```
34+
35+
If no options are passed, the script executes all the steps in this order:
36+
37+
- setup dependencies and prepares them
38+
- creates Swift package file
39+
- builds for all platforms and configurations
40+
- creates xcframeworks
41+
42+
**Options:**
43+
44+
| Option | Short | Description |
45+
| ------------------ | ----: | ------------------------------------------------------- |
46+
| `--setup` | `-s` | Download and setup dependencies |
47+
| `--build` | `-b` | Build dependencies for target platforms |
48+
| `--compose` | `-c` | Compose XCFrameworks from built artifacts |
49+
| `--swiftpackage` | `-w` | Generate `Package.swift` file |
50+
| `--platforms` | `-p` | Target platforms (ios, macos, catalyst, tvos, visionos) |
51+
| `--configurations` | `-g` | Build configurations (Debug, Release) |
52+
| `--dependencies` | `-d` | Specific dependencies to process |
53+
| `--clean` | — | Clean build folder before building |
54+
| `--identity` | `-i` | Signing identity for frameworks |
55+
56+
## Integrating in your project with Cocoapods
57+
58+
To use the prebuilt React Native Dependencies XCFrameworks in your iOS project,
59+
run pod install with the environment variable `RCT_USE_RN_DEP` set to `1`:
60+
61+
```bash
62+
RCT_USE_RN_DEP=1 bundle exec pod install
63+
```
64+
65+
This can be combined with `RCT_USE_RN_DEP=1` to use both React Native and its
66+
dependencies as prebuilt frameworks.
67+
68+
For debugging and troubleshooting the Cocoapods scripts, you can use the
69+
following environment variables:
70+
71+
- `RCT_USE_RN_DEP`: If set to 1, it will use the release tarball from Maven
72+
instead of building from source.
73+
- `RCT_USE_LOCAL_RN_DEP`: **TEST ONLY** If set, it will use a local tarball of
74+
ReactNativeDependencies if it exists.
75+
- `RCT_DEPS_VERSION`: **TEST ONLY** If set, it will override the version of
76+
ReactNativeDependencies to be used.

0 commit comments

Comments
 (0)