internationalcolorconsortium/iccdev/ios-manual-examples

Manual iOS Example Apps

Use this skill when changing examples/ios-apply-preview/**, examples/ios-benchapply/**, or shared documentation for manual iOS example apps.

Required Invariants

• Keep each helper, CMake bundle variable, README command, simulator launch,

and device launch aligned:

• apply preview: IccApplyPreviewPOC,

ICCDEV_APPLYPREVIEW_BUNDLE_IDENTIFIER, org.color.iccdev.ApplyPreviewPOC.

• bench apply: IccBenchApplyPOC,

ICCDEV_BENCHAPPLY_BUNDLE_IDENTIFIER, org.color.iccdev.BenchApplyPOC.

• CLUT editor: IccClutEditorPOC,

ICCDEV_CLUTEDITOR_BUNDLE_IDENTIFIER, org.color.iccdev.ClutEditorPOC.

• Build helpers must provide simulator and device targets, --open,

--run-tests, and --launch.

• Simulator runs must use `simctl launch --console-pty

--terminate-running-process` with code signing disabled.

• Device runs must use `devicectl device process launch --console

--terminate-existing --timeout, require TEAM_ID for command-line builds, require DEVICE_ID` for launch, and reject placeholder team or bundle IDs before building.

• Unsigned simulator helpers should ignore a globally exported placeholder

BUNDLE_ID and use the app's default bundle ID.

• All three apps must adopt UIScene lifecycle: a UIWindowSceneDelegate

that builds self.window from the connecting UIWindowScene, an Info.plist.in UIApplicationSceneManifest naming that delegate class, and an AppDelegate.application:configurationForConnectingSceneSession:options: that returns it. iOS 27 physical hardware raises a fatal SIGTRAP/EXC_BREAKPOINT in UIApplicationEvaluateRuntimeIssueForNoSceneLifecycleAdoption_block_invoke for apps without scene adoption; the iOS 18.x/26.x simulator runtimes available locally do not enforce this, so simulator-only QA can miss it.

• Keep generated Xcode projects and local signing data out of the repository.
• Do not add CTest or workflow registration unless a maintainer explicitly

requests it.

Validation

Use the smallest complete local gate for the changed example:

git diff --check
examples/ios-apply-preview/build-ios.sh simulator --run-tests
examples/ios-benchapply/build-ios.sh simulator --run-tests
examples/ios-clut-editor/build-ios.sh simulator --run-tests
doxygen .github/ci/doxygen/Doxyfile
test ! -s docs/generated/doxygen-warnings.log

For helper-only signing changes, also verify placeholder rejection before any device build starts:

TEAM_ID=ABCDE12345 examples/ios-apply-preview/build-ios.sh device
TEAM_ID=ABCDE12345 examples/ios-benchapply/build-ios.sh device
TEAM_ID=ABCDE12345 examples/ios-clut-editor/build-ios.sh device

Run physical-device checks with an unlocked paired device and real local signing values when hardware is available. Do not commit or print signing credentials beyond the non-secret team ID and bundle ID needed for the run.