Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
56 commits
Select commit Hold shift + click to select a range
814015a
docs: add alpha.8 plan 2, the precheck
WillyAntunez Nov 9, 2026
5303c03
feat: scan the includes of app sources
WillyAntunez Nov 9, 2026
5c2dd27
refactor: share the app copy layout with B1
WillyAntunez Nov 9, 2026
c3234f4
fix: open absolute include spellings as clang does
WillyAntunez Nov 9, 2026
faaba7d
feat: resolve the app's own includes (B1)
WillyAntunez Nov 9, 2026
ac92a7c
fix: judge quote includes by header base name
WillyAntunez Nov 9, 2026
81882b2
fix: stop only on the app's own quote includes
WillyAntunez Nov 9, 2026
813dd5b
feat: name xcconfigs and synchronized folders
WillyAntunez Nov 9, 2026
f4d9245
feat: check the app's includes in doctor and build
WillyAntunez Nov 9, 2026
fbcabb7
fix: say what Expo copies when an include is missing
WillyAntunez Nov 9, 2026
974724f
refactor: one flag source for the App target
WillyAntunez Nov 9, 2026
8c58558
feat: read the package graph for the precheck
WillyAntunez Nov 9, 2026
2e7e644
fix: count product names among the graph's targets
WillyAntunez Nov 9, 2026
797f501
fix: resolve packages as SwiftPM aliases them
WillyAntunez Nov 9, 2026
42d3b65
feat: build the precheck's command lines
WillyAntunez Nov 9, 2026
19576ce
fix: give swiftc the SDK's Swift resources
WillyAntunez Nov 9, 2026
82f85c2
feat: report the precheck's compile errors
WillyAntunez Nov 9, 2026
c06ae0d
fix: keep swiftc's include trail in the stack
WillyAntunez Nov 9, 2026
a576542
feat: precheck the app sources before xtool
WillyAntunez Nov 9, 2026
1eb6d88
fix: keep pass 2 certain where it cannot know
WillyAntunez Nov 9, 2026
e9f0a26
fix: scope pass 2 errors to certain includes
WillyAntunez Nov 9, 2026
1d38cfc
feat: add the precheck step and --skip-precheck
WillyAntunez Nov 9, 2026
39928b0
docs: describe the app target precheck
WillyAntunez Nov 9, 2026
9b2b22d
docs: say what the precheck skips on Expo
WillyAntunez Nov 9, 2026
c20b265
test: capture Swift Build's App command lines
WillyAntunez Nov 9, 2026
ead5ccb
fix: typecheck the App as a library
WillyAntunez Nov 9, 2026
8c0be3e
fix: define what Swift Build defines
WillyAntunez Nov 9, 2026
456d1d8
fix: name one module map per module
WillyAntunez Nov 9, 2026
6f95aaf
fix: give swiftc Swift Build's search paths
WillyAntunez Nov 9, 2026
4a7f859
fix: compile C-family files as module App
WillyAntunez Nov 9, 2026
607065d
test: compare the precheck with Swift Build
WillyAntunez Nov 10, 2026
83118d7
fix: pass the package name and iframework dirs
WillyAntunez Nov 10, 2026
d2843a6
docs: correct why Expo's Swift skips the precheck
WillyAntunez Nov 10, 2026
4b3a66e
docs: record the precheck's reference timings
WillyAntunez Nov 10, 2026
94c937f
fix: assume only the compile's defines in B1
WillyAntunez Nov 10, 2026
bdc774f
fix: keep copied module maps' headers resolvable
WillyAntunez Nov 10, 2026
9e84aa0
fix: skip files that import Swift-built modules
WillyAntunez Nov 10, 2026
e49292a
fix: name the exit on every precheck stop
WillyAntunez Nov 10, 2026
027b07b
fix: match the path of folder spellings in pass 1
WillyAntunez Nov 10, 2026
121aa83
feat: let --skip-precheck soften pass-1 misses
WillyAntunez Nov 10, 2026
678905b
fix: give clang Swift Build's include order
WillyAntunez Nov 10, 2026
1a15249
fix: tidy precheck edge cases
WillyAntunez Nov 10, 2026
99a91bf
test: keep binary-header counts in the golden
WillyAntunez Nov 10, 2026
d54d54f
docs: record the fix wave's rulings
WillyAntunez Nov 10, 2026
d8e7b82
fix: name the exit in the pass-1 stop
WillyAntunez Nov 10, 2026
4b82b99
docs: record the pass-1 evidence ruling
WillyAntunez Nov 10, 2026
a3c8d3c
fix: keep the exit when the precheck log fails
WillyAntunez Nov 10, 2026
e55304c
fix: give the bridging header the importer's flags
WillyAntunez Nov 10, 2026
c251223
fix: resolve pass 2 in the compile's include order
WillyAntunez Nov 10, 2026
0bed1ba
test: catch scattered include folders in the golden
WillyAntunez Nov 10, 2026
a80ea7a
fix: follow symlinks when classing Swift targets
WillyAntunez Nov 10, 2026
d5fb628
fix: tell the truth in two precheck notes
WillyAntunez Nov 10, 2026
2981c92
docs: say what a failed precheck log write loses
WillyAntunez Nov 10, 2026
6e182d8
fix: tell the truth in the Swift module note
WillyAntunez Nov 10, 2026
496c44b
test: pin the most severe pass-2 verdict
WillyAntunez Nov 10, 2026
d9e614d
docs: widen the precheck's reference timings
WillyAntunez Nov 10, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 50 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,56 @@ versions follow [Semantic Versioning](https://semver.org/) with `alpha` prerelea

## [Unreleased]

### Changed
- `build` stops seconds after it starts, before the `patches` step (on Expo, once `expo prebuild` has written `ios/`),
when a file of the app target has a quote include of one of the app's own headers that resolves nowhere, instead of
minutes later in `xtool-build`: one `✖` line per include, naming the file and line, the places the app target's copy
searched ("which is not among the files the app target lists next to <file>, in the app target's headers or in <search
paths>") and, when `ios/` holds one, a file of that name that differs only in case ("file names are case-sensitive on
Linux"), that the target does not list, or, on Expo, that is not copied ("exists, but rn-xtool copies only the
bridging header of an Expo app"), then "<n> include(s) of the app's own sources resolve nowhere (listed above): the
build would stop compiling them; if xtool-build builds them, build with rn-xtool build --skip-precheck and report it
with rn-xtool doctor --report". With `--skip-precheck` each line is a `⚠` line instead, followed by "⚠ <n>
include(s) of the app's own sources resolve nowhere (listed above); checked by xtool-build (--skip-precheck)", and the
build goes on. In a project with CocoaPods binaries it never stops: every miss is left to the `precheck` step. A
quote include with a folder (`"SomeLib/Utils.h"`) counts as the app's own only when a header of the app target, or a
file under `ios/`, has that path, and an include under a condition on a macro the App compile does not define
(`RCT_NEW_ARCH_ENABLED`) is left to the compile. On Expo it reads the bridging header. See
[troubleshooting.md](docs/troubleshooting.md#precheck).
- A bare React Native app target that takes its files from an Xcode 16 synchronized folder is refused by `build`
and `doctor --project`: "The app target <name> takes its files from the synchronized folder <folder> (an Xcode 16
folder group); rn-xtool reads only the files a target lists. Convert the folder to a group (Xcode: Convert to
Group) so the target lists its files".

### Added
- The `precheck` build step, between `generate` and `xtool-build`: SwiftPM plans the generated package, the app's
includes are resolved again with the App target's full include list, `swiftc -typecheck` checks the Swift files and
`clang -fsyntax-only` each C-family file with the generated manifest's flags. When a Swift file imports a module
SwiftPM builds from Swift (a Swift library, or one with Swift files next to its Objective-C), the Swift files are left
to `xtool-build`, and a C-family file that `@import`s such a module, or one no module map of the package graph
declares (an SDK module such as CommonCrypto is left to xtool-build too), is left to it too ("ℹ precheck — <file>
imports the module <M>, which SwiftPM builds; checked by xtool-build", or "…, which no module map of the package
graph declares; …"); on Expo the app's Swift files import such a module (`Expo`, or `ExpoModulesCore` in the
generated `ExpoModulesProvider.swift`), so they are always checked there. Errors stop the build before `xtool-build`, with one line per include that resolves nowhere and
the compilers' first ten errors with their include stacks (an error several files report counts once), and the stop
names `rn-xtool build --skip-precheck` for a false one; so does every other stop of the step (SwiftPM's refusals, an
unreadable xcframework, a full disk) except a missing toolchain, which names `rn-xtool setup`. A precheck that passes
does not promise that `xtool-build` does: code generation and link errors still show there. Every command and its
output go to `ios-xtool/.precheck/precheck.log`; after a write to it fails (a full disk), the log may miss the lines
that follow, while the terminal and the stop lose none. The first precheck is slower while clang builds React Native's
modules into the module cache, which `--clean` empties. See
[how-it-works.md](docs/how-it-works.md#the-build-step-by-step).
- `--skip-precheck` on `build` and `run` leaves the `precheck` step out, with "⚠ precheck skipped (--skip-precheck):
errors in the app's own sources show in xtool-build"; the check of the app's own includes at the start of `build`
still runs, and prints its misses as `⚠` lines without stopping.
- `rn-xtool doctor --project` checks the app's own includes as `build` does, without a toolchain: `app-includes` lines
(`✖` per include that resolves nowhere, `ℹ` for those left to the `precheck` step, `✔` when they resolve).
- A `⚠` line, at `build` and as `app-target` in `doctor --project`, for an `.xcconfig` other than CocoaPods' that the
Debug configuration of the app target or of the project is based on and that sets a setting rn-xtool reads from the
pbxproj: "⚠ <file> sets <settings> for the app target; rn-xtool does not read xcconfig files".
- `rn-xtool doctor --report` has a `precheck:` line: `precheck: run (last build)`, `precheck: skipped with
--skip-precheck (last build)` or `precheck: not recorded`.

## [0.1.0-alpha.8] - 2026-11-09

### Upgrading from 0.1.0-alpha.7
Expand Down
8 changes: 4 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,8 +46,8 @@ Swift file) and 20 native libraries builds, installs over USB and launches on a
2026-11-06; its features are not checked yet, [details](docs/bare-react-native.md#react-native-085)).

`rn-xtool doctor --project` shows which line your project is on and what rn-xtool finds in it (the SwiftPM scripts
and prebuilt artifacts it would use, Expo's plugin and modules, podspec features), without the toolchain, login and
device checks ([details](docs/troubleshooting.md#doctor---project)).
and prebuilt artifacts it would use, Expo's plugin and modules, podspec features, the app's own includes), without
the toolchain, login and device checks ([details](docs/troubleshooting.md#doctor---project)).

CocoaPods is not needed: the `Podfile` is ignored. Any library with a podspec is tried automatically (CocoaPods-only
ones get a generated `Package.swift`, and the pods they depend on come from SwiftPM packages or, for pods of prebuilt
Expand Down Expand Up @@ -155,10 +155,10 @@ Details, every message and what to do: [docs/troubleshooting.md](docs/troublesho
| `setup [--xcode-xip <path>] [--wifi [--yes] [--udid <udid>]]` | Installs Swift via swiftly, the xtool AppImage and the Darwin SDK. Idempotent. `--wifi` is the one-time USB step for Wi‑Fi installs: it caches the pair record and, with `--yes`, enables Wi‑Fi connections on the iPhone. |
| `auth [args...]` | Runs `xtool auth <args>` (`auth login`, `auth logout`); with no arguments, `xtool auth status`. |
| `doctor [--project] [--report]` | Checks toolchain, SDK, login, connected device, Wi‑Fi install readiness and project. Exits non-zero on problems. `--project` checks only the project in the current folder: its version gates, what rn-xtool finds in it and the setups it cannot build yet. `--report` prints the same checks as one block to paste into a GitHub issue, with your home folder, Apple ID, Team ID, bundle identifiers, UDIDs, device names, IP and MAC addresses replaced by placeholders, and makes no network request ([details](docs/troubleshooting.md#reporting-a-problem)). |
| `build [--clean]` | Prebuild if `ios/` is missing (Expo only), patches, RN/Expo SwiftPM pipeline, ExpoModulesJSI (Expo modules only), generates `ios-xtool/`, `xtool dev build`. `--clean` re-runs `expo prebuild --clean` for Expo; for bare it removes `ios/build` and `ios-xtool` and leaves the rest of `ios/` alone. |
| `build [--clean] [--skip-precheck]` | Prebuild if `ios/` is missing (Expo only), patches, RN/Expo SwiftPM pipeline, ExpoModulesJSI (Expo modules only), generates `ios-xtool/`, checks the app's own sources (`precheck`), `xtool dev build`. `--clean` re-runs `expo prebuild --clean` for Expo; for bare it removes `ios/build` and `ios-xtool` and leaves the rest of `ios/` alone. `--skip-precheck` leaves the `precheck` step out, and the check of the app's own includes at build start warns instead of stopping ([details](docs/troubleshooting.md#precheck)). |
| `install [--network [ip] [--udid <udid>] [--pair-record <file>]]` | Signs and installs the app on the USB-connected iPhone (over Wi‑Fi without the cable with `--network`, see [docs/wifi-install.md](docs/wifi-install.md)), then prints, for apps with expo-dev-client, the Metro URL with a link and QR code that open the app on it, and the first-run checklist. |
| `start [--clear]` | Starts Metro (`npx expo start`; `npx react-native start` for bare) on the port and LAN IP the app was built for. Tells you to rebuild if either changed; clears the Metro cache when dependencies changed (or with `--clear`). With expo-dev-client it announces Metro to the dev launcher under the installed app's bundle id. |
| `run [--clean] [--force] [--network [ip]]` | `build` and `install` when dependencies changed (or with `--force`), then `start`. `--network` installs over Wi‑Fi. |
| `run [--clean] [--force] [--network [ip]] [--skip-precheck]` | `build` and `install` when dependencies changed (or with `--force`), then `start`. `--network` installs over Wi‑Fi; `--skip-precheck` goes to `build`. |

## Configuration

Expand Down
32 changes: 28 additions & 4 deletions docs/bare-react-native.md
Original file line number Diff line number Diff line change
Expand Up @@ -193,16 +193,35 @@ missing bundle identifier.

`patches`, `rn-artifacts` (with the vendored SwiftPM scripts, so 0.85, 0.86 and 0.87, unless `rnArtifactsDir` is set),
`rn-spm`, `jsi` (only with Expo modules), `app-config` (only when `expo-constants` is installed), `frameworks`,
`generate` and `xtool-build`. `expo prebuild` never runs, and the `rn-spm` step runs React Native's
`generate`, `precheck` and `xtool-build`. `expo prebuild` never runs, and the `rn-spm` step runs React Native's
SwiftPM generation steps without injecting anything into your Xcode project (it writes `ios/build/` only). Your
`Podfile` and any `pod install` result are ignored.

`build --clean` removes `ios/build` and `ios-xtool` and leaves the rest of `ios/` alone.

Before the first step, `build` resolves the `#import` and `#include` lines of the app target's C-family sources, headers
and bridging header as the generated App target compiles them, with file reads only (pass 1): a quote include of one of
the app's own headers that resolves nowhere stops the build seconds after it starts, naming the file, the places
searched and, when `ios/` holds one, a file of that name that differs only in case or that the target does not list. In
a project with CocoaPods binaries it never stops: every miss is left to the `precheck` step. With `--skip-precheck` it
prints its misses as `⚠` lines and the build goes on, and `doctor --project` runs the same check as its `app-includes`
line. Includes into React Native's or the libraries' headers are left to the `precheck` step: SwiftPM plans the
generated package, the includes are resolved again with the App target's full include list, `swiftc -typecheck` checks
the Swift files and `clang -fsyntax-only` each C-family file with the generated manifest's flags, so an error in the
app's own sources stops the build before `xtool-build`. When a Swift file imports a module SwiftPM builds from Swift (a
Swift library, or one with Swift files next to its Objective-C), the Swift files are left to `xtool-build`, and so is a
C-family file that `@import`s such a module or one no module map of the package graph declares (an SDK module such as
CommonCrypto is left to xtool-build too). `build --skip-precheck` leaves that step out.
Each line and what to do:
[troubleshooting.md](troubleshooting.md#precheck).

## What is read from `project.pbxproj`

The single application target (several application targets or several `.xcodeproj` are an error naming them). From its
Debug configuration, then the project's:
The single application target (several application targets or several `.xcodeproj` are an error naming them). A target
that takes its files from an Xcode 16 synchronized folder is refused, by `build` and `doctor --project`, with `The app
target <name> takes its files from the synchronized folder <folder> (an Xcode 16 folder group); rn-xtool reads only
the files a target lists. Convert the folder to a group (Xcode: Convert to Group) so the target lists its files`. From
its Debug configuration, then the project's:

- `PRODUCT_BUNDLE_IDENTIFIER` (required; bare projects are never written to, so add it in Xcode or the pbxproj if it is
missing), `PRODUCT_NAME`, `MARKETING_VERSION`, `CURRENT_PROJECT_VERSION` and `INFOPLIST_FILE` (the `Info.plist`
Expand All @@ -213,7 +232,12 @@ Debug configuration, then the project's:
and `$(CONFIGURATION)` (`Debug`), the `:rfc1034identifier` and `:c99extidentifier` modifiers and settings defined in
the pbxproj itself (for example `$(PRODUCT_NAME)`) are resolved. Any other `$(VAR)` stops the build with `Cannot
resolve build setting` naming it. Relative paths in `HEADER_SEARCH_PATHS` and the bridging header are relative to
`ios/`. `.xcconfig` files are ignored.
`ios/`. `.xcconfig` files are not read: when the Debug configuration of the app target or of the project is based
on one, other than CocoaPods' `Pods-*.xcconfig`, that sets (itself or through its `#include` lines)
`HEADER_SEARCH_PATHS`, `GCC_PREPROCESSOR_DEFINITIONS`, `CLANG_CXX_LANGUAGE_STANDARD`, `SWIFT_OBJC_BRIDGING_HEADER`,
`PRODUCT_MODULE_NAME`, `CODE_SIGN_ENTITLEMENTS` or `INFOPLIST_FILE`, `build` prints `⚠ <file> sets <settings> for the
app target; rn-xtool does not read xcconfig files` and `doctor --project` the same line as `⚠ app-target — …`. Set
those values in the target's build settings ([details](troubleshooting.md#precheck)).

Not carried over: `IPHONEOS_DEPLOYMENT_TARGET` (the generated package always targets iOS 16.4, in Swift 5 language
mode), capabilities and script phases. When `OTHER_CFLAGS`, `OTHER_LDFLAGS` or `OTHER_SWIFT_FLAGS` hold flags beyond
Expand Down
3 changes: 2 additions & 1 deletion docs/design/plans/2026-11-06-alpha-8-fail-early.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,8 @@ its rulings R1–R13. This file lists the task groups and the failure-walk rows
exactly one owner. The tasks, their tests and the execution order are written next.

Plans: [plan 1, the podspec reader](2026-11-06-alpha-8-plan-1-podspec-reader.md) covers group A (rows 1–28), F1 (rows
104–108), F3 (rows 112–115) and records row 29 as deferred.
104–108), F3 (rows 112–115) and records row 29 as deferred; [plan 2, the precheck](2026-11-09-alpha-8-plan-2-precheck.md)
covers group B (rows 30–55), with the response-file capture (R12) as its Task 13.

Two gates come before the groups that depend on them:

Expand Down
Loading
Loading