Skip to content

Select the Android run target before building the app - #3158

Open
kattni wants to merge 12 commits into
beeware:mainfrom
kattni:android-prepare-target
Open

kattni wants to merge 12 commits into
beeware:mainfrom
kattni:android-prepare-target

Conversation

@kattni

@kattni kattni commented Nov 19, 2026

Copy link
Copy Markdown
Contributor

This PR depends on #3114, and should be merged after it. Until #3114 is merged, the diff here includes #3114's commits; the change specific to this PR is the last commit.

In review of #3114, the new RunCommand.prepare_target() hook was used so that iOS selects the target device before the (potentially slow) build. This PR makes Android use the same hook, for consistency.

GradleRunCommand.prepare_target() now does everything that might prompt the user or fail on device selection before the build starts:

  • selects the device or emulator (-d, -d auto, or the interactive selection menu);
  • if the user chose to create a new emulator, prompts for its name and creates it;
  • if an existing emulator isn't running, verifies its AVD (system image and skin).

The selected device ID, name and AVD are stored on the command, and run_app() uses them; run_app() no longer accepts device_or_avd. Starting a non-running emulator stays in run_app(), inside the existing --shutdown-on-exit handling, so a failed build doesn't leave a freshly started emulator running. Android builds don't depend on the target device, so (unlike iOS) no clone_options() is needed.

Behavior is otherwise unchanged; select_target_device() itself is untouched, so -d, auto, emulator creation from a JSON definition, unauthorized-device errors, and --no-input handling all behave as before - they just occur before the build.

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)

kattni added 12 commits October 29, 2026 18:35
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
- 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.
Move Android device and emulator selection (including creating a new
emulator, and verifying an existing AVD) into the RunCommand.prepare_target()
hook, so that any prompts or selection errors occur before the build,
consistent with iOS.
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.

1 participant