ECMAddAppIcon

Add icons to executable files and packages.

ecm_add_app_icon(<sources_var_name(|target (since 5.83))>
                 ICONS <icon> [<icon> [...]]
                 [SIDEBAR_ICONS <icon> [<icon> [...]] # Since 5.49
                 [OUTFILE_BASENAME <name>]) # Since 5.49
                 )

The given icons, whose names must match the pattern:

<size>-<other_text>.png

will be added as platform-specific application icons to the variable named <sources_var_name> or, if the first argument is a target (since 5.83), to the SOURCES property of <target>. Any target must be created with add_executable() and not be an alias.

Other icon files are ignored but on macOS SVG files can be supported and it is thus possible to mix those with png files in a single macro call.

The platforms currently supported are Windows and macOS, on all others the call has no effect and is ignored.

<size> is a numeric pixel size (typically 16, 32, 48, 64, 128 or 256). <other_text> can be any other text. See the platform notes below for any recommendations about icon sizes.

SIDEBAR_ICONS can be used to add macOS sidebar icons to the generated iconset. They are used when a folder monitored by the application is dragged into Finder’s sidebar. Since 5.49.

OUTFILE_BASENAME will be used as the basename for the icon file. If you specify it, the icon file will be called <OUTFILE_BASENAME>.icns on macOS and <OUTFILE_BASENAME>.ico on Windows. If you don’t specify it, it defaults to <sources_var_name>.<ext>. Since 5.49.

Windows notes

  • Icons are compiled into the executable using a resource file.

  • Icons may not show up in Windows Explorer if the executable target does not have the WIN32_EXECUTABLE property set.

  • Icotool (see FindIcoTool) is required.

  • Supported sizes: 16, 24, 32, 48, 64, 128, 256, 512 and 1024.

macOS notes

  • The executable target must have the MACOSX_BUNDLE property set.

  • Icons are added to the bundle.

  • If the ksvg2icns tool from KIconThemes is available, .svg and .svgz files are accepted; the first that is converted successfully to .icns will provide the application icon. SVG files are ignored otherwise.

  • The tool iconutil (provided by Apple) is required for bitmap icons.

  • Supported sizes: 16, 32, 64, 128, 256 (and 512, 1024 after OS X 10.9).

  • At least a 128x128px (or an SVG) icon is required.

  • Larger sizes are automatically used to substitute for smaller sizes on “Retina” (high-resolution) displays. For example, a 32px icon, if provided, will be used as a 32px icon on standard-resolution displays, and as a 16px-equivalent icon (with an “@2x” tag) on high-resolution displays. That is why you should provide 64px and 1024px icons although they are not supported anymore directly. Instead they will be used as 32px@2x and 512px@2x. If an SVG icon is provided, ksvg2icns will be used internally to automatically generate all appropriate sizes, including the high-resolution ones.

  • This function sets the MACOSX_BUNDLE_ICON_FILE variable to the name of the generated icns file, so that it will be used as the MACOSX_BUNDLE_ICON_FILE target property when you call add_executable.

  • Sidebar icons should typically provided in 16, 32, 64, 128 and 256px.

Since 1.7.0.