Build iOS Binary

/build-ios-binary

Turns the extension's iOS source (ios/RCT<Pascal>Module.{h,m}) into the flat <Pascal>Plugin.framework/ (device slice) that the wrap runtime loads. iOS analogue of /build-android-binary: source in, a prebuilt framework out.

Ship a FLAT .framework, NOT an .xcframework. The wrap pipeline expects ios/<Name>.framework and does not descend into an .xcframework — shipping one fails with "Framework '<Name>.framework' not found in plugin." This skill builds the device archive only and copies out the flat .framework. See ppmplugin-format §5b.

Mac-only. Requires Xcode. On Linux/Windows this skill BLOCKs — Android-only contributors can't produce the iOS slice.

KNOWN LIMITATION — read this. The single hard part is React-Core: the framework compiles against React's headers (#import <React/RCTBridgeModule.h>) from the control repo's own pinned react-native devDep, while never embedding React — the wrap host provides it at runtime (weak-link). The coupling that matters is the RN version pin (0.79.7): it must match the RN the wrap host ships. The exact weak-link flags / header-search-path setup aren't yet validated against a live wrap host — that's the main risk area. React symbol/header errors mean the RN pin diverged from the host's RN, not a code bug.

Read shared/ppmplugin-format.md §5b (iOS binary requirements) and the naming-conventions.md iOS rows.

What this skill does NOT do

• Does not author manifest.json (run /generate-ppmplugin-manifest first — this skill reads it for cross-checks and the framework/moduleClass names).
• Does not zip the .ppmplugin — that's /assemble-ppmplugin.
• Does not build Android — that's /build-android-binary.
• Does not modify the canonical ios/ or the podspec — all adjustments live in a throwaway copy under ppmplugin/staging/ios-build/.
• Does not sign the framework — the wrap pipeline signs at packaging time (given BUILD_LIBRARY_FOR_DISTRIBUTION=YES SKIP_INSTALL=NO). No signing skill needed.

Step 1 — Read shared docs + prereq block

1. Read shared/shared-instructions.md and shared/ppmplugin-format.md.
2. Read ppmplugin/staging/manifest.json. If absent, STOP with NEEDS_CONTEXT: manifest.json missing — run /generate-ppmplugin-manifest first. If it has no entrypoints.ios, STOP with NEEDS_CONTEXT: manifest targets Android-only — re-run /generate-ppmplugin-manifest and choose iOS/Both.
3. Read the ## ppmplugin (third-party controls) block in .extension-state.md. Replace-existing gate: if ppmplugin/staging/ios/<framework>.framework already exists, surface it (with its build timestamp) and ask via AskUserQuestion — Keep existing (skip to Step 6) vs Replace (rebuild). Default Keep if source + manifest unchanged since the recorded build, else Replace (note Keep is stale). Per ppmplugin-format §1 replace-existing rule.
4. Run prereq checks and print the visible block (shared-instructions §9.2). Policy: resolve, don't punt (locate tools by path; offer + run safe installs):

Step 2 — React-Core source (self-contained) + confirm the config

The framework needs React's headers at compile time. The source is the control repo's own node_modules/react-native — the pinned react-native devDep (0.79.7 for pen-input), which ships the React headers (React/Base/RCTBridgeModule.h). The build is fully self-contained in the control repo. If the devDep isn't installed, run pnpm install; only if it's genuinely absent, ask the user for a react-native path.

Recommended: header-only React (no CocoaPods). Aggregate the React headers into a flat include dir in the staging copy and point the framework target at it — cleaner and faster than the Pod chain, and it avoids the CocoaPods/React-Codegen failures that bite under recent Xcode (see ppmplugin-format §5b):

mkdir -p ppmplugin/staging/ios-build/include/React
# copy the RN headers the module imports (Base + the Libraries it uses):
cp node_modules/react-native/React/Base/*.h        ppmplugin/staging/ios-build/include/React/
cp -R node_modules/react-native/React/Base node_modules/react-native/Libraries  ppmplugin/staging/ios-build/include/React/ 2>/dev/null || true

Then set on the framework target: HEADER_SEARCH_PATHS = $(inherited) $(SRCROOT)/include and OTHER_LDFLAGS = -undefined dynamic_lookup (weak-links React's symbols — the host provides them at runtime). -undefined dynamic_lookup is deprecated by Apple (works today, may break in a future Xcode — known caveat).

Fallback: CocoaPods — only if the header-only path doesn't suffice. A Podfile referencing the devDep (pod 'React-Core', :path => '<repo>/node_modules/react-native') gives CocoaPods the header map, but on recent Xcode/RN-0.79 you'll need post_install patches (boost URL, Yoga _pt, RCT-Folly clockid_t, boost std::unary_function) and may still hit the React-Codegen sandbox failure — all documented in ppmplugin-format §5b.

What matters either way is that the pinned RN version (0.79.7) matches the RN the wrap host ships at runtime (React is weak-linked, host-provided). Print the detected RN version and ask via AskUserQuestion to confirm / override the source + version before building. State plainly: "React is provided by the wrap host at runtime; React symbol/header errors at build or load mean the RN pin has diverged from the host's RN version."

Step 3 — Stage a standalone Xcode framework project (canonical ios/ stays pristine)

Like the Android build, work from a throwaway copy so the source the engineer maintains is never touched.

1. Copy ios/*.{h,m} → ppmplugin/staging/ios-build/Sources/ (fresh each run).

2. Generate the umbrella header ppmplugin/staging/ios-build/<Pascal>Plugin.h and mark it a Public header (build hygiene, not runtime-required — the wrap player dlopens the binary and uses NSClassFromString, it never imports the module, so the framework loads fine without a module map; the umbrella just silences the DEFINES_MODULE warning. Generate it anyway for a clean build). Minimal contents:

   #import <Foundation/Foundation.h>
   FOUNDATION_EXPORT double <Pascal>PluginVersionNumber;
   FOUNDATION_EXPORT const unsigned char <Pascal>PluginVersionString[];

3. Generate a standalone Xcode framework project ppmplugin/staging/ios-build/<Pascal>Plugin.xcodeproj, product/target name <Pascal>Plugin (= entrypoints.ios.framework), compiling the copied sources, with the umbrella as the Public header. Derive from the canonical podspec:

   • System frameworks to link: from the podspec s.frameworks (e.g. pen-input → PencilKit, UIKit, CoreGraphics, QuartzCore).
   • Deployment target: from s.platform (e.g. :ios, "14.0") — but floor it at the supported PAM shell minimum iOS 16.0.
   • xcodeproj-gem trap (if generating via the xcodeproj gem): when a group already carries its path (e.g. Sources), add file refs filename-only — new_group('Sources','Sources') + new_reference("Sources/<file>") doubles to Sources/Sources/<file> → file-not-found. Pin a known-good gen_project.rb rather than re-deriving it each run.

4. Set the build settings (each maps to a documented wrap/on-device failure — see ppmplugin-format §5b):

   Setting	Value
   Mach-O Type	Dynamic Library (NOT Static)
   Dead Code Stripping	NO (preserves the +moduleName class method and RCT_EXPORT_METHOD metadata the host reads after dlopen)
   Defines Module	YES
   Enable Bitcode	NO
   HEADER_SEARCH_PATHS	$(inherited) $(SRCROOT)/include (header-only React from Step 2)
   OTHER_LDFLAGS	-undefined dynamic_lookup (weak-link React; host-provided at runtime)
   BUILD_LIBRARY_FOR_DISTRIBUTION	YES
   SKIP_INSTALL	NO
   GENERATE_INFOPLIST_FILE	YES (REQUIRED — a framework with no Info.plist is rejected by the wrap codesign step)
   INFOPLIST_KEY_CFBundleDisplayName	<Pascal>Plugin
   MARKETING_VERSION	<version from manifest>
   CURRENT_PROJECT_VERSION	1
   PRODUCT_BUNDLE_IDENTIFIER	com.powerapps.<lowername>

The canonical ios/ + podspec are never modified — report the staging adjustments applied.