Skip to content

Document iOS build prerequisites in README #6

Description

@dnorman

Summary

Building the iOS app on a fresh machine (especially Xcode 26) has several prerequisites that aren't documented and produce confusing failures when missing.

To document

  • Node path for Xcode script phases — resolved via ios/.xcode.env (command -v node) with an optional ios/.xcode.env.local override. A stale .xcode.env.local (e.g. pointing at a removed nvm version) makes every RN script phase fail; because the Hermes "Replace Hermes" phase runs first, it looks like a Hermes problem when it's really "node not found". Document how to set it and this failure mode.
  • Xcode 26 / iOS 26 SDK — the fmt consteval issue and the Podfile post_install patch that works around it (link the RN-upgrade issue).
  • CocoaPods locale — under a non-UTF-8 locale, pod install can crash with Unicode Normalization not appropriate for ASCII-8BIT (Encoding::CompatibilityError). Run with LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8.
  • Simulatordev.sh matches iPhone 16 (; document creating that sim (or relaxing the match to accept e.g. iPhone 16e).
  • Maestro e2e — requires Java 17 (JAVA_HOME=/opt/homebrew/opt/openjdk@17) plus the maestro CLI on PATH.

Acceptance

  • README has a "Building / prerequisites" section covering the above

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions