CMake: document qt6_am_add_systemui_wrapper

Fixes: AUTOSUITE-1673
Change-Id: I95bb5768aa96f35a9941ea29492d52eb789d4075
Reviewed-by: Dominik Holland <dominik.holland@qt.io>

14 files changed, 96 insertions, 8 deletions

diff --git a/doc/cmake-integration.qdoc b/doc/cmake-integration.qdoc
new file mode 100644
index 00000000..3b538ce7
--- /dev/null
+++ b/doc/cmake-integration.qdoc
@@ -0,0 +1,16 @@
+// Copyright (C) 2022 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+
+\page cmake-integration.html
+\title CMake Integration
+\ingroup qtappman
+\brief Qt Application Manager specific CMake functionality.
+
+The QtAppManMainPrivate package provides the following CMake functions:
+
+\section3 Commands
+\annotatedlist cmake-macros-qtapplicationmanager
+
+*/
diff --git a/doc/index.qdoc b/doc/index.qdoc
index b132fd43..b97c647f 100644
--- a/doc/index.qdoc
+++ b/doc/index.qdoc
@@ -30,6 +30,7 @@ For a high-level overview, see \l{The Qt Application Manager}{Introduction to th
     \li \l{QtApplicationManager QML module}
     \li \l{QtApplicationManager.SystemUI QML module}
     \li \l{QtApplicationManager.Application QML module}
+    \li \l{CMake Integration}
 \endlist
 
 \section1 Examples
diff --git a/doc/online/style/qt5-sidebar.html b/doc/online/style/qt5-sidebar.html
index d228b696..d7f9f3d5 100644
--- a/doc/online/style/qt5-sidebar.html
+++ b/doc/online/style/qt5-sidebar.html
@@ -36,7 +36,8 @@
     <ul>
         <li><a href="manifest.html">Manifest Definition</a></li>
         <li><a href="qml-common.html">QtApplicationManager</a></li>
-        <li><a href="qml-sysui.html">SystemUI</a></li>
-        <li><a href="qml-apps.html">Application</a></li>
+        <li><a href="qml-sysui.html">QtApplicationManager.SystemUI</a></li>
+        <li><a href="qml-apps.html">QtApplicationManager.Application</a></li>
+        <li><a href="cmake-integration.html">CMake Integration</a></li>
     </ul>
 </div>
diff --git a/examples/applicationmanager/animated-windows/CMakeLists.txt b/examples/applicationmanager/animated-windows/CMakeLists.txt
index 74f3341a..09c475b9 100644
--- a/examples/applicationmanager/animated-windows/CMakeLists.txt
+++ b/examples/applicationmanager/animated-windows/CMakeLists.txt
@@ -19,6 +19,7 @@ find_package(Qt6 COMPONENTS Gui)
 find_package(Qt6 COMPONENTS AppManMainPrivate)
 
 qt6_am_add_systemui_wrapper(animated-windows
+    INSTALL_DIR "${INSTALL_EXAMPLEDIR}"
     CONFIG_YAML am-config.yaml
     EXTRA_FILES apps system-ui
 )
diff --git a/examples/applicationmanager/application-features/CMakeLists.txt b/examples/applicationmanager/application-features/CMakeLists.txt
index 4f186e9f..156d16a4 100644
--- a/examples/applicationmanager/application-features/CMakeLists.txt
+++ b/examples/applicationmanager/application-features/CMakeLists.txt
@@ -17,6 +17,7 @@ set(INSTALL_EXAMPLEDIR "${INSTALL_EXAMPLESDIR}/applicationmanager/application-fe
 find_package(Qt6 COMPONENTS AppManMainPrivate)
 
 qt6_am_add_systemui_wrapper(application-features
+    INSTALL_DIR "${INSTALL_EXAMPLEDIR}"
     CONFIG_YAML am-config.yaml
     EXTRA_FILES apps system-ui
 )
diff --git a/examples/applicationmanager/frame-timer/CMakeLists.txt b/examples/applicationmanager/frame-timer/CMakeLists.txt
index 184db902..2f10f349 100644
--- a/examples/applicationmanager/frame-timer/CMakeLists.txt
+++ b/examples/applicationmanager/frame-timer/CMakeLists.txt
@@ -19,6 +19,7 @@ find_package(Qt6 COMPONENTS Gui)
 find_package(Qt6 COMPONENTS AppManMainPrivate)
 
 qt6_am_add_systemui_wrapper(frame-timer
+    INSTALL_DIR "${INSTALL_EXAMPLEDIR}"
     CONFIG_YAML am-config.yaml
     EXTRA_FILES apps system-ui
 )
diff --git a/examples/applicationmanager/hello-world/CMakeLists.txt b/examples/applicationmanager/hello-world/CMakeLists.txt
index 9924a982..6910033d 100644
--- a/examples/applicationmanager/hello-world/CMakeLists.txt
+++ b/examples/applicationmanager/hello-world/CMakeLists.txt
@@ -19,6 +19,7 @@ find_package(Qt6 COMPONENTS Gui)
 find_package(Qt6 COMPONENTS AppManMainPrivate)
 
 qt6_am_add_systemui_wrapper(hello-world
+    INSTALL_DIR "${INSTALL_EXAMPLEDIR}"
     MAIN_QML_FILE system-ui.qml
     EXTRA_FILES apps
     EXTRA_ARGS --builtin-apps-manifest-dir apps
diff --git a/examples/applicationmanager/intents/CMakeLists.txt b/examples/applicationmanager/intents/CMakeLists.txt
index b3c38a93..b7ce5dc7 100644
--- a/examples/applicationmanager/intents/CMakeLists.txt
+++ b/examples/applicationmanager/intents/CMakeLists.txt
@@ -19,6 +19,7 @@ find_package(Qt6 COMPONENTS Gui)
 find_package(Qt6 COMPONENTS AppManMainPrivate)
 
 qt6_am_add_systemui_wrapper(intents
+    INSTALL_DIR "${INSTALL_EXAMPLEDIR}"
     CONFIG_YAML am-config.yaml
     EXTRA_FILES apps shared
 )
diff --git a/examples/applicationmanager/launch-intents/CMakeLists.txt b/examples/applicationmanager/launch-intents/CMakeLists.txt
index 1216e644..55dd795a 100644
--- a/examples/applicationmanager/launch-intents/CMakeLists.txt
+++ b/examples/applicationmanager/launch-intents/CMakeLists.txt
@@ -19,6 +19,7 @@ find_package(Qt6 COMPONENTS Gui)
 find_package(Qt6 COMPONENTS AppManMainPrivate)
 
 qt6_am_add_systemui_wrapper(launch-intents
+    INSTALL_DIR "${INSTALL_EXAMPLEDIR}"
     MAIN_QML_FILE system-ui.qml
     EXTRA_FILES apps
     EXTRA_ARGS --builtin-apps-manifest-dir apps
diff --git a/examples/applicationmanager/minidesk/CMakeLists.txt b/examples/applicationmanager/minidesk/CMakeLists.txt
index 630f3502..1153d9f6 100644
--- a/examples/applicationmanager/minidesk/CMakeLists.txt
+++ b/examples/applicationmanager/minidesk/CMakeLists.txt
@@ -19,6 +19,7 @@ find_package(Qt6 COMPONENTS Gui)
 find_package(Qt6 COMPONENTS AppManMainPrivate)
 
 qt6_am_add_systemui_wrapper(minidesk
+    INSTALL_DIR "${INSTALL_EXAMPLEDIR}"
     CONFIG_YAML am-config.yaml
     EXTRA_FILES apps system-ui
     EXTRA_ARGS --verbose
diff --git a/examples/applicationmanager/multi-views/CMakeLists.txt b/examples/applicationmanager/multi-views/CMakeLists.txt
index 1b4e9676..ba362645 100644
--- a/examples/applicationmanager/multi-views/CMakeLists.txt
+++ b/examples/applicationmanager/multi-views/CMakeLists.txt
@@ -19,6 +19,7 @@ find_package(Qt6 COMPONENTS Gui)
 find_package(Qt6 COMPONENTS AppManMainPrivate)
 
 qt6_am_add_systemui_wrapper(multi-views
+    INSTALL_DIR "${INSTALL_EXAMPLEDIR}"
     CONFIG_YAML am-config.yaml
     EXTRA_FILES apps system-ui
     EXTRA_ARGS --verbose
diff --git a/examples/applicationmanager/process-status/CMakeLists.txt b/examples/applicationmanager/process-status/CMakeLists.txt
index 03628e04..e25872fb 100644
--- a/examples/applicationmanager/process-status/CMakeLists.txt
+++ b/examples/applicationmanager/process-status/CMakeLists.txt
@@ -19,6 +19,7 @@ find_package(Qt6 COMPONENTS Gui)
 find_package(Qt6 COMPONENTS AppManMainPrivate)
 
 qt6_am_add_systemui_wrapper(process-status
+    INSTALL_DIR "${INSTALL_EXAMPLEDIR}"
     CONFIG_YAML am-config.yaml
     EXTRA_FILES apps system-ui
     EXTRA_ARGS --verbose
diff --git a/src/main-lib/Qt6AppManMainPrivateMacros.cmake b/src/main-lib/Qt6AppManMainPrivateMacros.cmake
index 226e00e3..562113a4 100644
--- a/src/main-lib/Qt6AppManMainPrivateMacros.cmake
+++ b/src/main-lib/Qt6AppManMainPrivateMacros.cmake
@@ -7,8 +7,8 @@ function(qt_am_internal_create_copy_command file)
                         DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/${file}
                         COMMENT "Copying file: ${file}")
     endif()
-    if (NOT ARG_NO_INSTALL)
-        get_filename_component(dest ${INSTALL_EXAMPLEDIR}/${file} DIRECTORY)
+    if (ARG_INSTALL_DIR)
+        get_filename_component(dest ${ARG_INSTALL_DIR}/${file} DIRECTORY)
         install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/${file}
             DESTINATION ${dest}
         )
@@ -19,7 +19,7 @@ function(qt6_am_add_systemui_wrapper target)
     cmake_parse_arguments(
         PARSE_ARGV 1
         ARG
-        "NO_INSTALL" "MAIN_QML_FILE;EXECUTABLE" "CONFIG_YAML;EXTRA_FILES;EXTRA_ARGS"
+        "" "MAIN_QML_FILE;EXECUTABLE;INSTALL_DIR" "CONFIG_YAML;EXTRA_FILES;EXTRA_ARGS"
     )
 
     if (NOT ARG_EXECUTABLE)
@@ -121,9 +121,9 @@ exec ${ARG_EXECUTABLE} ${CMD_ARGS_STR} ${CMD_EXTRA_ARGS_STR} ${ARG_MAIN_QML_FILE
         COMMAND ${CMAKE_COMMAND} -E copy ${WRAPPER_SCRIPT} $<TARGET_FILE_NAME:${target}>
     )
 
-    if (NOT ARG_NO_INSTALL)
+    if (ARG_INSTALL_DIR)
         install(PROGRAMS $<TARGET_FILE:${target}>
-            DESTINATION "${INSTALL_EXAMPLEDIR}"
+            DESTINATION "${ARG_INSTALL_DIR}"
         )
     endif()
 endfunction()
@@ -214,7 +214,6 @@ function (qt_am_internal_add_qml_test target)
             qt6_am_add_systemui_wrapper(${target}_${CONFIG_ARG_NAME}
                 EXECUTABLE appman-qmltestrunner
                 MAIN_QML_FILE ${ARG_TEST_FILE}
-                NO_INSTALL
                 ${EXTRA_FILES_ARG_STR}
                 ${WRAPPER_ARGS}
             )
diff --git a/src/main-lib/cmake-macros.qdoc b/src/main-lib/cmake-macros.qdoc
new file mode 100644
index 00000000..d5ff3879
--- /dev/null
+++ b/src/main-lib/cmake-macros.qdoc
@@ -0,0 +1,62 @@
+// Copyright (C) 2021 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+\page cmake-qt6-am-add-systemui-wrapper.html
+\ingroup cmake-macros-qtapplicationmanager
+
+\title qt_am_add_systemui_wrapper
+\target qt6_am_add_systemui_wrapper
+
+\brief Creates a basic wrapper script to run a System UI using the appman binary.
+
+\section1 Synopsis
+
+\badcode
+qt_am_add_systemui_wrapper(
+    target
+    [EXECUTABLE appman-executable]
+    [MAIN_QML_FILE main.qml]
+    [CONFIG_YAML config.yaml ...]
+    [EXTRA_ARGS ...]
+    [EXTRA_FILES ...]
+    [INSTALL_DIR install-dir]
+)
+\endcode
+
+\versionlessCMakeCommandsNote qt6_am_add_systemui_wrapper()
+
+\section1 Description
+
+Generates a \c .bat (Windows) or \c .sh (macOS, Linux) wrapper in the build directory to easily run
+your QML based System UI referenced by \c target on the desktop or within Qt Creator. It will also
+automatically copy the required files from the source to the build directory: these are the \c
+MAIN_QML_FILE, any \c CONFIG_YAML files as well as all \c EXTRA_FILES.
+
+If you also want this command to automatically generate installation rules for all files, you can
+specify the destination directory via \c INSTALL_DIR. By default, no installation rule is created.
+
+If you want to use a custom build of the application manager, you can do that by using \c
+EXECUTABLE. Otherwise, the \c appman binary of the current Qt build will be used.
+
+All \c EXTRA_ARGS will be appended to the command line when running the \c EXECUTABLE from the
+wrapper script.
+
+For very simple setups, specifying just the \c MAIN_QML_FILE is enough. If you already have an \c
+am-config.yaml, you can reference that via \c CONFIG_YAML. In case your main.qml is already set in
+the YAML config file, you do not need to specify it here again.
+
+Please note that this command will not scale when your project is becoming more sophisticated over
+time. It is only meant to help you get started without diving too deep into CMake.
+
+\section1 Examples
+
+Here is a snippet from the \l applicationmanager/minidesk example, showing how this function is
+used there:
+
+\quotefromfile applicationmanager/minidesk/CMakeLists.txt
+
+\skipto qt6_am_add_systemui_wrapper
+\printuntil /^\)/
+
+*/