Use devicectl to install and launch *_application targets on a physical device (#2527)

In Xcode 15, Apple introduced a new command-line tool that allows
management of physical devices. This makes it possible to install and
launch *_application targets on a physical device without third-party
solutions.

With these changes, you can now use `bazel run //:iOSApp
--ios_multi_cpus=arm64`.

Previously, this command would attempt to launch the application on a
simulator and fail due to an invalid architecture.

Bazel currently lacks a specific flag for specifying device identifiers
suitable for this purpose. I created a [PR to
Bazel](bazelbuild/bazel#23599) introducing an
`--ios_device` flag. However, it's unlikely to be accepted since it's a
platform-specific flag. If it is accepted, we can utilize it in the
future.

For the current implementation, I added astring_flagthat allows passing
a device identifier. It can be used like
this:--@build_bazel_rules_apple//apple/build_settings:ios_device=<uuid|ecid|serial_number|udid|name|dns_name&gt;
.
---------

Signed-off-by: Vadim Smal <vadims@spotify.com>
Co-authored-by: Luis Padron <heyluispadron@gmail.com>
Co-authored-by: Brentley Jones <github@brentleyjones.com>

Author: 3 people

apple/build_settings/build_settings.bzl

@@ -38,6 +38,14 @@ Enables Bazel's tree artifacts for Apple bundle rules (instead of archives).
 """,
         default = False,
     ),
+    "ios_device": struct(
+        doc = """
+The identifier, ECID, serial number, UDID, user-provided name, or DNS name
+of the device for running an iOS application.
+You can get a list of devices by running 'xcrun devicectl list devices`.
+""",
+        default = "",
+    ),
 }
 
 _BUILD_SETTING_LABELS = {

apple/internal/ios_rules.bzl

@@ -468,20 +468,33 @@ def _ios_application_impl(ctx):
         label_name = label.name,
     )
 
-    # TODO(b/254511920): Consider creating a custom build config for iOS simulator device/version.
-    run_support.register_simulator_executable(
-        actions = actions,
-        bundle_extension = bundle_extension,
-        bundle_name = bundle_name,
-        label_name = label.name,
-        output = executable,
-        platform_prerequisites = platform_prerequisites,
-        predeclared_outputs = predeclared_outputs,
-        rule_descriptor = rule_descriptor,
-        runner_template = ctx.file._runner_template,
-        simulator_device = ctx.fragments.objc.ios_simulator_device,
-        simulator_version = ctx.fragments.objc.ios_simulator_version,
-    )
+    if platform_prerequisites.platform.is_device:
+        run_support.register_device_executable(
+            actions = actions,
+            bundle_extension = bundle_extension,
+            bundle_name = bundle_name,
+            label_name = label.name,
+            output = executable,
+            platform_prerequisites = platform_prerequisites,
+            predeclared_outputs = predeclared_outputs,
+            rule_descriptor = rule_descriptor,
+            runner_template = ctx.file._device_runner_template,
+            device = apple_xplat_toolchain_info.build_settings.ios_device,
+        )
+    else:
+        run_support.register_simulator_executable(
+            actions = actions,
+            bundle_extension = bundle_extension,
+            bundle_name = bundle_name,
+            label_name = label.name,
+            output = executable,
+            platform_prerequisites = platform_prerequisites,
+            predeclared_outputs = predeclared_outputs,
+            rule_descriptor = rule_descriptor,
+            runner_template = ctx.file._simulator_runner_template,
+            simulator_device = ctx.fragments.objc.ios_simulator_device,
+            simulator_version = ctx.fragments.objc.ios_simulator_version,
+        )
 
     archive = outputs.archive(
         actions = actions,
@@ -773,20 +786,33 @@ def _ios_app_clip_impl(ctx):
         label_name = label.name,
     )
 
-    # TODO(b/254511920): Consider creating a custom build config for iOS simulator device/version.
-    run_support.register_simulator_executable(
-        actions = actions,
-        bundle_extension = bundle_extension,
-        bundle_name = bundle_name,
-        label_name = label.name,
-        output = executable,
-        platform_prerequisites = platform_prerequisites,
-        predeclared_outputs = predeclared_outputs,
-        rule_descriptor = rule_descriptor,
-        runner_template = ctx.file._runner_template,
-        simulator_device = ctx.fragments.objc.ios_simulator_device,
-        simulator_version = ctx.fragments.objc.ios_simulator_version,
-    )
+    if platform_prerequisites.platform.is_device:
+        run_support.register_device_executable(
+            actions = actions,
+            bundle_extension = bundle_extension,
+            bundle_name = bundle_name,
+            label_name = label.name,
+            output = executable,
+            platform_prerequisites = platform_prerequisites,
+            predeclared_outputs = predeclared_outputs,
+            rule_descriptor = rule_descriptor,
+            runner_template = ctx.file._device_runner_template,
+            device = apple_xplat_toolchain_info.build_settings.ios_device,
+        )
+    else:
+        run_support.register_simulator_executable(
+            actions = actions,
+            bundle_extension = bundle_extension,
+            bundle_name = bundle_name,
+            label_name = label.name,
+            output = executable,
+            platform_prerequisites = platform_prerequisites,
+            predeclared_outputs = predeclared_outputs,
+            rule_descriptor = rule_descriptor,
+            runner_template = ctx.file._simulator_runner_template,
+            simulator_device = ctx.fragments.objc.ios_simulator_device,
+            simulator_version = ctx.fragments.objc.ios_simulator_version,
+        )
 
     archive = outputs.archive(
         actions = actions,
@@ -2544,6 +2570,7 @@ ios_application = rule_factory.create_apple_rule(
             allowed_families = rule_attrs.defaults.allowed_families.ios,
             is_mandatory = True,
         ),
+        rule_attrs.device_runner_template_attr(),
         rule_attrs.infoplist_attrs(),
         rule_attrs.ipa_post_processor_attrs(),
         rule_attrs.launch_images_attrs(),
@@ -2656,6 +2683,7 @@ ios_app_clip = rule_factory.create_apple_rule(
             allowed_families = rule_attrs.defaults.allowed_families.ios,
             is_mandatory = True,
         ),
+        rule_attrs.device_runner_template_attr(),
         rule_attrs.infoplist_attrs(),
         rule_attrs.ipa_post_processor_attrs(),
         rule_attrs.locales_to_include_attrs(),

apple/internal/rule_attrs.bzl

@@ -719,7 +719,7 @@ bundle in a directory named `Settings.bundle`.
 def _simulator_runner_template_attr():
     """Returns the attribute required to `bazel run` a *_application target with an Apple sim."""
     return {
-        "_runner_template": attr.label(
+        "_simulator_runner_template": attr.label(
             cfg = "exec",
             allow_single_file = True,
             default = Label(
@@ -728,6 +728,18 @@ def _simulator_runner_template_attr():
         ),
     }
 
+def _device_runner_template_attr():
+    """Returns the attribute required to `bazel run` a *_application target on a physical device."""
+    return {
+        "_device_runner_template": attr.label(
+            cfg = "exec",
+            allow_single_file = True,
+            default = Label(
+                "@build_bazel_rules_apple//apple/internal/templates:apple_device_template",
+            ),
+        ),
+    }
+
 def _locales_to_include_attr():
     """Returns the attribute required to support configuring the explicit set of locales supported for the bundle."""
     return {
@@ -757,6 +769,7 @@ rule_attrs = struct(
     common_tool_attrs = _common_tool_attrs,
     custom_transition_allowlist_attr = _custom_transition_allowlist_attr,
     device_family_attrs = _device_family_attrs,
+    device_runner_template_attr = _device_runner_template_attr,
     extensionkit_attrs = _extensionkit_attrs,
     infoplist_attrs = _infoplist_attrs,
     ipa_post_processor_attrs = _ipa_post_processor_attrs,

apple/internal/run_support.bzl

@@ -76,6 +76,59 @@ def _register_simulator_executable(
         },
     )
 
+def _register_device_executable(
+        *,
+        actions,
+        bundle_extension,
+        bundle_name,
+        label_name,
+        output,
+        platform_prerequisites,
+        predeclared_outputs,
+        rule_descriptor,
+        runner_template,
+        device = None):
+    """Registers an action that runs the bundled app on a physical device.
+
+    Args:
+      actions: The actions provider from ctx.actions.
+      bundle_extension: Extension for the Apple bundle inside the archive.
+      bundle_name: The name of the output bundle.
+      label_name: The name of the target.
+      output: The `File` representing where the executable should be generated.
+      platform_prerequisites: Struct containing information on the platform being targeted.
+      predeclared_outputs: Outputs declared by the owning context. Typically from `ctx.outputs`
+      rule_descriptor: The rule descriptor for the given rule.
+      runner_template: The simulator runner template as a `File`.
+      device: The identifier of the device ( <uuid|ecid|serial_number|udid|name|dns_name> ).
+    """
+
+    device = str(device or "")
+    minimum_os = str(platform_prerequisites.minimum_os)
+    platform_type = str(platform_prerequisites.platform_type)
+    archive = outputs.archive(
+        actions = actions,
+        bundle_name = bundle_name,
+        bundle_extension = bundle_extension,
+        label_name = label_name,
+        platform_prerequisites = platform_prerequisites,
+        predeclared_outputs = predeclared_outputs,
+        rule_descriptor = rule_descriptor,
+    )
+
+    actions.expand_template(
+        output = output,
+        is_executable = True,
+        template = runner_template,
+        substitutions = {
+            "%app_name%": bundle_name,
+            "%ipa_file%": archive.short_path,
+            "%minimum_os%": minimum_os,
+            "%platform_type%": platform_type,
+            "%device%": device,
+        },
+    )
+
 def _register_macos_executable(
         *,
         actions,
@@ -105,6 +158,7 @@ def _register_macos_executable(
 
 # Define the loadable module that lists the exported symbols in this file.
 run_support = struct(
-    register_simulator_executable = _register_simulator_executable,
+    register_device_executable = _register_device_executable,
     register_macos_executable = _register_macos_executable,
+    register_simulator_executable = _register_simulator_executable,
 )

apple/internal/templates/BUILD

@@ -18,6 +18,15 @@ filegroup(
     visibility = ["//visibility:public"],
 )
 
+filegroup(
+    name = "apple_device_template",
+    srcs = ["apple_device.template.py"],
+    # Used by the rule implementations, so it needs to be public; but
+    # should be considered an implementation detail of the rules and
+    # not used by other things.
+    visibility = ["//visibility:public"],
+)
+
 filegroup(
     name = "macos_template",
     srcs = ["macos.template.sh"],