iOS 17.2 Simulator: black screen/crash fixed by rebuilding SDL2; doc & scripts inside -- (iOS 17.5 Simulator still problematic)

[wolfgang-coder]

iOS 17.x Simulator (15.4 toolchain): black screen / launch exit — fixed by rebuilding SDL2 and adjusting build flags (docs + scripts inside)

TL;DR
On a clean macOS 14.7.6 + Xcode 15.4 host (MacStadium M2), a pure Kivy “Hello World” app:

• fails on some iOS 17.x simulator runtimes (black screen or immediate exit),
• works reliably after (a) rebuilding SDL2 from source (no cached/prebuilt) and (b) removing OTHER_CFLAGS="-Umain -DSDL_MAIN_HANDLED" from xcodebuild flags.
  iOS 17.2 runtime is stable; 17.5 still shows flaky simulator behavior (OpenGL ES/EAGL path).
  Full write-up + scripts below.

---

Environment

• Host: macOS 14.7.6 (Apple M2, MacStadium), Xcode 15.4
• Python: 3.10.12 (venv)
• kivy-ios: 2025.5.17 @ cce9545
• Kivy: 2.3.1
• SDL2: 2.28.5 (rebuilt locally via recipe)
• Simulator runtimes: iOS 17.2 (✅ stable), iOS 17.5 (⚠️ problematic)
• Real device: not fully verified yet (TestFlight still pending review)

Symptoms

• On iOS 17.x simulator, app exits right after launch (exit code 0) or shows black screen.
• With OTHER_CFLAGS="-Umain -DSDL_MAIN_HANDLED" the app crashes with:

  “Application didn't initialize properly with message: did you include SDL_main.h in the file containing your main() function?”

What fixed it

1. Rebuild SDL2 from source (no cached/prebuilt) using kivy-ios recipe, and ensure:
   • No “Cached result/Skipping/Ignoring” in toolchain logs for SDL2.
   • The generated fat libs actually contain the UIKit OpenGL view object(s).
2. Remove OTHER_CFLAGS="-Umain -DSDL_MAIN_HANDLED" from xcodebuild flags.
3. Optional (works well on sims): In the SDL2 UIKit view, force RGBA8 + retained backing + opaque YES (idempotent inline patch).
   • This mitigated the “black screen” path for us on 17.2 sims.

Note: After a deep clean and explicit rebuild of SDL2 on the target host/SDK, even the unpatched SDL2 recipe worked on 17.2 for us. That suggests the root cause was likely stale or mismatched prebuilt artifacts rather than a strict upstream bug. The RGBA8+retained+opaque tweak still seems like a pragmatic improvement for simulator stability.

Repro (minimal)

• Pure Kivy app, single Label, set Window.clearcolor=(0.2,0.6,0.9,1).
• Build via kivy-ios toolchain, then xcodebuild for iphonesimulator:
  • Do not pass OTHER_CFLAGS="-Umain -DSDL_MAIN_HANDLED".
  • Provide OTHER_LDFLAGS (static libs), EXCLUDED_ARCHS="i386 x86_64", etc.
• Install/launch to a fresh iOS 17.2 simulator → ✅ works (after SDL2 rebuild).
• Same flow on iOS 17.5 → may still exit silently (simulator quirk).

Why removing -Umain -DSDL_MAIN_HANDLED matters

That flag combo overrides SDL’s main wiring and triggers the SDL_main error path on iOS simulator with Kivy. Removing it allowed SDL/Kivy bootstrap to proceed normally.

Scripts & docs (ready to use)

• ReadMe__Kivy_iOS17_Simulator_Fixes_and_goldenPath.md
  View: https://gist.github.com/wolfgang-coder/7e88636fb3f19b492d565e982575939d#file-ReadMe__Kivy_iOS17_Simulator_Fixes_and_goldenPath-md
  Raw : https://gist.githubusercontent.com/wolfgang-coder/7e88636fb3f19b492d565e982575939d/raw/ReadMe__Kivy_iOS17_Simulator_Fixes_and_Workflow.md

• sdl2_recipe__init__patched__rgba8_fix.py
  View: https://gist.github.com/wolfgang-coder/7e88636fb3f19b492d565e982575939d#file-sdl2_recipe__init__patched__rgba8_fix-py
  Raw : https://gist.githubusercontent.com/wolfgang-coder/7e88636fb3f19b492d565e982575939d/raw/sdl2_recipe__init__patched__rgba8_fix.py

• python3_recipe__init__patched__preserve_libpython.py
  View: https://gist.github.com/wolfgang-coder/7e88636fb3f19b492d565e982575939d#file-python3_recipe__init__patched__preserve_libpython-py
  Raw : https://gist.githubusercontent.com/wolfgang-coder/7e88636fb3f19b492d565e982575939d/raw/python3_recipe__init__patched__preserve_libpython.py

• sdl2_patch_verify.sh
  View: https://gist.github.com/wolfgang-coder/7e88636fb3f19b492d565e982575939d#file-sdl2_patch_verify-sh
  Raw : https://gist.githubusercontent.com/wolfgang-coder/7e88636fb3f19b492d565e982575939d/raw/sdl2_patch_verify.sh

• simulator_device_UDID_and_Setup.sh
  View: https://gist.github.com/wolfgang-coder/7e88636fb3f19b492d565e982575939d#file-simulator_device_UDID_and_Setup-sh
  Raw : https://gist.githubusercontent.com/wolfgang-coder/7e88636fb3f19b492d565e982575939d/raw/simulator_device_UDID_and_Setup.sh

• simulator_device_list_clean.sh
  View: https://gist.github.com/wolfgang-coder/7e88636fb3f19b492d565e982575939d#file-simulator_device_list_clean-sh
  Raw : https://gist.githubusercontent.com/wolfgang-coder/7e88636fb3f19b492d565e982575939d/raw/simulator_device_list_clean.sh

Open questions / feedback wanted

• Does kivy-ios still ship or prefer prebuilt SDL2 artifacts in some flows that could mismatch with Xcode 15.4/SDK 17.x?
• Would you consider adopting the RGBA8 + retained + opaque defaults for the simulator build config?
• Any known iOS 17.5 sim regressions you’re tracking (OpenGL ES/EAGL swap/visibility issues)?

Thanks a lot for maintaining kivy-ios! Happy to A/B test patches or provide additional logs if helpful.

[wolfgang-coder]

TL;DR (Kivy on iOS 17.x Simulator)

• Fix: Clean rebuild of SDL2 (no cached artifacts), then build python/kivy/app + xcodebuild without option -Umain -DSDL_MAIN_HANDLED + iOS 17.2 Simulator (17.5 still problematic with OpenGL/EAGL-problems).
• Tested: macOS 14.7.6, Xcode 15.4, runtimes iOS 17.2/17.5, kivy-ios 2025.5.17 @ cce9545, Kivy 2.3.1, SDL2 2.28.5.

Quick checklist

1. deep clean:

   ⚠️ Make sure $KIVYIOS_ROOT, $APP_NAME, $PROJECTS are set correctly before running destructive commands.

   rm -rf "$KIVYIOS_ROOT/build" "$KIVYIOS_ROOT/dist" "$KIVYIOS_ROOT/.kivy-ios*" "$HOME/.kivy-ios" "$KIVYIOS_ROOT/${APP_NAME}-ios" "$HOME/Library/Developer/Xcode/DerivedData/${APP_NAME}-*"

2. toolchain clean hostpython3 python3 sdl2 kivy (derived data etc.).

3. toolchain build sdl2 → followd with toolchain build python3 kivy … → then toolchain build <app>.

4. xcodebuild:
   without OTHER_CFLAGS="-Umain -DSDL_MAIN_HANDLED".
   Set: ONLY_ACTIVE_ARCH=YES, EXCLUDED_ARCHS="i386 x86_64", IPHONEOS_DEPLOYMENT_TARGET=16.0.

5. Simulator via Script: iOS 17.2 allocate/boot/get UDID; then simctl install/launch.

6. Optional, but helpful: SDL2 RGBA8 + opaque + retained Backing (idempotenter Patch/Inline-Fix).

Gists (Scripts/Recipes)

• README & scripts: https://gist.github.com/wolfgang-coder/7e88636fb3f19b492d565e982575939d
  (including: simulator_device_ensure_17_2_udid.sh, Cleaner, SDL2-Recipe-Fix, Python-Recipe-Fix)

Status iOS 17.5 Simulator

• 17.5 still problematic with OpenGL ES/EAGL symptoms: showing black screen or exit without crash dialog
  Workaround: use 17.2 or real device.

Note

• Don’t post certificates, bundle IDs, or real UDIDs..
• If you reproduce or fix related issues on 17.5+, please add your environment and steps here to help others.