Fix iOS CI simulator selection and docs

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: bmehta001

.github/workflows/build-ios-mac.yml

@@ -55,7 +55,7 @@ jobs:
     - name: build
       run: |
         if [[ "${{ matrix.os }}" == "macos-14" ]]; then
-          export IOS_DEPLOYMENT_TARGET=14.0;
+          export IOS_DEPLOYMENT_TARGET=13.0;
         elif [[ "${{ matrix.os }}" == "macos-15" ]]; then
           export IOS_DEPLOYMENT_TARGET=15.0;
         fi

README.md

@@ -94,6 +94,9 @@ Other resources to learn how to setup the build system:
 * **Supported** - these platforms are known to work well with the SDK in
     production.
 * **Covered by CI** - these platforms are tested as part of CI.
+* For iOS simulator, CI covers representative supported simulator
+  configurations on the current macOS runner images rather than every
+  supported iOS 12+ runtime.
 
 ## Test
 

build-tests-ios.sh

@@ -12,16 +12,74 @@ cd tests/unittests
 xcrun simctl list devices available
 echo 'End of xcrun simctl list devices available'
 
-# Resolve simulator UUID to avoid ambiguous destination matching.
-# Grab the last (newest OS) available device matching the requested name.
-SIM_ID=$(xcrun simctl list devices available | grep "$SIMULATOR" | grep -oE '[A-F0-9-]{36}' | tail -1)
+# Resolve simulator UUID from simctl JSON using an exact name match.
+# If the same device name exists across multiple iOS runtimes, pick the
+# newest runtime and fail if that runtime still contains duplicate matches.
+SIM_JSON=$(mktemp)
+cleanup_sim_json() {
+  rm -f "$SIM_JSON"
+}
+trap cleanup_sim_json EXIT
+xcrun simctl list devices available --json > "$SIM_JSON"
+SIM_MATCH=$(
+  python3 - "$SIMULATOR" "$SIM_JSON" <<'PY'
+import json
+import re
+import sys
+from pathlib import Path
+
+simulator_name = sys.argv[1]
+raw = Path(sys.argv[2]).read_text()
+json_start = raw.find('{')
+if json_start < 0:
+    print("ERROR: simctl did not emit JSON", file=sys.stderr)
+    raise SystemExit(1)
+
+devices_by_runtime = json.loads(raw[json_start:]).get("devices", {})
+matches = []
+for runtime, devices in devices_by_runtime.items():
+    if not runtime.startswith("com.apple.CoreSimulator.SimRuntime.iOS-"):
+        continue
+
+    match = re.search(r"iOS-(\d+)(?:-(\d+))?$", runtime)
+    if match is None:
+        continue
+
+    version = tuple(int(part) for part in match.groups(default="0"))
+    runtime_label = "iOS " + ".".join(str(part) for part in version)
+
+    for device in devices:
+        if device.get("name") == simulator_name and device.get("isAvailable", True):
+            matches.append((version, runtime_label, device["udid"]))
+
+if not matches:
+    print(f"ERROR: No available simulator found for '{simulator_name}'", file=sys.stderr)
+    raise SystemExit(1)
+
+newest_version = max(version for version, _, _ in matches)
+newest_matches = [(runtime_label, udid) for version, runtime_label, udid in matches if version == newest_version]
+
+if len(newest_matches) != 1:
+    print(f"ERROR: Multiple available simulators found for '{simulator_name}' in newest runtime:", file=sys.stderr)
+    for runtime_label, udid in newest_matches:
+        print(f"  - {runtime_label}: {udid}", file=sys.stderr)
+    raise SystemExit(1)
+
+runtime_label, udid = newest_matches[0]
+print(f"{udid}|{runtime_label}")
+PY
+)
+cleanup_sim_json
+trap - EXIT
+SIM_ID=${SIM_MATCH%%|*}
+SIM_RUNTIME=${SIM_MATCH#*|}
 
 if [ -z "$SIM_ID" ]; then
   echo "ERROR: No available simulator found for '$SIMULATOR'"
   exit 1
 fi
 
-echo "Using simulator: $SIMULATOR (id=$SIM_ID)"
+echo "Using simulator: $SIMULATOR ($SIM_RUNTIME, id=$SIM_ID)"
 
 xcodebuild test -scheme iOSUnitTests -destination "id=$SIM_ID"
 

docs/cpp-start-ios.md

@@ -16,12 +16,36 @@ Run `build-ios.sh [clean] [release|debug]` script in the root folder of the sour
 
 Run `build-ios.sh [clean] [release|debug] [arm64|arm64e]`.
 
+### Run iOS tests
+
+Run `./build-tests-ios.sh [release|debug] "<simulator name>"`.
+
+Example:
+
+```sh
+./build-tests-ios.sh release "iPhone 17"
+```
+
+Use a simulator name returned by `xcrun simctl list devices available`.
+The script resolves an exact device name from `simctl --json`, prefers the
+newest installed iOS runtime for that device name, and fails if that newest
+runtime still contains multiple matches.
+
+If Xcode reports that the requested simulator runtime is missing, install it
+from Xcode > Settings > Components or run
+`xcodebuild -downloadPlatform iOS -architectureVariant arm64`.
+
 ## 3. Integrate the SDK into your C++ project
 
-SDK package contains headers and library installed at the following locations:
+SDK package contains headers and library installed at the following locations
+by default:
 
 * Headers: /usr/local/include/mat
-* Library: /usr/local/lib/${arch}/libmat.a
+* Library: /usr/local/lib/libmat.a
+
+If you set a custom install prefix via
+`CMAKE_OPTS="-DCMAKE_INSTALL_PREFIX=/path/to/install"`, the SDK is installed
+under `<prefix>/include/mat` and `<prefix>/lib/libmat.a`.
 
 1DS SDK is built using cmake, but you can explore building it with any other build system of your choice.