Repository navigation
Conversation
Physical devices discovered with devicectl are offered alongside simulators in the -d device picker, grouped by iOS version, and can be selected by hardware UDID or name. Automatic (-d auto) selection is unchanged, and only considers simulators.
The development team ID is read from the organizational unit of the identity's certificate, as the suffix in an Apple Development certificate's name identifies the team member, not the team. Identities can be selected by fingerprint or name, or chosen from a list of development identities.
Run commands now have a prepare_target() hook, invoked before deciding whether the app needs to be built. On iOS, it selects the target device and, for a physical device, the development signing identity (which can be provided with -i/--identity). Physical devices use a separate binary path, and always trigger a build so that Xcode signs the app with the selected identity.
build iOS now accepts -d/--device and -i/--identity; without -d, the existing simulator build is used. Physical device builds use Xcode's automatic signing and provisioning with the selected identity's team, and target the selected device so that it can be registered if needed.
Apps are installed with devicectl, and launched with the console attached, so the app's output is streamed (with NSLog prefixes removed) until the app exits. BRIEFCASE_CONSOLE_OUTPUT is set so the app launcher can send Python output to the console, and the debugger uses the device's app packages.
Adds an iOS code signing guide covering development certificates, free Apple IDs, device pairing, Developer Mode and trusting the developer profile, and documents the -d/-i options, device deployment workflow and troubleshooting in the iOS platform reference.
A device that is paired, but isn't connected by cable or on the same network, is reported with instructions, rather than offered as a target.
A launch failure can't be distinguished from the app failing, so errors from running on a physical device point to a locked device or an untrusted developer certificate, and the deployment documentation.
…ios-device-deployment # Conflicts: # src/briefcase/platforms/iOS/xcode.py # tests/platforms/iOS/xcode/mixin/test_select_target_device.py
freakboy3742
left a comment
There was a problem hiding this comment.
I've done an initial review of this; it's really impressive.
- There's a couple of edge cases around device discovery that I've flagged inline
- I'm not sure the workflow around device selection is correct. This follows the original spec suggested in the ticket (integrating devices with simulators); after trying it, I'm not sure that's the best approach. On my setup, I was presented with 4 iOS versions; I can't say I know off the top of my head that my phone is running iOS 26.6.2, but that is what I had to select to get my phone. It may be better to provide the user an initial list of options of each simulator iOS version, plus a final option of "physical devices" if any physical devices were found. If no physical devices exist, they just get the list of iOS versions; and if there's only one iOS version, and no physical devices then the single iOS simulated iOS version is selected automatically
- The "not ready for running" device handling is also slightly inconsistent with how Android handles the problem. Rather than output warnings for all the "not ready" devices while processing the list, Android displays all devices, but if the user selects that device, a helper message is provided describing the next step for enabling that device (e.g., how to turn on developer mode"). This probably means the iOSDevice object gains flags to track "not ready" devices, which are converted into errors if that device is selected; the label for those devices may also be able to share some small detail about device readiness (e.g., "My iPhone (development mode not enabled)")
- The
prepare_target()workflow is a nice improvement because it causes the device to be selected before the build (which is potentially the slow action). It would be nice to have the same workflow on Android, so that we're usingprepare_target()consistently for simulator selection. - The modifications to handle launching on a physical device are great - but I can't help but think that we've missed an opportunity to massively simplify things. In the process of poking around this, I discovered the
--consoleoption tosimctl launch, which I think puts simulators on the same footing as physical devices with regarding output handling. If that works, we should be able to turn off system logging entirely in iOS apps, and fall back on raw console logs. This should simplify the code paths around physical devices, since they'll be using the same logging scheme; and also be more reliable, as it doesn't rely on filtering the system log (which can drop logging frames if the machine is busy.
| f"Ignoring {name}; it is not paired with this Mac. Connect the " | ||
| "device, and tap Trust when prompted." | ||
| ) | ||
| elif device["deviceProperties"]["developerModeStatus"] != "enabled": |
There was a problem hiding this comment.
I got an exception on this line because [developerModeStatus] didn't exist in the deviceProperties dictionary on a simulated device. In digging into the problem, I found this block at the start of the JSON for every device:
"_deprecationNotice" : {
"deprecatedFields" : [
"hardwareProperties",
"deviceProperties",
"connectionProperties"
],
"message" : "The 'hardwareProperties', 'deviceProperties', 'connectionProperties' fields are deprecated and will be removed in a future release. Use the 'properties' dictionary instead.",
"replacement" : "properties"
},
From the look of it, the new keys for a usable device are:
device["properties"]["connection"]["paringState"] == "paired"
device["properties"]["software"]["developerModeStatus"].get("enabled",{}}.get("mode", 0) == 1
device["properties"]["connection"]["state"] == "connected"
and will return the OS version as device["properties"]["software"]["osVersionNumber"][ stringValue"], and the device name as device["properties"]["state"]["name"]`.
There was a problem hiding this comment.
Simulated devices are now skipped, and missing keys no longer raise. Each device is read from the deprecated dictionaries when they are present, falling back to properties. For reachability in the new layout I used connection.state != "unavailable" rather than == "connected", because an idle device that is still reachable reports disconnected in the old layout. I only have Xcode 26 here, so the properties fixture was put together from your description and other projects' parsers. Could you share an anonymized xcrun devicectl list devices --json-output - from Xcode 27, so I can replace it with real output?
- Read devicectl's JSON from stdout, rather than a temporary file. - Ignore simulated devices, and support the `properties` layout that Xcode 27 introduced, falling back from the deprecated dictionaries. - Offer physical devices as a "Physical devices" option alongside the simulator iOS versions. - List devices that aren't ready with the reason, and explain how to fix the problem if one is selected, instead of warning and omitting them. - Build for an automatically selected simulator by default. - Decide whether to build based on whether the binary for the selected target exists, rather than always building for a physical device.
* Rename the 'not-ready' field 'problem' * Provide a hint for selecting a developer identity * Add a __str__ to iOSDevice, to simplify other console output * Refactor the code path for running on a simulator * Simplify the invocation of apps on the simulator.
freakboy3742
left a comment
There was a problem hiding this comment.
This is looking really good, and works great in my testing.
I've pushed a couple of updates; most of them are fairly minor:
- A bike-shed change: Naming the field
problemrather thannot_readywhen the device needs to report an issue - Providing a human-readable hint for simplifying usage when an identity is selected
- Adding a
__str__method toiOSDevice, which simplifies usage in status messages (and allows cleaning up the grammar when referencing a physical device - I was seeing messages like "Starting app on an Russell's iPhone ..." - Refactoring the branch of simulator execution so that there's a clear "if physical: run_physical(); else run_simulator", rather than physical short-cutting the
run_appmethod
The one more substantive change is around simulator execution. In my previous review, I noted that --console could be usable to simplify simulator launch. I've made that modification in this branch. The app will still need the ability to write to the unified log by default - but the ability to turn on console logging with an environment variable as you've done here (and in the corresponding template) will meet that requirement.
I haven't updated the tests to reflect these changes (other than the simple rename for not_ready); if you can update the failing tests to reflect the updated behavior, and update the Briefcase template PR to hard-remove the use of the system logger, this should be ready to merge!
- Update the simulator run tests for launching with `simctl launch --console`, and remove the tests for parsing the app's PID. - Remove error handling and an environment branch that can no longer be reached. - Include "iOS" in the description of a simulator. - Shorten the changelog entry.
Adds support for running iOS apps on physical devices (iOS/iPadOS 17+) from the command line.
-d;-d auto(the default) still selects a simulator.-i/--identity). The team ID is read from the certificate, and Xcode's automatic signing manages provisioning. A free Apple ID is sufficient.devicectl, and launched with the console attached, so output, test results and Ctrl-C work as on other platforms.build iOSalso accepts-dand-i; without-d, the existing simulator build is used.Python output on a device requires beeware/briefcase-iOS-Xcode-template#94; the template revision will need to be updated once it is merged.
Fixes #860
PR Checklist:
Assisted-by: Claude Code (Claude Opus 5.5)