diff --git a/packages/react-native/scripts/ios-prebuild/__docs__/README.md b/packages/react-native/scripts/ios-prebuild/__docs__/README.md new file mode 100644 index 00000000000000..c7a671e9611007 --- /dev/null +++ b/packages/react-native/scripts/ios-prebuild/__docs__/README.md @@ -0,0 +1,137 @@ +# iOS Prebuild Scripts + +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. + +## 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 +- Support both Debug and Release build configurations +- Generate Debug Symbol (dSYM) files for debugging +- Enable library evolution and module stability for Swift packages + +## Usage + +Run the prebuild script from the command line: + +```bash +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 | + +### 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: + +- `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 (useful for React Native modules due to the header structure not + beeing modular) + +## Notes + +- These scripts build React Native itself, not third-party dependencies +- The build process requires significant disk space for derived data +- Build times vary depending on the target platform and configuration +- XCFrameworks support multiple architectures in a single bundle + +## Known Issues + +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 + +## Integrating in your project with Cocoapods + +For consuming, debugging or troubleshooting when using Cocoapods scripts, you +can use the following environment variables: + +- `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 diff --git a/scripts/releases/ios-prebuild/__docs__/README.md b/scripts/releases/ios-prebuild/__docs__/README.md new file mode 100644 index 00000000000000..9b0953f43f2852 --- /dev/null +++ b/scripts/releases/ios-prebuild/__docs__/README.md @@ -0,0 +1,76 @@ +# 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. + +## 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 prebuild process creates a Swift package that builds frameworks for the +following 3rd party libraries: + +- boost +- folly +- glog +- fmt +- double-conversion +- socketrocket +- fast-float + +## Main Scripts + +### `cli.js` + +Command-line interface for the prebuild system. + +```bash +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:** + +| 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 | + +## 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`: + +```bash +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. + +For debugging and troubleshooting the Cocoapods scripts, you can use the +following environment variables: + +- `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.