Skip to content

Commit c498034

Browse files
chrfalchchrfalch
committed
codereview
1 parent 2877f07 commit c498034

2 files changed

Lines changed: 114 additions & 234 deletions

File tree

  • packages/react-native/scripts/ios-prebuild/__docs__
  • scripts/releases/ios-prebuild/__docs__

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

Lines changed: 72 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -1,99 +1,109 @@
11
# iOS Prebuild Scripts
22

3-
This directory contains scripts for prebuilding React Native itself into XCFrameworks for iOS and related platforms.
3+
This directory contains scripts for prebuilding React Native itself into
4+
XCFrameworks for iOS and related platforms.
45

56
## Overview
67

7-
These scripts automate the process of building React Native as a Swift Package and packaging it into XCFrameworks that can be distributed and consumed by iOS applications. The build process creates optimized frameworks for multiple architectures and platforms.
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.
812

913
## Purpose
1014

1115
The prebuild scripts are used to:
1216

1317
- Build React Native itself (not its dependencies) as XCFrameworks
14-
- Create distributable binaries for iOS, iOS Simulator, Catalyst, Vision, and visionOS platforms
18+
- Create distributable binaries for iOS, iOS Simulator, Catalyst, Vision, and
19+
visionOS platforms
1520
- Support both Debug and Release build configurations
1621
- Generate Debug Symbol (dSYM) files for debugging
1722
- Enable library evolution and module stability for Swift packages
1823

24+
## Usage
25+
26+
Run the prebuild script from the command line:
27+
28+
```bash
29+
cd packages/react-native
30+
node scripts/ios-prebuild
31+
```
32+
33+
If no options are passed, the script executes all the steps in this order:
34+
35+
- setup build for all platforms and flavors
36+
- compose xcframeworks
37+
- sign (if an identity is passed)
38+
39+
### Options
40+
41+
| Option | Alias | Type | Default | Description |
42+
| ------------- | ----- | ------- | ------------------------------------------ | ------------------------------------------------------------------- |
43+
| `--setup` | `-s` | boolean | - | Download and setup dependencies |
44+
| `--build` | `-b` | boolean | - | Build dependencies/platforms |
45+
| `--compose` | `-c` | boolean | - | Compose XCFramework from built dependencies |
46+
| `--platforms` | `-p` | array | `['ios', 'ios-simulator', 'mac-catalyst']` | Specify one or more platforms to build for |
47+
| `--flavor` | `-f` | string | `Debug` | Specify the flavor to build: `Debug` or `Release` |
48+
| `--identity` | `-i` | string | - | Specify the code signing identity to use for signing the frameworks |
49+
| `--help` | - | boolean | - | Show help information |
50+
51+
### Output Structure
52+
53+
The build produces:
54+
55+
- XCFrameworks in the specified output directory
56+
- Debug symbols (dSYM files) for debugging
57+
- Build products organized by platform and configuration
58+
1959
## Architecture
2060

2161
The build system consists of several components:
2262

2363
### `cli.js`
64+
2465
The main entry point that orchestrates the build process. It:
66+
2567
- Parses command-line arguments
2668
- Validates build parameters
2769
- Coordinates the build, archiving, and XCFramework creation steps
2870

2971
### `build.js`
72+
3073
Handles the Swift Package build process. It:
74+
3175
- Executes `xcodebuild` commands with appropriate flags
3276
- Builds for specific platforms and build types (Debug/Release)
3377
- Locates and validates the generated framework artifacts
34-
- Uses build settings like `BUILD_LIBRARY_FOR_DISTRIBUTION=YES` for binary compatibility
78+
- Uses build settings like `BUILD_LIBRARY_FOR_DISTRIBUTION=YES` for binary
79+
compatibility
3580

3681
### `types.js`
82+
3783
Defines TypeScript/Flow type definitions for:
84+
3885
- `BuildFlavor`: Debug or Release configurations
39-
- `Destination`: Target platforms (iOS, iOS Simulator, Catalyst, Vision, visionOS)
86+
- `Destination`: Target platforms (iOS, iOS Simulator, Catalyst, Vision,
87+
visionOS)
4088
- `ArchiveOptions`: Configuration options for the build process
4189

4290
### `utils.js`
91+
4392
Provides utility functions including:
93+
4494
- Logging functionality with prefixed output
4595
- Common helper functions used across scripts
4696

47-
## Usage
48-
49-
Run the prebuild script from the command line:
50-
51-
```bash
52-
node cli.js [options]
53-
```
54-
55-
### Options
56-
57-
58-
| Option | Alias | Type | Default | Description |
59-
|--------|-------|------|---------|-------------|
60-
| `--setup` | `-s` | boolean | - | Download and setup dependencies |
61-
| `--build` | `-b` | boolean | - | Build dependencies/platforms |
62-
| `--compose` | `-c` | boolean | - | Compose XCFramework from built dependencies |
63-
| `--platforms` | `-p` | array | `['ios', 'ios-simulator', 'mac-catalyst']` | Specify one or more platforms to build for |
64-
| `--flavor` | `-f` | string | `Debug` | Specify the flavor to build: `Debug` or `Release` |
65-
| `--identity` | `-i` | string | - | Specify the code signing identity to use for signing the frameworks |
66-
| `--help` | - | boolean | - | Show help information |
67-
68-
69-
### Build Process
70-
71-
1. **Build Phase**: Compiles the React Native Swift Package for the specified platform and configuration
72-
2. **Archive Phase**: Collects the built frameworks from the derived data path
73-
3. **XCFramework Creation**: Packages the frameworks into XCFrameworks with debug symbols
74-
75-
### Output Structure
76-
77-
The build produces:
78-
- XCFrameworks in the specified output directory
79-
- Debug symbols (dSYM files) for debugging
80-
- Build products organized by platform and configuration
81-
8297
## Build Flags
8398

8499
The build process uses specific `xcodebuild` flags:
85100

86101
- `BUILD_LIBRARY_FOR_DISTRIBUTION=YES`: Enables module stability
87102
- `SKIP_INSTALL=NO`: Ensures frameworks are properly installed
88103
- `DEBUG_INFORMATION_FORMAT="dwarf-with-dsym"`: Generates debug symbols
89-
- `OTHER_SWIFT_FLAGS="-no-verify-emitted-module-interface"`: Skips interface verification
90-
91-
## Requirements
92-
93-
- Xcode installed with command-line tools
94-
- Swift Package Manager support
95-
- macOS development environment
96-
- Node.js for running the scripts
104+
- `OTHER_SWIFT_FLAGS="-no-verify-emitted-module-interface"`: Skips interface
105+
verification (useful for React Native modules due to the header structure not
106+
beeing modular)
97107

98108
## Notes
99109

@@ -104,21 +114,24 @@ The build process uses specific `xcodebuild` flags:
104114

105115
## Known Issues
106116

107-
The generated XCFrameworks currently use CocoaPods-style header structures rather than standard framework header conventions. This may cause modularity issues when:
117+
The generated XCFrameworks currently use CocoaPods-style header structures
118+
rather than standard framework header conventions. This may cause modularity
119+
issues when:
108120

109121
- Consuming the XCFrameworks in projects that expect standard framework headers
110122
- Building dependent frameworks that rely on proper module boundaries
111123
- Integrating with Swift Package Manager projects expecting modular headers
112124

113-
## Usage
114-
115-
To use the prebuilt React Native dependencies XCFrameworks in your iOS project, run pod install with the environment variable `RCT_USE_RN_DEP` set to `1`:
116-
117-
```bash
118-
RCT_USE_RN_DEP=1 bundle exec pod install
119-
```
125+
## Integrating in your project with Cocoapods
120126

121-
For debugging and troubleshooting the Cocoapods scripts, you can use the following environment variables:
127+
For consuming, debugging or troubleshooting when using Cocoapods scripts, you
128+
can use the following environment variables:
122129

123-
- `RCT_USE_LOCAL_RN_DEP`: **TEST ONLY** If set, it will use a local tarball of ReactNativeDependencies if it exists.
124-
- `RCT_DEPS_VERSION`: **TEST ONLY** If set, it will override the version of ReactNativeDependencies to be used.
130+
- `RCT_USE_PREBUILT_RNCORE`: If set to 1, it will use the release tarball from
131+
Maven instead of building from source.
132+
- `RCT_TESTONLY_RNCORE_TARBALL_PATH`: **TEST ONLY** If set, it will use a local
133+
tarball of RNCore if it exists.
134+
- `RCT_TESTONLY_RNCORE_VERSION`: **TEST ONLY** If set, it will override the
135+
version of RNCore to be used.
136+
- `RCT_SYMBOLICATE_PREBUILT_FRAMEWORKS`: If set to 1, it will download the dSYMs
137+
for the prebuilt RNCore frameworks and install these in the framework folders

0 commit comments

Comments
 (0)