Facebook/react-native
1
0
Fork 0
mirror of https://github.com/facebook/react-native.git synced 2025-11-01 09:14:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

codereview

Browse Source
This commit is contained in:
Christian Falch
2025-10-14 15:07:00 +02:00
parent 2877f07b3a
commit c498034beb
2 changed files with 124 additions and 244 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/react-native/scripts/ios-prebuild/__docs__/README.md
+81 -68
View File
@@ -1,84 +1,99 @@
# iOS Prebuild Scripts
This directory contains scripts for prebuilding React Native itself into XCFrameworks for iOS and related platforms.
This directory contains scripts for prebuilding React Native itself into
XCFrameworks for iOS and related platforms.
## Overview
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.
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.
## Purpose
The prebuild scripts are used to:
- Build React Native itself (not its dependencies) as XCFrameworks
- Create distributable binaries for iOS, iOS Simulator, Catalyst, Vision, and visionOS platforms
- Create distributable binaries for iOS, iOS Simulator, Catalyst, Vision, and
visionOS platforms
- Support both Debug and Release build configurations
- Generate Debug Symbol (dSYM) files for debugging
- Enable library evolution and module stability for Swift packages
## Architecture
The build system consists of several components:
### `cli.js`
The main entry point that orchestrates the build process. It:
- Parses command-line arguments
- Validates build parameters
- Coordinates the build, archiving, and XCFramework creation steps
### `build.js`
Handles the Swift Package build process. It:
- Executes `xcodebuild` commands with appropriate flags
- Builds for specific platforms and build types (Debug/Release)
- Locates and validates the generated framework artifacts
- Uses build settings like `BUILD_LIBRARY_FOR_DISTRIBUTION=YES` for binary compatibility
### `types.js`
Defines TypeScript/Flow type definitions for:
- `BuildFlavor`: Debug or Release configurations
- `Destination`: Target platforms (iOS, iOS Simulator, Catalyst, Vision, visionOS)
- `ArchiveOptions`: Configuration options for the build process
### `utils.js`
Provides utility functions including:
- Logging functionality with prefixed output
- Common helper functions used across scripts
## Usage
Run the prebuild script from the command line:
```bash
node cli.js [options]
cd packages/react-native
node scripts/ios-prebuild
```
If no options are passed, the script executes all the steps in this order:
- setup build for all platforms and flavors
- compose xcframeworks
- sign (if an identity is passed)
### Options
| Option | Alias | Type | Default | Description |
|--------|-------|------|---------|-------------|
| `--setup` | `-s` | boolean | - | Download and setup dependencies |
| `--build` | `-b` | boolean | - | Build dependencies/platforms |
| `--compose` | `-c` | boolean | - | Compose XCFramework from built dependencies |
| `--platforms` | `-p` | array | `['ios', 'ios-simulator', 'mac-catalyst']` | Specify one or more platforms to build for |
| `--flavor` | `-f` | string | `Debug` | Specify the flavor to build: `Debug` or `Release` |
| `--identity` | `-i` | string | - | Specify the code signing identity to use for signing the frameworks |
| `--help` | - | boolean | - | Show help information |
### Build Process
1. **Build Phase**: Compiles the React Native Swift Package for the specified platform and configuration
2. **Archive Phase**: Collects the built frameworks from the derived data path
3. **XCFramework Creation**: Packages the frameworks into XCFrameworks with debug symbols
| Option | Alias | Type | Default | Description |
| ------------- | ----- | ------- | ------------------------------------------ | ------------------------------------------------------------------- |
| `--setup` | `-s` | boolean | - | Download and setup dependencies |
| `--build` | `-b` | boolean | - | Build dependencies/platforms |
| `--compose` | `-c` | boolean | - | Compose XCFramework from built dependencies |
| `--platforms` | `-p` | array | `['ios', 'ios-simulator', 'mac-catalyst']` | Specify one or more platforms to build for |
| `--flavor` | `-f` | string | `Debug` | Specify the flavor to build: `Debug` or `Release` |
| `--identity` | `-i` | string | - | Specify the code signing identity to use for signing the frameworks |
| `--help` | - | boolean | - | Show help information |
### Output Structure
The build produces:
- XCFrameworks in the specified output directory
- Debug symbols (dSYM files) for debugging
- Build products organized by platform and configuration
## Architecture
The build system consists of several components:
### `cli.js`
The main entry point that orchestrates the build process. It:
- Parses command-line arguments
- Validates build parameters
- Coordinates the build, archiving, and XCFramework creation steps
### `build.js`
Handles the Swift Package build process. It:
- Executes `xcodebuild` commands with appropriate flags
- Builds for specific platforms and build types (Debug/Release)
- Locates and validates the generated framework artifacts
- Uses build settings like `BUILD_LIBRARY_FOR_DISTRIBUTION=YES` for binary
compatibility
### `types.js`
Defines TypeScript/Flow type definitions for:
- `BuildFlavor`: Debug or Release configurations
- `Destination`: Target platforms (iOS, iOS Simulator, Catalyst, Vision,
visionOS)
- `ArchiveOptions`: Configuration options for the build process
### `utils.js`
Provides utility functions including:
- Logging functionality with prefixed output
- Common helper functions used across scripts
## Build Flags
The build process uses specific `xcodebuild` flags:
@@ -86,14 +101,9 @@ The build process uses specific `xcodebuild` flags:
- `BUILD_LIBRARY_FOR_DISTRIBUTION=YES`: Enables module stability
- `SKIP_INSTALL=NO`: Ensures frameworks are properly installed
- `DEBUG_INFORMATION_FORMAT="dwarf-with-dsym"`: Generates debug symbols
- `OTHER_SWIFT_FLAGS="-no-verify-emitted-module-interface"`: Skips interface verification
## Requirements
- Xcode installed with command-line tools
- Swift Package Manager support
- macOS development environment
- Node.js for running the scripts
- `OTHER_SWIFT_FLAGS="-no-verify-emitted-module-interface"`: Skips interface
verification (useful for React Native modules due to the header structure not
beeing modular)
## Notes
@@ -104,21 +114,24 @@ The build process uses specific `xcodebuild` flags:
## Known Issues
The generated XCFrameworks currently use CocoaPods-style header structures rather than standard framework header conventions. This may cause modularity issues when:
The generated XCFrameworks currently use CocoaPods-style header structures
rather than standard framework header conventions. This may cause modularity
issues when:
- Consuming the XCFrameworks in projects that expect standard framework headers
- Building dependent frameworks that rely on proper module boundaries
- Integrating with Swift Package Manager projects expecting modular headers
## Usage
## Integrating in your project with Cocoapods
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`:
For consuming, debugging or troubleshooting when using Cocoapods scripts, you
can use the following environment variables:
```bash
RCT_USE_RN_DEP=1 bundle exec pod install
```
For debugging and troubleshooting the Cocoapods scripts, you can use the following environment variables:
- `RCT_USE_LOCAL_RN_DEP`: **TEST ONLY** If set, it will use a local tarball of ReactNativeDependencies if it exists.
- `RCT_DEPS_VERSION`: **TEST ONLY** If set, it will override the version of ReactNativeDependencies to be used.
- `RCT_USE_PREBUILT_RNCORE`: If set to 1, it will use the release tarball from
Maven instead of building from source.
- `RCT_TESTONLY_RNCORE_TARBALL_PATH`: **TEST ONLY** If set, it will use a local
tarball of RNCore if it exists.
- `RCT_TESTONLY_RNCORE_VERSION`: **TEST ONLY** If set, it will override the
version of RNCore to be used.
- `RCT_SYMBOLICATE_PREBUILT_FRAMEWORKS`: If set to 1, it will download the dSYMs
for the prebuilt RNCore frameworks and install these in the framework folders
scripts/releases/ios-prebuild/__docs__/README.md
+43 -176
View File
@@ -1,12 +1,18 @@
# iOS Prebuild Scripts Documentation
This folder contains scripts for creating precompiled XCFrameworks for React Native's dependencies. These scripts automate the process of downloading, building, and packaging third-party libraries into distributable XCFramework bundles for iOS.
This folder contains scripts for creating precompiled XCFrameworks for React
Native's dependencies. These scripts automate the process of downloading,
building, and packaging third-party libraries into distributable XCFramework
bundles for iOS.
## Overview
The iOS prebuild system creates precompiled frameworks to reduce build times for React Native iOS apps. Instead of compiling dependencies from source during every build, these scripts package them as ready-to-use XCFrameworks.
The iOS prebuild system creates precompiled frameworks to reduce build times for
React Native iOS apps. Instead of compiling dependencies from source during
every build, these scripts package them as ready-to-use XCFrameworks.
The prebuild process creates a Swift package that builds frameworks for the following 3rd party libraries:
The prebuild process creates a Swift package that builds frameworks for the
following 3rd party libraries:
- boost
- folly
@@ -20,190 +26,51 @@ The prebuild process creates a Swift package that builds frameworks for the foll
### `cli.js`
Command-line interface for the prebuild system. Provides the following options:
Command-line interface for the prebuild system.
```bash
# Setup: Download and prepare dependencies
node cli.js --setup
# Build: Compile dependencies for specified platforms
node cli.js --build --platforms ios,macos
# Compose: Create XCFrameworks from built artifacts
node cli.js --compose
# Create Swift Package: Generate Package.swift file
node cli.js --swiftpackage
node scripts/releases/prepare-ios-prebuilds.js
```
If no options are passed, the script executes all the steps in this order:
- setup dependencies and prepares them
- creates Swift package file
- builds for all platforms and configurations
- creates xcframeworks
**Options:**
- `--setup` / `-s`: Download and setup dependencies
- `--build` / `-b`: Build dependencies for target platforms
- `--compose` / `-c`: Compose XCFrameworks from built artifacts
- `--swiftpackage` / `-w`: Generate Package.swift file
- `--platforms` / `-p`: Target platforms (ios, macos, catalyst, tvos, visionos)
- `--configurations` / `-g`: Build configurations (Debug, Release)
- `--dependencies` / `-d`: Specific dependencies to process
- `--clean`: Clean build folder before building
- `--identity` / `-i`: Signing identity for frameworks
### `setupDependencies.js`
| Option | Short | Description |
| ------------------ | ----: | ------------------------------------------------------- |
| `--setup` | `-s` | Download and setup dependencies |
| `--build` | `-b` | Build dependencies for target platforms |
| `--compose` | `-c` | Compose XCFrameworks from built artifacts |
| `--swiftpackage` | `-w` | Generate `Package.swift` file |
| `--platforms` | `-p` | Target platforms (ios, macos, catalyst, tvos, visionos) |
| `--configurations` | `-g` | Build configurations (Debug, Release) |
| `--dependencies` | `-d` | Specific dependencies to process |
| `--clean` | — | Clean build folder before building |
| `--identity` | `-i` | Signing identity for frameworks |
Handles downloading and preparing third-party dependencies defined in `configuration.js`.
## Integrating in your project with Cocoapods
**Functions:**
- Downloads dependencies from specified URLs
- Extracts archives (tar.gz, zip)
- Runs preparation scripts for each dependency
- Organizes source files in the build directory
### `build.js`
Compiles dependencies using Xcode for specified platforms and configurations.
**Key features:**
- Builds for multiple platforms: iOS, macOS, Catalyst, tvOS, visionOS
- Supports both Debug and Release configurations
- Creates universal binaries for device and simulator
- Handles architecture-specific builds (arm64, x86_64)
### `compose-framework.js`
Creates the final XCFramework from built artifacts.
**Functions:**
#### `createFramework(scheme, configuration, dependencies, rootFolder, buildFolder, identity)`
Composes XCFrameworks from platform-specific builds using `xcodebuild -create-xcframework`.
#### `copyHeaders(scheme, dependencies, rootFolder)`
Copies public headers from dependencies to the framework's Headers folder based on settings in `configuration.js`.
#### `copyBundles(scheme, dependencies, outputFolder, frameworkPaths)`
Copies resource bundles into the XCFramework's Resources folder.
#### `copySymbols(scheme, outputFolder, frameworkPaths)`
Copies debug symbols (dSYM files) to enable symbolication of crash reports.
#### `signXCFramework(identity, xcframeworkPath)`
Code signs the XCFramework with the specified identity.
### `configuration.js`
Defines all dependencies and their build settings.
**Configuration structure:**
```javascript
{
name: 'boost',
version: '1.84.0',
url: new URL('https://...'),
files: {
sources: ['boost/**/*.hpp'],
headers: ['boost/**/*.hpp'],
resources: ['PrivacyInfo.xcprivacy']
},
settings: {
publicHeaderFiles: './',
headerSearchPaths: ['./'],
cCompilerFlags: ['-Wno-documentation'],
cxxCompilerFlags: ['-std=c++20']
}
}
```
### `swift-package.js`
Generates a Package.swift file for Swift Package Manager distribution.
**Functions:**
- `createSwiftPackageFile(dependencies, version, outputPath)`: Creates Package.swift with binary target definitions
### `folders.js`
Utility functions for folder operations.
**Functions:**
- `cleanFolder(folderPath)`: Removes and recreates a directory
- `ensureFolder(folderPath)`: Creates directory if it doesn't exist
### `constants.js`
Defines shared constants used across scripts:
- `HEADERS_FOLDER`: Location for extracted headers
- `TARGET_FOLDER`: Build output location
- `CPP_STANDARD`: C++ standard version to use
### `types.js`
Flow type definitions for TypeScript-style type checking:
- `Platform`: Supported platform types
- `Configuration`: Build configuration types
- `Dependency`: Dependency configuration structure
## Workflow
The typical workflow for creating prebuilt frameworks:
1. **Setup Phase** (`setupDependencies.js`)
- Downloads third-party dependencies
- Extracts archives
- Runs preparation scripts
- Organizes files in build directory
2. **Build Phase** (`build.js`)
- Compiles each dependency for target platforms
- Creates fat binaries for device + simulator
- Generates build artifacts in platform-specific folders
3. **Compose Phase** (`compose-framework.js`)
- Combines platform builds into XCFramework
- Copies headers and resources
- Includes debug symbols (dSYM)
- Code signs if identity provided
4. **Package Phase** (`swift-package.js`)
- Generates Package.swift for SPM distribution
- Defines binary targets with checksums
## Integration
The prebuilt frameworks are consumed via CocoaPods or Swift Package Manager.
Related files:
- `packages/react-native/scripts/cocoapods/rndependencies.rb` - CocoaPods integration
- `packages/react-native/React-Core-prebuilt.podspec` - Prebuilt React Core podspec
## Entry Point
The main entry point is `prepare-ios-prebuilds.js` which orchestrates the entire prebuild process:
```javascript
const {buildDepenencies} = require('./ios-prebuild/build');
const {createFramework} = require('./ios-prebuild/compose-framework');
const {setupDependencies} = require('./ios-prebuild/setupDependencies');
```
## Environment Variables
- `RCT_USE_RN_DEP`: Use prebuilt dependencies instead of building from source
- `RCT_USE_LOCAL_RN_DEP`: Use local tarball for testing
- `RCT_SYMBOLICATE_PREBUILT_FRAMEWORKS`: Download and install dSYMs for symbolication
See `packages/react-native/scripts/cocoapods/rncore.rb` for implementation details.
## Usage
To use the prebuilt React Native XCFrameworks in your iOS project, run pod install with the environment variable `RCT_USE_PREBUILT_RNCORE` set to `1`:
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`:
```bash
RCT_USE_PREBUILT_RNCORE=1 bundle exec pod install
RCT_USE_RN_DEP=1 bundle exec pod install
```
This can be combined with `RCT_USE_RN_DEP=1` to use both React Native and its dependencies as prebuilt frameworks.
This can be combined with `RCT_USE_RN_DEP=1` to use both React Native and its
dependencies as prebuilt frameworks.
For debugging and troubleshooting the Cocoapods scripts, you can use the following environment variables:
For debugging and troubleshooting the Cocoapods scripts, you can use the
following environment variables:
- `RCT_TESTONLY_RNCORE_TARBALL_PATH`: **TEST ONLY** If set, it will use a local tarball of RNCore if it exists.
- `RCT_TESTONLY_RNCORE_VERSION`: **TEST ONLY** If set, it will override the version of RNCore to be used.
- `RCT_SYMBOLICATE_PREBUILT_FRAMEWORKS`: If set to 1, it will download the dSYMs for the prebuilt RNCore frameworks and install these in the framework folders
- `RCT_USE_RN_DEP`: If set to 1, it will use the release tarball from Maven
instead of building from source.
- `RCT_USE_LOCAL_RN_DEP`: **TEST ONLY** If set, it will use a local tarball of
ReactNativeDependencies if it exists.
- `RCT_DEPS_VERSION`: **TEST ONLY** If set, it will override the version of
ReactNativeDependencies to be used.