Doc: Add cmake instructions for app icon setup

Added CMake-specific app icon setup instructions
for windows and macOS.

Change-Id: I81378ba8cee010685811b34b4dee85fdbe2b2edf
Fixes: QTBUG-83696
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
(cherry picked from commit 33b7bf61824b80cf71042c31c505b73e82e11b37)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

2 files changed, 87 insertions, 19 deletions

diff --git a/doc/src/howtos/appicon.qdoc b/doc/src/howtos/appicon.qdoc
index fcd2487a..f4ff8275 100644
--- a/doc/src/howtos/appicon.qdoc
+++ b/doc/src/howtos/appicon.qdoc
@@ -37,8 +37,8 @@
     QWindow::setIcon() method.
 
     In order to change the icon of the executable application file
-    itself, as it is presented on the desktop (i.e., prior to
-    application execution), it is necessary to employ another,
+    itself, as it is presented on the desktop (that is, prior to
+    application launch), it is necessary to employ another,
     platform-dependent technique.
 
     \tableofcontents
@@ -46,11 +46,11 @@
     \section1 Setting the Application Icon on Windows
 
     First, create an ICO format bitmap file that contains the icon
-    image. This can be done with e.g. Microsoft Visual C++: Select
-    \menu{File|New}, then select the \menu{File} tab in the dialog
-    that appears, and choose \menu{Icon}. (Note that you do not need
-    to load your application into Visual C++; here we are only using
-    the icon editor.)
+    image. This can be done using Microsoft Visual Studio: Select
+    \uicontrol{File >> New}, and choose the \uicontrol{Icon File}.
+
+    \note You need not load the application into the Visual Studio IDE as you
+    are using the icon editor only.
 
     Alternatively, an \c .ico file can be created from a set of images using
     ImageMagick's \l {https://imagemagick.org/script/convert.php}{convert}
@@ -61,10 +61,33 @@
     \endcode
 
     Store the ICO file in your application's source code directory,
-    for example, with the name \c myappico.ico.
+    for example, with the name \c appico.ico.
+
+    \section2 Using CMake
+
+    To configure your application's icon, a resource file containing
+    information about the icon is required. A resource file is a text
+    file that contains information about the application
+    resources, such as icons, cursors, fonts, and so on. For
+    more information about resource files and what it can contain, see
+    \l{https://docs.microsoft.com/en-us/windows/win32/menurc/about-resource-files}{About Resource Files}.
+
+    Once you have the \c .rc file, add information about the ICO file to it and
+    use it to configure your application icon.
+
+    The following snippet example demonstrates how to set up application
+    icon using CMake:
+
+    \snippet snippets/code/CMakeLists.txt appicon_windows
+
+    Notice that the \c set command, defines the \c APP_ICON_RESOURCE_WINDOWS
+    variable, which contains the path of the RC file. This variable is used
+    with the \c add_executable command to set the application's icon.
 
-    Then, assuming you are using qmake to generate your makefiles,
-    you only need to add a single line to your \c .pro project file:
+    \section2 Using qmake
+
+    If you are still using qmake to generate your makefiles,
+    you need to add a single line to your \c .pro project file:
 
     \snippet snippets/code/doc_src_appicon.pro 0
 
@@ -104,7 +127,28 @@
     icns files. Using this tool also compresses the resulting icns file,
     so there is no need for you to perform additional compression.
 
-    If you are using qmake to generate your makefiles, you only need
+    \section2 Using CMake
+
+    To configure the application's icon, the \c Info.plist file generated
+    by CMake must contain the icon information. This can be achieved by
+    setting the \c .icns file name to the \c MACOSX_BUNDLE_ICON_FILE variable.
+
+    The following snippet demonstrates how to set up the application icon using
+    CMake:
+
+    \snippet snippets/code/CMakeLists.txt appicon_macOS
+
+    Notice that the first \c set command defines the \c MACOSX_BUNDLE_ICON_FILE
+    variable, which is required to add the icon file to the \c Info.plist file.
+    The second \c set command defines the \c APP_ICON_MACOSX variable with the
+    absolute path to the icon file. This variable is then used to configure
+    MACOSX_PACKAGE_LOCATION, which defines the icon file's install location.
+    Finally, the \c add_executable uses the \c APP_ICON_MACOSX variable to set
+    the application's icon.
+
+    \section2 Using qmake
+
+    If you are still using qmake to generate your makefiles, you only need
     to add a single line to your \c .pro project file. For example,
     if the name of your icon file is \c{myapp.icns}, and your project
     file is \c{myapp.pro}, add this line to \c{myapp.pro}:
@@ -207,13 +251,13 @@
     http://www.freedesktop.org/Standards/icon-theme-spec Icon Theme
     Specification \endlink.
 
-    If you are developing exclusively for GNOME, you may wish to use
-    the standard set of \link
-    http://developer.gnome.org/tools/build.html GNU Build Tools\endlink,
-    also described in the relevant section of
-    the \link http://developer.gnome.org/doc/GGAD/ggad.html GTK+/Gnome
-    Application Development book\endlink. This ensures that your icons are
-    installed in the appropriate locations for GNOME.
+    If you are developing exclusively for GNOME, you may want to use
+    the standard set of GNU Build Tools. For more information, see
+    the
+    \l{https://developer.gnome.org/platform-overview/unstable/dev-launching.html.en}{Application launching}
+    section. This ensures that your icons are installed in the
+    appropriate locations for GNOME.
 
-    The GNOME developer website is at \l{http://developer.gnome.org/}.
+    The GNOME developer website, \l{http://developer.gnome.org/}, provides
+    more insight into developing applications.
 */
diff --git a/doc/src/snippets/code/CMakeLists.txt b/doc/src/snippets/code/CMakeLists.txt
new file mode 100644
index 00000000..52c26898
--- /dev/null
+++ b/doc/src/snippets/code/CMakeLists.txt
@@ -0,0 +1,24 @@
+cmake_minimum_required(VERSION 3.14)
+project(qt5app LANGUAGES CXX)
+
+if (WIN32)
+#! [appicon_windows]
+    set(APP_ICON_RESOURCE_WINDOWS "${CMAKE_CURRENT_SOURCE_DIR}/qt5app.rc")
+    add_executable(qt5app main.cpp ${APP_ICON_RESOURCE_WINDOWS})
+#! [appicon_windows]
+elseif (APPLE)
+#! [appicon_macOS]
+    # NOTE: Don't include the path in MACOSX_BUNDLE_ICON_FILE -- this is
+    # the property added to Info.plist
+    set(MACOSX_BUNDLE_ICON_FILE qt5app.icns)
+
+    # And this part tells CMake where to find and install the file itself
+    set(APP_ICON_MACOSX ${CMAKE_CURRENT_SOURCE_DIR}/qt5app.icns)
+    set_source_files_properties(${APP_ICON_MACOSX} PROPERTIES
+           MACOSX_PACKAGE_LOCATION "Resources")
+
+    add_executable(qt5app MACOSX_BUNDLE main.cpp ${APP_ICON_MACOSX})
+#! [appicon_macOS]
+else()
+    add_executable(qt5app main.cpp)
+endif()