support icon composer app icons for xcode 26+ (#2733)

Author: aaronsky

apple/internal/bundling_support.bzl

@@ -248,10 +248,19 @@ See https://github.com/bazelbuild/rules_apple/blob/master/doc/shared_capabilitie
         suffix_default = suffix_default,
     )
 
-def _ensure_single_xcassets_type(*, attr, extension, files, message = None):
+def _ensure_single_xcassets_type(
+        *,
+        additional_path_fragments = [],
+        attr,
+        extension,
+        files,
+        message = None):
     """Helper for when an xcassets catalog should have a single sub type.
 
     Args:
+      additional_path_fragments: Additional path fragments to check for in the path (in order), used
+          to handle actool inputs that don't use the `xcassets` directory, such as Xcode 26 `icon`
+          bundles generated by the Icon Composer tool.
       attr: The attribute to associate with the build failure if the list of
           files has an element that is not in a directory with the given
           extension.
@@ -267,7 +276,7 @@ def _ensure_single_xcassets_type(*, attr, extension, files, message = None):
     _ensure_path_format(
         attr = attr,
         files = files,
-        path_fragments_list = [["xcassets", extension]],
+        path_fragments_list = [["xcassets", extension], additional_path_fragments],
         message = message,
     )
 

apple/internal/partials/app_assets_validation.bzl

@@ -85,7 +85,15 @@ def _app_assets_validation_partial_impl(
                 message = message,
             )
         else:
+            # For Xcode 26, appiconset-s can live alongside iOS/macOS/watchOS .icon bundle contents
+            # to ensure rendering is correct for pre-26 Apple OSes, so we need to make that
+            # exception here.
+            additional_path_fragments = []
+            xcode_version = platform_prerequisites.xcode_version_config.xcode_version()
+            if xcode_version >= apple_common.dotted_version("26.0"):
+                additional_path_fragments.append("icon")
             bundling_support.ensure_single_xcassets_type(
+                additional_path_fragments = additional_path_fragments,
                 attr = "app_icons",
                 extension = "appiconset",
                 files = app_icons,

apple/internal/providers.bzl

@@ -427,14 +427,15 @@ AppleResourceInfo, new_appleresourceinfo = provider(
         "asset_catalogs": "Resources that need to be embedded into Assets.car.",
         "datamodels": "Datamodel files.",
         "framework": "Apple framework bundle from `ios_framework` and `tvos_framework` targets.",
-        "infoplists": """Plist files to be merged and processed. Plist files that should not be
-merged into the root Info.plist should be propagated in `plists`. Because of this, infoplists should
-only be bucketed with the `bucketize_typed` method.""",
+        "infoplists": """Plist files to be merged and processed. Plist files that should not be \
+merged into the root Info.plist should be propagated in `plists`. Because of this, infoplists \
+should only be bucketed with the `bucketize_typed` method.""",
         "metals": """Metal Shading Language source files to be compiled into a single .metallib file
 and bundled at the top level.""",
         "mlmodels": "Core ML model files that should be processed and bundled at the top level.",
         "plists": "Resource Plist files that should not be merged into Info.plist",
-        "pngs": "PNG images which are not bundled in an .xcassets folder.",
+        "pngs": """PNG images which are not bundled in an .xcassets folder or an .icon folder in \
+Xcode 26+.""",
         "processed": "Typed resources that have already been processed.",
         "storyboards": "Storyboard files.",
         "strings": "Localization strings files.",

apple/internal/resource_actions/actool.bzl

@@ -49,6 +49,9 @@ load(
 
 _supports_visionos = hasattr(apple_common.platform_type, "visionos")
 
+# TODO: b/425967223 - Rework the validation to better account for Xcode 26, and make it a bit more
+# readable via helper functions as we add more conditions.
+
 def _actool_args_for_special_file_types(
         *,
         asset_files,
@@ -77,6 +80,13 @@ def _actool_args_for_special_file_types(
     """
     args = []
 
+    is_xcode_26_or_later = (
+        platform_prerequisites.xcode_version_config.xcode_version() >=
+        apple_common.dotted_version("26.0")
+    )
+    icon_files = []
+    icon_bundle_files = []
+
     if product_type in (
         apple_product_type.messages_extension,
         apple_product_type.messages_sticker_pack_extension,
@@ -121,27 +131,72 @@ def _actool_args_for_special_file_types(
         appicon_extension = "solidimagestack"
         icon_files = [f for f in asset_files if ".solidimagestack/" in f.path]
     else:
+        icon_bundle_files = [f for f in asset_files if ".icon/" in f.path]
         appicon_extension = "appiconset"
         icon_files = [f for f in asset_files if ".appiconset/" in f.path]
 
+    if not is_xcode_26_or_later and len(icon_bundle_files):
+        fail("""\
+Found Icon Composer .icon bundles among the assigned app_icons. These are only supported \
+on Xcode 26 or later.""")
+
     # Add arguments for app icons, if there are any.
-    if icon_files:
+    if icon_files or icon_bundle_files:
         icon_dirs = group_files_by_directory(
             icon_files,
             [appicon_extension],
             attr = "app_icons",
         ).keys()
-        if len(icon_dirs) != 1 and not primary_icon_name:
+        has_exactly_one_icon_dir = False
+
+        if is_xcode_26_or_later:
+            icon_bundle_dirs = group_files_by_directory(
+                icon_bundle_files,
+                ["icon"],
+                attr = "app_icons",
+            ).keys()
+
+            if len(icon_dirs + icon_bundle_dirs) == 1:
+                has_exactly_one_icon_dir = True
+            elif len(icon_dirs) == 1 and len(icon_bundle_dirs) == 1:
+                # Carve out; the AppIcon and Icon bundles can be used together to support Apple OSes
+                # prior to 26 and the new Apple OS 26 icon features for iOS/macOS/watchOS as long as
+                # their names match perfectly.
+                icon_paths_to_compare = [icon_dirs[0], icon_bundle_dirs[0]]
+                unique_icon_names = dict()
+                for icon_path in icon_paths_to_compare:
+                    unique_icon_names[paths.split_extension(paths.basename(icon_path))[0]] = True
+                if len(unique_icon_names) == 1:
+                    has_exactly_one_icon_dir = True
+            icon_dirs.extend(icon_bundle_dirs)
+
+        elif len(icon_dirs) == 1:
+            has_exactly_one_icon_dir = True
+
+        if not has_exactly_one_icon_dir and not primary_icon_name:
             formatted_dirs = "[\n  %s\n]" % ",\n  ".join(icon_dirs)
 
             # Alternate icons are only supported for UIKit applications on iOS, tvOS, visionOS and
             # iOS-on-macOS (Catalyst)
             if (platform_prerequisites.platform_type == apple_common.platform_type.watchos or
                 platform_prerequisites.platform_type == apple_common.platform_type.macos or
                 product_type != apple_product_type.application):
-                fail("The asset catalogs should contain exactly one directory named " +
-                     "*.%s among its asset catalogs, " % appicon_extension +
-                     "but found the following: " + formatted_dirs, "app_icons")
+                xcode_26_workaround_message = ""
+                if is_xcode_26_or_later:
+                    xcode_26_workaround_message = (
+                        "which can be accompanied by exactly one Icon Composer .icon bundle of " +
+                        "the same name, "
+                    )
+                fail("""
+The asset catalogs should contain exactly one directory named *.{appicon_extension} among its \
+asset catalogs, \
+{xcode_26_workaround_message}\
+but found the following: \
+{formatted_dirs}""".format(
+                    appicon_extension = appicon_extension,
+                    formatted_dirs = formatted_dirs,
+                    xcode_26_workaround_message = xcode_26_workaround_message,
+                ), "app_icons")
             else:
                 fail("""
 Found multiple app icons among the asset catalogs with no primary_app_icon assigned.
@@ -279,13 +334,27 @@ def compile_asset_catalog(
         "actool",
         "--compile",
         xctoolrunner_support.prefixed_path(output_dir.path),
+        "--errors",
+        "--warnings",
+        "--notices",
+        "--output-format",
+        "human-readable-text",
         "--platform",
         actool_platform,
         "--minimum-deployment-target",
         platform_prerequisites.minimum_os,
         "--compress-pngs",
     ]
 
+    xcode_config = platform_prerequisites.xcode_version_config
+
+    if platform_prerequisites.platform_type == "macos" and (
+        xcode_config.xcode_version() >= apple_common.dotted_version("26.0")
+    ):
+        # Required for the Icon Composer .icon bundles to work as inputs, even though it's not
+        # documented. Xcode 26 currently relies on this flag to be set.
+        args.extend(["--lightweight-asset-runtime-mode", "enabled"])
+
     args.extend(_actool_args_for_special_file_types(
         asset_files = asset_files,
         bundle_id = bundle_id,
@@ -321,7 +390,7 @@ def compile_asset_catalog(
 
     xcassets = group_files_by_directory(
         asset_files,
-        ["xcassets", "xcstickers"],
+        ["icon", "xcassets", "xcstickers"],
         attr = "asset_catalogs",
     ).keys()
 
@@ -336,7 +405,7 @@ def compile_asset_catalog(
         inputs = asset_files,
         mnemonic = "AssetCatalogCompile",
         outputs = actool_outputs,
-        xcode_config = platform_prerequisites.xcode_version_config,
+        xcode_config = xcode_config,
     )
 
     if alternate_icons:

apple/internal/resource_actions/ibtool.bzl

@@ -77,6 +77,12 @@ def compile_storyboard(
         "ibtool",
         "--compilation-directory",
         xctoolrunner_support.prefixed_path(output_dir.dirname),
+        "--errors",
+        "--warnings",
+        "--notices",
+        "--auto-activate-custom-fonts",
+        "--output-format",
+        "human-readable-text",
     ]
 
     min_os = platform_prerequisites.minimum_os

apple/internal/resources.bzl

@@ -258,7 +258,9 @@ def _bucketize_data(
                 resource_swift_module = swift_module
             elif ".alticon/" in resource_short_path:
                 bucket_name = "asset_catalogs"
-            elif ".xcassets/" in resource_short_path or ".xcstickers/" in resource_short_path:
+            elif (".icon/" in resource_short_path or
+                  ".xcassets/" in resource_short_path or
+                  ".xcstickers/" in resource_short_path):
                 bucket_name = "asset_catalogs"
             elif ".xcdatamodel" in resource_short_path or ".xcmappingmodel/" in resource_short_path:
                 bucket_name = "datamodels"

apple/internal/rule_attrs.bzl

@@ -623,7 +623,9 @@ def _app_icon_attrs(
             doc = """
 Files that comprise the app icons for the application. Each file must have a containing directory
 named `*.{app_icon_parent_extension}/*.{app_icon_extension}` and there may be only one such
-`.{app_icon_extension}` directory in the list.""".format(
+`.{app_icon_extension}` directory in the list. In Xcode 26+ for iOS/macOS/watchOS, an `*.icon`
+bundle can be provided along with the `*.{app_icon_parent_extension}` bundle to support 26 and
+pre-26 Apple OS rendering.""".format(
                 app_icon_extension = icon_extension,
                 app_icon_parent_extension = icon_parent_extension,
             ),
@@ -634,8 +636,12 @@ named `*.{app_icon_parent_extension}/*.{app_icon_extension}` and there may be on
             "primary_app_icon": attr.string(
                 doc = """
 An optional String to identify the name of the primary app icon when alternate app icons have been
-provided for the app.
-""",
+provided for the app. This should match both the `*.icon` bundle in iOS/macOS/watchOS 26+ and the
+`*.{app_icon_parent_extension}/.appiconset` bundle's AppIcon resource in previous versions of
+iOS/macOS/watchOS.
+""".format(
+                    app_icon_parent_extension = icon_parent_extension,
+                ),
             ),
         })
     return app_icon_attrs

doc/providers.md

@@ -494,7 +494,7 @@ Provider that propagates buckets of resources that are differentiated by type.
 | <a id="AppleResourceInfo-metals"></a>metals |  Metal Shading Language source files to be compiled into a single .metallib file and bundled at the top level.    |
 | <a id="AppleResourceInfo-mlmodels"></a>mlmodels |  Core ML model files that should be processed and bundled at the top level.    |
 | <a id="AppleResourceInfo-plists"></a>plists |  Resource Plist files that should not be merged into Info.plist    |
-| <a id="AppleResourceInfo-pngs"></a>pngs |  PNG images which are not bundled in an .xcassets folder.    |
+| <a id="AppleResourceInfo-pngs"></a>pngs |  PNG images which are not bundled in an .xcassets folder or an .icon folder in Xcode 26+.    |
 | <a id="AppleResourceInfo-processed"></a>processed |  Typed resources that have already been processed.    |
 | <a id="AppleResourceInfo-storyboards"></a>storyboards |  Storyboard files.    |
 | <a id="AppleResourceInfo-strings"></a>strings |  Localization strings files.    |