[precompile] added readme/doc files for precompile

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

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.