Skip to content

Add support for running iOS apps on physical devices - #3114

Open
kattni wants to merge 13 commits into
beeware:mainfrom
kattni:860-ios-device-deployment
Open

kattni wants to merge 13 commits into
beeware:mainfrom
kattni:860-ios-device-deployment

Conversation

@kattni

@kattni kattni commented Oct 30, 2026

Copy link
Copy Markdown
Contributor

Adds support for running iOS apps on physical devices (iOS/iPadOS 17+) from the command line.

  • Connected devices are listed alongside simulators when using -d; -d auto (the default) still selects a simulator.
  • When a device is selected, a development signing identity is selected (or provided with -i/--identity). The team ID is read from the certificate, and Xcode's automatic signing manages provisioning. A free Apple ID is sufficient.
  • Apps are built for the device, installed with devicectl, and launched with the console attached, so output, test results and Ctrl-C work as on other platforms.
  • build iOS also accepts -d and -i; without -d, the existing simulator build is used.
  • Adds an iOS code signing guide, and updates the iOS platform reference.

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:

  • I will abide by the BeeWare Code of Conduct
  • I have read and have followed the CONTRIBUTING.md file
  • This PR was generated or assisted using an AI tool

Assisted-by: Claude Code (Claude Opus 5.5)

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 freakboy3742 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 using prepare_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 --console option to simctl 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.

Comment thread src/briefcase/integrations/xcode.py Resolved
Comment thread docs/en/how-to/code-signing/iOS.md Resolved
Comment thread src/briefcase/integrations/xcode.py Outdated
f"Ignoring {name}; it is not paired with this Mac. Connect the "
"device, and tap Trust when prompted."
)
elif device["deviceProperties"]["developerModeStatus"] != "enabled":

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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"]`.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Comment thread src/briefcase/integrations/xcode.py Resolved
Comment thread src/briefcase/platforms/iOS/xcode.py Resolved
Comment thread src/briefcase/commands/run.py Resolved
- 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 freakboy3742 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 problem rather than not_ready when the device needs to report an issue
  • Providing a human-readable hint for simplifying usage when an identity is selected
  • Adding a __str__ method to iOSDevice, 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_app method

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!

Comment thread changes/860.feature.md Resolved
Comment thread docs/en/how-to/code-signing/iOS.md Resolved
- 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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add ability to run iOS app on a physical device

2 participants