From 2de484baf7bf379753c3073f40da3a178b2918a0 Mon Sep 17 00:00:00 2001 From: Tom Brow Date: Fri, 16 Oct 2026 10:35:43 -0700 Subject: [PATCH] docs(ios): document Xcode 27 development setup (#8400) Document Xcode 27.0 as the recommended iOS development toolchain while retaining Xcode 26 compatibility. Explain per-command selection, the known Flutter native-assets compiler/SDK mismatch on hosts with multiple Xcode versions, and where CI and release toolchains are configured. The compatibility changes are already merged in [#8379](https://github.com/block/buzz/pull/8379) and [#8398](https://github.com/block/buzz/pull/8398). Related open work is [#8330](https://github.com/block/buzz/pull/8330); this PR changes documentation only. The release version bump remains separate in [buzz-releases#110](https://github.com/squareup/buzz-releases/pull/110). ### Validation - Ordinary unsigned Release build passed on [main at 73962435b](https://github.com/block/buzz/commit/73962435b6dd7c67b29e650e4f11ae8efcd9af5d) with exact Xcode 27.0 (27A266a), the pinned Flutter SDK, and normal CocoaPods installation. Buzz.app contains NotificationService.appex. No dependency patches or plugin-validation bypasses were used. - The merged direct-C change passed native tests on Xcode 26.5 and 27.0, full local CI, and hosted Native and unsigned Release validation. This documentation-only follow-up preserves that code. - Documentation diff checks and local pre-push checks passed. --------- Signed-off-by: Tom Brow --- CONTRIBUTING.md | 1 + mobile/README.md | 28 ++++++++++++++++++++++++++++ 2 files changed, 29 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dbe4ba5dd2..c761fab9c1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -84,6 +84,7 @@ We review as capacity allows — focused PRs that follow this guide move fastest | Node.js | 24+ | Required for desktop app commands and `just ci` | | pnpm | 10+ | Required for desktop app commands and `just ci` | | Flutter | 3.41+ | Required for mobile app — install via [flutter.dev](https://docs.flutter.dev/get-started/install) | +| Xcode | 27.0 recommended; 26 supported | Required for iOS builds; see [iOS toolchain setup](mobile/README.md#ios-toolchain) | | Docker | 24+ | For Postgres, Redis, MinIO | | `just` | latest | Task runner — `cargo install just` | | `lefthook` | 2.1.3 (Hermit-pinned) | Auto-installed by `just hooks` — no manual install needed | diff --git a/mobile/README.md b/mobile/README.md index b447a7fbe6..c2e7e6f4aa 100644 --- a/mobile/README.md +++ b/mobile/README.md @@ -21,6 +21,34 @@ external Flutter SDK has touched `mobile/.dart_tool`, rerun `mobile-install` with the pinned SDK before building so `flutter_test`, `sky_engine`, and the engine all come from the same Flutter version. +### iOS toolchain + +Use Xcode 27.0 for iOS development and build validation on an Apple silicon +Mac running macOS Tahoe 26.6 or later, as required by the +[Xcode 27 release notes](https://developer.apple.com/documentation/xcode-release-notes/xcode-27-release-notes). +On Intel Macs or hosts that cannot meet those requirements, use a compatible +Xcode 26 version, which remains supported. Activate the repository's pinned +Flutter SDK with Hermit as described above. + +When multiple Xcode versions are installed, select the intended version for +the command with `DEVELOPER_DIR`, for example: + +```bash +DEVELOPER_DIR=/Applications/Xcode-27.0.0.app/Contents/Developer xcodebuild -version +``` + +Adjust the path to your installation. Keep the compiler and SDK from the same +Xcode installation. The pinned Flutter native-assets tooling can discover the +globally selected SDK even when `DEVELOPER_DIR` selects another compiler, so +use a build machine with a matching default Xcode when validating either +Xcode 26 or Xcode 27. + +The native cryptography dependency is pinned upstream C source in +`ios/BuzzPushKit/Sources/CSecp256k1`; it requires no Swift build-plugin approval. +GitHub's mobile CI currently uses the Xcode default of its `macos-latest` +runner. The internal release toolchain is configured separately in +[buzz-releases](https://github.com/squareup/buzz-releases). + ## Run ```bash