cmake: move the qt_am_create_package command from examples to main-lib

This will be in TP for 6.7 until we gain more experience with the new
QtCreator integration.

Change-Id: I9a9efac81a9f6d4994be6e47fee3090fe75d181a
Pick-to: 6.7
Reviewed-by: Dominik Holland <dominik.holland@qt.io>

3 files changed, 143 insertions, 39 deletions

diff --git a/examples/applicationmanager/package-installation/CMakeLists.txt b/examples/applicationmanager/package-installation/CMakeLists.txt
index caded9d6..5d011e89 100644
--- a/examples/applicationmanager/package-installation/CMakeLists.txt
+++ b/examples/applicationmanager/package-installation/CMakeLists.txt
@@ -26,45 +26,6 @@ qt6_am_add_systemui_wrapper(package-installation
     EXTRA_ARGS --verbose
 )
 
-#TODO: check if it makes sense to expose this as public cmake API
-function(qt6_am_create_package target)
-    cmake_parse_arguments(
-        PARSE_ARGV 1
-        ARG
-        "" "SOURCE_DIR;OUTPUT_PACKAGE" ""
-    )
-
-    if (NOT ARG_SOURCE_DIR)
-        message(FATAL_ERROR "SOURCE_DIR needs to be provided")
-    endif()
-    if (NOT EXISTS "${ARG_SOURCE_DIR}/info.yaml")
-        message(FATAL_ERROR "SOURCE_DIR does not contain info.yaml")
-    endif()
-    if (NOT ARG_OUTPUT_PACKAGE)
-        message(FATAL_ERROR "OUTPUT_PACKAGE needs to be provided")
-    endif()
-
-    if (COMMAND qt_internal_collect_command_environment)
-        qt_internal_collect_command_environment(env_path env_plugin_path)
-    else()
-        set(env_path "${QT6_INSTALL_PREFIX}/${QT6_INSTALL_BINS}")
-        set(env_plugin_path "${QT6_INSTALL_PREFIX}/${QT6_INSTALL_PLUGINS}")
-    endif()
-
-    qt_am_internal_find_host_packager()
-
-    add_custom_command(
-        OUTPUT  ${ARG_OUTPUT_PACKAGE}
-        COMMAND ${CMAKE_COMMAND} -E env "PATH=${env_path}${QT_PATH_SEPARATOR}$ENV{PATH}"
-                    $<TARGET_FILE:${QT_CMAKE_EXPORT_NAMESPACE}::appman-packager>
-                    create-package ${ARG_OUTPUT_PACKAGE} ${ARG_SOURCE_DIR}
-        DEPENDS ${ARG_SOURCE_DIR}
-        VERBATIM
-    )
-    add_custom_target(${target} DEPENDS ${ARG_OUTPUT_PACKAGE})
-endfunction()
-
-
 foreach (PKG_NAME red green)
     qt6_am_create_package(package-installation-create-${PKG_NAME}-ampkg
         SOURCE_DIR     ${CMAKE_CURRENT_SOURCE_DIR}/installable-apps/hello-world.${PKG_NAME}/
diff --git a/src/main-lib/Qt6AppManMainPrivateMacros.cmake b/src/main-lib/Qt6AppManMainPrivateMacros.cmake
index a5baf8d3..c67749c2 100644
--- a/src/main-lib/Qt6AppManMainPrivateMacros.cmake
+++ b/src/main-lib/Qt6AppManMainPrivateMacros.cmake
@@ -266,3 +266,64 @@ function (qt_am_internal_add_qml_test target)
 
 endfunction()
 
+function(qt_am_internal_create_package target)
+    cmake_parse_arguments(
+        PARSE_ARGV 1
+        ARG
+        "BUILTIN" "SOURCE_DIR;OUTPUT_PACKAGE" ""
+    )
+
+    if (NOT ARG_SOURCE_DIR)
+        message(FATAL_ERROR "SOURCE_DIR needs to be provided")
+    endif()
+    if (NOT EXISTS "${ARG_SOURCE_DIR}/info.yaml")
+        message(FATAL_ERROR "SOURCE_DIR does not contain info.yaml")
+    endif()
+    if (NOT ARG_BUILTIN AND NOT ARG_OUTPUT_PACKAGE)
+        message(FATAL_ERROR "OUTPUT_PACKAGE needs to be provided")
+    endif()
+
+    if (COMMAND qt_internal_collect_command_environment)
+        qt_internal_collect_command_environment(env_path env_plugin_path)
+    else()
+        set(env_path "${QT6_INSTALL_PREFIX}/${QT6_INSTALL_BINS}")
+        set(env_plugin_path "${QT6_INSTALL_PREFIX}/${QT6_INSTALL_PLUGINS}")
+    endif()
+
+    qt_am_internal_find_host_packager()
+
+    if (ARG_BUILTIN)
+        add_custom_target(${target})
+    else()
+        add_custom_command(
+            OUTPUT  ${ARG_OUTPUT_PACKAGE}
+            COMMAND ${CMAKE_COMMAND} -E env "PATH=${env_path}${QT_PATH_SEPARATOR}$ENV{PATH}"
+                        $<TARGET_FILE:${QT_CMAKE_EXPORT_NAMESPACE}::appman-packager>
+                        create-package ${ARG_OUTPUT_PACKAGE} ${ARG_SOURCE_DIR}
+            DEPENDS ${ARG_SOURCE_DIR}
+            VERBATIM
+        )
+        add_custom_target(${target} DEPENDS ${ARG_OUTPUT_PACKAGE})
+    endif()
+
+    target_sources(${target} PRIVATE ${ARG_SOURCE_DIR}/info.yaml)
+
+endfunction()
+
+# in tech-preview state (6.7)
+function(qt6_am_create_installable_package target)
+    qt_am_internal_create_package(${target} ${ARGN})
+endfunction()
+
+function(qt6_am_create_builtin_package target)
+    qt_am_internal_create_package(${target} ${ARGN} BUILTIN)
+endfunction()
+
+if(NOT QT_NO_CREATE_VERSIONLESS_FUNCTIONS)
+    function(qt_am_create_installable_package)
+        qt6_am_create_installable_package(${ARGV})
+    endfunction()
+    function(qt_am_create_builtin_package)
+        qt6_am_create_builtin_package(${ARGV})
+    endfunction()
+endif()
diff --git a/src/main-lib/cmake-macros.qdoc b/src/main-lib/cmake-macros.qdoc
index 62c4157a..5487af74 100644
--- a/src/main-lib/cmake-macros.qdoc
+++ b/src/main-lib/cmake-macros.qdoc
@@ -68,3 +68,85 @@ used there:
 \printuntil /^\)/
 
 */
+
+/*!
+\page cmake-qt6_am_create_installable_package.html
+\ingroup cmake-macros-qtapplicationmanager
+
+\title qt_am_create_installable_package
+\target qt6_am_create_installable_package
+
+\brief Uses the appman-packager tool to package applications.
+
+\preliminarycmakecommand
+
+\section1 Synopsis
+
+\badcode
+qt_am_create_installable_package(
+    target
+    SOURCE_DIR <dir>
+    OUTPUT_PACKAGE <package.ampkg>
+)
+\endcode
+
+\versionlessCMakeCommandsNote qt6_am_create_installable_package()
+
+\section1 Description
+
+Adds a custom \c target that, when executed, uses the \l{Packager}{appman-packager} tool to create
+a package for the application found in \c SOURCE_DIR. The result is written to \c OUTPUT_PACKAGE.
+
+The complete content of the source directory is packaged, which works out of the box for QML-only
+applications, but needs installation rules to temporary directories for more sophisticated setups
+(e.g. QML plugins).
+
+The \c info.yaml manifest from \c SOURCE_DIR is added as source file to the \c target.
+
+\note This function will serve as an anchor for the application manager's QtCreator integration
+      to discover the available packages in a System UI.
+
+\section1 Examples
+
+Here is a snippet from the \l applicationmanager/package-installation example, showing how this
+function is used there:
+
+\quotefromfile applicationmanager/package-installation/CMakeLists.txt
+\skipto foreach
+\printuntil endforeach
+
+*/
+
+/*!
+\page cmake-qt6_am_create_builtin_package.html
+\ingroup cmake-macros-qtapplicationmanager
+
+\title qt6_am_create_builtin_package
+\target qt6_am_create_builtin_package
+
+\brief Marks a directory containing a package as built-in.
+
+\preliminarycmakecommand
+
+\section1 Synopsis
+
+\badcode
+qt6_am_create_builtin_package(
+    target
+    SOURCE_DIR <dir>
+)
+\endcode
+
+\versionlessCMakeCommandsNote qt6_am_create_builtin_package()
+
+\section1 Description
+
+Adds a custom \c target, containing the \c info.yaml manifest from \c SOURCE_DIR as source file.
+
+This is a dummy function that works exactly like \l qt_am_create_installable_package, but for
+built-in packages.
+
+\note This function will serve as an anchor for the application manager's QtCreator integration
+      to discover the available packages in a System UI.
+
+*/