Skip to content

feat: read podspecs with real Ruby (alpha.8, plan 1) - #37

Merged
WillyAntunez merged 53 commits into
mainfrom
feature/alpha-8-podspec-reader
Nov 9, 2026
Merged

WillyAntunez merged 53 commits into
mainfrom
feature/alpha-8-podspec-reader

Conversation

@WillyAntunez

Copy link
Copy Markdown
Owner

Read podspecs with real Ruby (alpha.8, plan 1)

The rn-spm step now reads every library's podspec with the system Ruby, through a shim of CocoaPods' DSL and React Native's podspec helpers, so a podspec gives the same fields on Linux as under CocoaPods on a Mac. Without a usable Ruby, the reduced reader of earlier releases reads it, and the build says so.

Design: docs/design/specs/2026-11-06-alpha-8-fail-early-design.md (A, with its 2026-11-09 amendments). Plan: docs/design/plans/2026-11-06-alpha-8-plan-1-podspec-reader.md.

What users get

  • Podspecs read as CocoaPods reads them. install_modules_dependencies, defined? and respond_to? answer as under React Native's Podfile, and a library's own Ruby and node scripts run: react-native-gesture-handler 3.3.0 gets RNGH_USE_WORKLETS=1 beside react-native-worklets, and react-native-webview 14.0.1 takes its install_modules_dependencies branch. pod ipc spec is no longer run.
  • ios attributes apply. s.ios.exclude_files, ss.ios.dependency and the like are merged over the spec and each subspec the scaffold uses; other platforms' attributes are never read.
  • One Ruby, a fixed environment, 120 s. Every podspec runs with the interpreter of the first ruby on PATH, by its absolute path, so a version manager's shim cannot switch Ruby per folder; in the podspec's folder; with PATH, HOME, LANG, RCT_NEW_ARCH_ENABLED=1 and RCT_HERMES_V1_ENABLED=1 only; for at most 120 s.
  • No silent fallback. A podspec Ruby cannot read stops rn-spm with the podspec, its line and the reason, also when autolinking reads it for header search paths, on React Native 0.88 and in the copy used for 0.85–0.87 and Expo SDK 57. A gap of the reader, a timeout, a Ruby that ends without a result, rn-xtool's own failure to run the read and a key not found from ENV.fetch end with the escape: RN_XTOOL_PODSPEC_READER=reduced reads with the reduced reader for one run, and a ⚠ line names it.
  • Libraries rn-xtool cannot scaffold are named. A podspec that calls spm_dependency is refused by name; one that sets script_phases, prepare_command, info_plist or module_map gets a ! line.
  • Ruby in doctor and setup. ✔ ruby — 3.3.8, or a ⚠ with the reason. The install command (sudo apt install ruby) is given when Ruby is missing or older than 2.7; for another reason (no json, a Ruby that cannot run the reader, the shim missing) the line names it and links the troubleshooting page. setup never installs Ruby.
  • Scaffold markers and reports. Each scaffolded Package.swift names its reader; the patches step warns about a persisted scaffold the other reader wrote. doctor --report has ruby:, podspec reader: and, when a podspec read environment variables, podspec ENV:.

Upgrading from 0.1.0-alpha.7

  • Install Ruby 2.7 or newer (sudo apt install ruby) before the first build with this release.
  • On React Native 0.88 (bare, and Expo SDK 58), the first build stops at patches with the stale-patch message: the bundled react-native patch changed (a new scripts/spm/read-podspec-shim.rb, a rewritten scripts/spm/read-podspec.js). Run rm -rf node_modules/react-native && npm install, then build again.
  • The scaffolder is now revision 8: each persisted scaffold patch gets the "older rn-xtool scaffolder" warning until it is deleted and regenerated (with Ruby installed).

How it was proven

  • The reader sweep (tests/podspecReaderSweep.test.ts): 77 library and React Native pairs, 82 podspecs (the 30 most-downloaded libraries with an iOS podspec, the trial's failing versions, the Expo SDK 57 and 58 templates' and the reference apps' libraries, and gesture-handler 3.3.0 with worklets installed beside it), each read with Ruby and with the reduced reader against a reviewed golden. About a minute locally with every tarball cached.

  • The shim's tests run on Ruby 2.7 in CI (shim-ruby-floor), and a drift test checks the shim's min_ios_version_supported and folly values against every cached React Native line.

  • Build-only runs of the reference apps with the new reader (no device), total time and the rn-spm step's share:

    • bare React Native 0.88.1: 260 s (64 s);
    • Expo SDK 58: 276 s (64 s);
    • bare React Native 0.86.3: 356 s (43 s);
    • bare React Native 0.87.1: 274 s (106 s);
    • bare React Native 0.85.0: 203 s (73 s);
    • Expo SDK 57: 80 s (31 s; its template has no library to scaffold);
    • bare React Native 0.88.1 with RN_XTOOL_PODSPEC_READER=reduced: 262 s (38 s), exactly one ⚠ line, every marker reduced.

    No reader stop, every read ok, markers ruby and revision 8 everywhere; Ruby costs about 64 ms per podspec.

  • Without Ruby, rn-xtool doctor and doctor --project print the ⚠ ruby — not found line.

  • npm test: 2676 passed, 6 skipped (environment: real slots, a device, the e2e app, the CI-only check); npm run lint and npm run scan:private are clean.

Merge gate

  • CI green, including shim-ruby-floor.
  • The maintainer's own test: the packed tarball installed locally and built with his app.

Maintainer notes

  • The recipe in docs/RELEASING.md that regenerates the 0.88 patches now gives a new file's header the a/ side patch-package reads (before, patch-package refused the whole patch), and runs the main reverse patch with --no-backup-if-mismatch, so no .orig file lands in the diff.
  • skia's three prebuilt packages (about 530 MB) are an optional heavy tier of tests/tarballs.json: RN_XTOOL_FETCH_HEAVY=1 node scripts/fetch-test-tarballs.mjs fetches them, the sweep skips skia with a named reason without them, and CI does not fetch them.
  • The scaffold golden reads ../app-golden beside the repo (or RN_XTOOL_REF_APP).
  • tests/mentions.test.ts checks the tracked Markdown; the Mentions workflow checks a pull request's description, and npm run check:mentions -- <file> checks a draft like this one.

@WillyAntunez
WillyAntunez merged commit 85ccec8 into main Nov 9, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant