feat: Add support for macOS layered icons #5451

Sanlorng · 2025-10-13T05:49:31Z

Support for using macOS layered icons (.icon directory) for both JVM and native application packaging.

This feature requires actool version >= 26.0

A new layeredIconDir property is added to the compose.desktop.application.nativeDistributions.macOS and compose.nativeApplication.macOS DSLs.
The actool from Xcode Command Line Tools is used to compile the .icon directory into an Assets.car file.
The Assets.car file is included in the .app bundle resources.
The Info.plist is updated with CFBundleIconName to reference the compiled asset.
A check for a supported actool version is performed before compilation.
New integration tests (testMacLayeredIcon, testMacLayeredIconRemove) are added to verify the functionality for both JVM and native targets.

Example

compose.desktop {
    application {
        nativeDistributions {
            macOS {
                layeredIconDir.set("Icon Path")
            }
        }
    }
}

Testing

Only verify the task behavior: compose:test-Gradle(9.2.0)-Agp(8.12.3) --tests org.jetbrains.compose.test.tests.integration.DesktopApplicationTest.testMacLayeredIcon

Only verify the task behavior: compose:test-Gradle(9.2.0)-Agp(8.12.3) --tests org.jetbrains.compose.test.tests.integration.DesktopApplicationTest.testMacLayeredIconRemove

This should be tested by QA

Tickets

CMP-9083 Support macOS 26 layered icons

Release Notes

Features - Gradle Plugin

Support for using macOS layered icons (.icon directory) for both JVM and native application packaging.

kropp · 2025-10-13T11:52:32Z

Hi, thank you for the contribution!
We will soon be requiring all PRs to have a linked issue in our tracker, I created one for this: CMP-9083 Support macOS 26 layered icons. It should be used for discussions around the newly added feature.

Sanlorng · 2025-11-21T14:52:08Z

Thanks again for creating the related YouTrack issue – it’s been really helpful!

I just wanted to gently follow up on this PR – would you have a moment to review it when you get a chance? Let me know if I can clarify anything to make it easier!

No rush at all, appreciate your help!

freelife4850-netizen

Sounds like a good idea to try 🙂

kropp

Sorry for a long wait, could you please take a look at comments and also rebase the branch to the latest version?

...pose/src/main/kotlin/org/jetbrains/compose/desktop/application/tasks/AbstractJPackageTask.kt

...mpose/src/test/kotlin/org/jetbrains/compose/test/tests/integration/DesktopApplicationTest.kt

gradle-plugins/compose/src/test/test-projects/application/macLayeredIcon/build.gradle.kts

.../compose/src/main/kotlin/org/jetbrains/compose/desktop/application/internal/MacAssetsTool.kt

This commit introduces support for using macOS layered icons (`.icon` directory) for both JVM and native application packaging. - A new `layeredIconDir` property is added to the `compose.desktop.application.nativeDistributions.macOS` and `compose.nativeApplication.macOS` DSLs. - The `actool` from Xcode Command Line Tools is used to compile the `.icon` directory into an `Assets.car` file. - The `Assets.car` file is included in the `.app` bundle resources. - The `Info.plist` is updated with `CFBundleIconName` to reference the compiled asset. - A check for a supported `actool` version is performed before compilation. - New integration tests (`testMacLayeredIcon`, `testMacLayeredIconRemove`) are added to verify the functionality for both JVM and native targets.

The `macAssetsDir` property in `AbstractJPackageTask` was unused and has been removed.

- Deleted the `Expected-Info.plist` which verified now-removed properties. - Removed `extraInfoPlistKeys` and file association configurations from the test's `build.gradle.kts`.

Updated the `macLayeredIcon` test project to use `COMPOSE_VERSION_PLACEHOLDER` for Compose dependency versions. This makes the test configuration more flexible and easier to maintain.

This commit refactors the `actool` version parsing logic to use the `plutil` command-line tool instead of a manual XML parser. This change simplifies the code and improves robustness. - Replaced the XML parsing implementation in `MacAssetsTool` with a call to `plutil -extract`. - Updated `try`/`catch` blocks to handle exceptions from the tool execution. - Added a `plutil` file definition to `MacUtils`. - Integration tests for macOS layered icons (`testMacLayeredIcon`, `testMacLayeredIconRemove`) are now skipped if the `actool` version is less than 26, ensuring they run only on supported environments.

Sanlorng · 2025-12-10T15:37:34Z

@kropp All the changes you mentioned that needed to be made have already been completed.

kropp · 2025-12-11T16:10:21Z

@igordmn requesting second review as it adds new public API in Gradle plugin

PierreVieira

Simple comments. Nice addition!

.../compose/src/main/kotlin/org/jetbrains/compose/desktop/application/internal/MacAssetsTool.kt

...plugins/compose/src/test/test-projects/application/macLayeredIcon/src/jvmMain/kotlin/main.kt

...ugins/compose/src/test/test-projects/application/macLayeredIcon/src/macosMain/kotlin/main.kt

...pose/src/test/test-projects/application/macLayeredIcon/subdir/kotlin_icon_big.icon/icon.json

gradle-plugins/compose/src/test/test-projects/application/macLayeredIcon/build.gradle.kts

gradle-plugins/compose/src/test/test-projects/application/macLayeredIcon/gradle.properties

gradle-plugins/compose/src/test/test-projects/application/macLayeredIcon/settings.gradle.kts

Co-authored-by: Pierre Vieira <pierrevieiraggg@gmail.com>

igordmn

Thank you and sorry for more waiting time. After we resolve the new comments, it should be good to merge.

igordmn · 2026-01-12T19:11:49Z

...ns/compose/src/main/kotlin/org/jetbrains/compose/desktop/application/dsl/PlatformSettings.kt

    var dmgPackageBuildVersion: String? = null
    var appCategory: String? = null
    var minimumSystemVersion: String? = null
+    var layeredIconDir: DirectoryProperty = objects.directoryProperty()


Do we override the icon defined in iconFile by defining this property and packaging it on the new macOs/Xcode? Is this icon supported on the oldest OS, because it is compiled into backward-compatible assets?

If so, it is better to reuse the existing iconFile instead of adding a new property and check that if it is a directory ending with ".icon" then we should use the layeredIcon logic.

Reasoning:

iconFile, layeredIconDir change one thing (the application icon) and differ only in implementations

it is similar to using different extensions, just more unusual

we might need to support it in fileAssociation

igordmn · 2026-01-24T01:32:41Z

...ns/compose/src/main/kotlin/org/jetbrains/compose/desktop/application/dsl/PlatformSettings.kt

    var dmgPackageBuildVersion: String? = null
    var appCategory: String? = null
    var minimumSystemVersion: String? = null
+    var layeredIconDir: DirectoryProperty = objects.directoryProperty()


Can we support it for fileAssociation?:

compose.desktop { application { nativeDistributions { macOS { fileAssociation( "text/kotlin", "kott", "Kotlin Source File2", project.file("subdir/kotlin_icon_big.icon"), )

igordmn · 2026-01-24T01:35:49Z

...ns/compose/src/main/kotlin/org/jetbrains/compose/desktop/application/dsl/PlatformSettings.kt

    var dmgPackageBuildVersion: String? = null
    var appCategory: String? = null
    var minimumSystemVersion: String? = null
+    var layeredIconDir: DirectoryProperty = objects.directoryProperty()


Please add a link to the example (gradle-plugins/compose/src/test/test-projects/application/macLayeredIcon/subdir/kotlin_icon_big.icon) in the PR description, near the snippet and change the path in the snippet to subdir/kotlin_icon_big.icon

igordmn · 2026-01-24T01:47:10Z

...ns/compose/src/main/kotlin/org/jetbrains/compose/desktop/application/dsl/PlatformSettings.kt

    var dmgPackageBuildVersion: String? = null
    var appCategory: String? = null
    var minimumSystemVersion: String? = null
+    var layeredIconDir: DirectoryProperty = objects.directoryProperty()


We need to describe necessary changes required in the documentation.

I suggest to just do it in the PR:

Documentation changes needed

Documentation section

.icns files or .icon directory ([example](gradle-plugins/compose/src/test/test-projects/application/macLayeredIcon/subdir/kotlin_icon_big.icon)) for macOS

igordmn · 2026-01-24T01:59:00Z

gradle-plugins/compose/src/test/test-projects/application/macLayeredIcon/Kotlin_icon_big.png

Are the root icons not used? If so, let's delete.

igordmn · 2026-01-24T02:39:41Z

...pose/src/main/kotlin/org/jetbrains/compose/desktop/application/tasks/AbstractJPackageTask.kt


            if (macAppStore.orNull == true) {
-                val systemVersion = macMinimumSystemVersion.orNull ?: "10.13"
+


Suggested change

igordmn · 2026-01-24T02:53:36Z

.../compose/src/main/kotlin/org/jetbrains/compose/desktop/application/internal/MacAssetsTool.kt

+                "--platform", "macosx",
+                "--enable-icon-stack-fallback-generation=disabled",
+                "--include-all-app-icons",
+                "--minimum-deployment-target", minimumSystemVersion ?: "10.13",


Suggested change

"--minimum-deployment-target", minimumSystemVersion ?: "10.13",

"--minimum-deployment-target", minimumSystemVersion,

Better to pass a non-null parameter to not have "10.13" in multiple places. We seems can do that, by changing one of the calling code to minimumSystemVersion.getOrElse(KOTLIN_NATIVE_MIN_SUPPORTED_MAC_OS)!!

igordmn · 2026-01-24T03:20:52Z

...pose/src/main/kotlin/org/jetbrains/compose/desktop/application/tasks/AbstractJPackageTask.kt

+
+    @get:InputDirectory
+    @get:Optional
+    internal val macLayeredIcons: DirectoryProperty = objects.directoryProperty()


Suggested change

internal val macLayeredIcons: DirectoryProperty = objects.directoryProperty()

internal val layeredIconDir: DirectoryProperty = objects.directoryProperty()

to be consistent with the public property (if we still decide to keep it after this)

igordmn · 2026-01-24T03:22:30Z

.../compose/src/main/kotlin/org/jetbrains/compose/desktop/application/internal/MacAssetsTool.kt

+
+    fun compileAssets(iconDir: File, workingDir: File, minimumSystemVersion: String?): File {
+        val toolVersion = checkAssetsToolVersion()
+        logger.info("compile mac assets is starting, supported actool version:$toolVersion")


Suggested change

logger.info("compile mac assets is starting, supported actool version:$toolVersion")

logger.info("Compilation of mac assets is starting, actool version: $toolVersion")

MatkovIvan requested a review from kropp October 13, 2025 11:26

freelife4850-netizen reviewed Dec 4, 2025

View reviewed changes

kropp requested changes Dec 10, 2025

View reviewed changes

Sanlorng added 5 commits December 10, 2025 19:16

Remove unused macAssetsDir property

6878a0a

The `macAssetsDir` property in `AbstractJPackageTask` was unused and has been removed.

clean code

27e4a6b

- Deleted the `Expected-Info.plist` which verified now-removed properties. - Removed `extraInfoPlistKeys` and file association configurations from the test's `build.gradle.kts`.

Refactor: Use placeholders for Compose dependencies in test

3cce19c

Updated the `macLayeredIcon` test project to use `COMPOSE_VERSION_PLACEHOLDER` for Compose dependency versions. This makes the test configuration more flexible and easier to maintain.

Sanlorng force-pushed the support_macos_new_icon branch from 6fe432f to f6d1291 Compare December 10, 2025 15:36

kropp approved these changes Dec 11, 2025

View reviewed changes

kropp requested a review from igordmn December 11, 2025 16:09

PierreVieira reviewed Dec 16, 2025

View reviewed changes

typo: add new lines

8c45518

Co-authored-by: Pierre Vieira <pierrevieiraggg@gmail.com>

igordmn requested changes Jan 24, 2026

View reviewed changes


		if (macAppStore.orNull == true) {
		val systemVersion = macMinimumSystemVersion.orNull ?: "10.13"

	"--minimum-deployment-target", minimumSystemVersion ?: "10.13",
	"--minimum-deployment-target", minimumSystemVersion,

	internal val macLayeredIcons: DirectoryProperty = objects.directoryProperty()
	internal val layeredIconDir: DirectoryProperty = objects.directoryProperty()

	logger.info("compile mac assets is starting, supported actool version:$toolVersion")
	logger.info("Compilation of mac assets is starting, actool version: $toolVersion")

feat: Add support for macOS layered icons #5451

Are you sure you want to change the base?

feat: Add support for macOS layered icons #5451

Uh oh!

Conversation

Sanlorng commented Oct 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Example

Testing

Tickets

Release Notes

Features - Gradle Plugin

Uh oh!

kropp commented Oct 13, 2025

Uh oh!

Sanlorng commented Nov 21, 2025

Uh oh!

freelife4850-netizen left a comment

Choose a reason for hiding this comment

Uh oh!

kropp left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Sanlorng commented Dec 10, 2025

Uh oh!

kropp commented Dec 11, 2025

Uh oh!

PierreVieira left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

igordmn left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Documentation changes needed

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Sanlorng commented Oct 13, 2025 •

edited

Loading