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 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
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.
- Mac OS X 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 theMACOSX_BUNDLE_ICON_FILE
target property when you calladd_executable
. - Sidebar icons should typically provided in 16, 32, 64, 128 and 256px.
- The executable target must have the
Since 1.7.0.