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:
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
Any target must be created with add_executable() and not be an alias.
Other icon files are ignored but on Mac 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 Mac OS X, 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 Mac OS X 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 Mac OS X
<OUTFILE_BASENAME>.ico on Windows. If you don’t specify it, it defaults
<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
FindIcoTool) is required.
Supported sizes: 16, 24, 32, 48, 64, 128, 256, 512 and 1024.
- Mac OS X notes
The executable target must have the
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_FILEvariable to the name of the generated icns file, so that it will be used as the
MACOSX_BUNDLE_ICON_FILEtarget property when you call
Sidebar icons should typically provided in 16, 32, 64, 128 and 256px.