CMake: Introduce qt_generate_deploy_script

Should the deployment script that qt_generate_deploy_app_script not be
sufficient, the new function qt_generate_deploy_script can be used to
generate a custom deployment script.  Before, one had to add quite some
boilerplate code to generate a custom deployment script.

The qt_generate_deploy_app_script function now uses
qt_generate_deploy_script internally.

The TARGET option of qt_generate_deploy_script is currently only used
for controlling the base name of the generated deployment script.  We
will do more with the target in a subsequent commit.

Fixes: QTBUG-105731
Change-Id: I85bfc50dac1f0b0b1aae0f657f803e9e30f53616
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>

5 files changed, 105 insertions, 11 deletions

diff --git a/src/corelib/doc/snippets/cmake-macros/deployment.cmake b/src/corelib/doc/snippets/cmake-macros/deployment.cmake
new file mode 100644
index 0000000000..c5979a9ff2
--- /dev/null
+++ b/src/corelib/doc/snippets/cmake-macros/deployment.cmake
@@ -0,0 +1,27 @@
+# Copyright (C) 2022 The Qt Company Ltd.
+# SPDX-License-Identifier: BSD-3-Clause
+
+#! [qt_generate_deploy_script_example]
+cmake_minimum_required(VERSION 3.16...3.22)
+project(MyThings)
+
+find_package(Qt6 REQUIRED COMPONENTS Core)
+qt_standard_project_setup()
+
+qt_add_executable(MyApp main.cpp)
+
+install(TARGETS MyApp
+    BUNDLE  DESTINATION .
+    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
+)
+
+qt_generate_deploy_script(
+    TARGET MyApp
+    FILENAME_VARIABLE deploy_script
+    CONTENT "
+qt_deploy_runtime_dependencies(
+    EXECUTABLE $<TARGET_FILE_NAME:MyApp>
+)
+")
+install(SCRIPT ${deploy_script})
+#! [qt_generate_deploy_script_example]
diff --git a/src/corelib/doc/src/cmake/qt_deploy_qt_conf.qdoc b/src/corelib/doc/src/cmake/qt_deploy_qt_conf.qdoc
index 4f2b638835..e295b213e9 100644
--- a/src/corelib/doc/src/cmake/qt_deploy_qt_conf.qdoc
+++ b/src/corelib/doc/src/cmake/qt_deploy_qt_conf.qdoc
@@ -64,10 +64,9 @@ as shown in the example below. This helps avoid hard-coding an absolute path.
 
 \badcode
 # The following script must only be executed at install time
-set(deploy_script "${CMAKE_CURRENT_BINARY_DIR}/deploy_custom.cmake")
-
-file(GENERATE OUTPUT ${deploy_script} CONTENT "
-include(\"${QT_DEPLOY_SUPPORT}\")
+qt_generate_deploy_script(
+    FILENAME_VARIABLE deploy_script
+    CONTENT "
 qt_deploy_qt_conf(\"\${QT_DEPLOY_PREFIX}/\${QT_DEPLOY_BIN_DIR}/qt.conf\"
     DATA_DIR \"./custom_data_dir\"
     TRANSLATIONS_DIR \"./custom_translations_dir\"
diff --git a/src/corelib/doc/src/cmake/qt_generate_deploy_app_script.qdoc b/src/corelib/doc/src/cmake/qt_generate_deploy_app_script.qdoc
index b3a3328098..e3e4901512 100644
--- a/src/corelib/doc/src/cmake/qt_generate_deploy_app_script.qdoc
+++ b/src/corelib/doc/src/cmake/qt_generate_deploy_app_script.qdoc
@@ -59,7 +59,11 @@ For deploying a QML application, use
 \l{qt6_generate_deploy_qml_app_script}{qt_generate_deploy_qml_app_script()}
 instead.
 
+For generating a custom deployment script, use
+\l{qt6_generate_deploy_script}{qt_generate_deploy_script}.
+
 \sa {qt6_standard_project_setup}{qt_standard_project_setup()},
+    {qt6_generate_deploy_script}{qt_generate_deploy_script()},
     {qt6_generate_deploy_qml_app_script}{qt_generate_deploy_qml_app_script()}
 
 \section1 Example
diff --git a/src/corelib/doc/src/cmake/qt_generate_deploy_script.qdoc b/src/corelib/doc/src/cmake/qt_generate_deploy_script.qdoc
new file mode 100644
index 0000000000..17ef93f26c
--- /dev/null
+++ b/src/corelib/doc/src/cmake/qt_generate_deploy_script.qdoc
@@ -0,0 +1,66 @@
+// Copyright (C) 2022 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+\page qt_generate_deploy_script.html
+\ingroup cmake-commands-qtcore
+
+\title qt_generate_deploy_script
+\target qt6_generate_deploy_script
+
+\summary {Generate a custom deployment script.}
+
+\include cmake-find-package-core.qdocinc
+
+\cmakecommandsince 6.5
+\preliminarycmakecommand
+
+\section1 Synopsis
+
+\badcode
+qt_generate_deploy_script(
+    FILENAME_VARIABLE var_name
+    [TARGET target]
+    [NAME script_name]
+    [CONTENT content]
+)
+\endcode
+
+\versionlessCMakeCommandsNote qt6_generate_deploy_script()
+
+\section1 Description
+
+The command generates a script whose full file path will be stored in the
+variable named by the \c{FILENAME_VARIABLE} option. That script is only written
+at CMake generation time. It is intended to be used with the \l{install(SCRIPT)}
+command, which should come after the application's target has been installed
+using \l{install(TARGETS)}.
+
+The command takes care of generating a file named suitably for multi-config
+generators. Necessary includes are added such that Qt's CMake deployment
+functions and variables are accessible.
+
+The \c TARGET argument specifies the target that will be deployed by the script.
+This affects the file name of the generated script, unless \c NAME is specified.
+
+The \c NAME argument controls an identifiable portion within the deployment
+script's automatically generated name. The \c NAME argument defaults to \c
+custom if neither \c NAME nor \c TARGET are given.
+
+The \c CONTENT argument specifies the code that is written to the deployment
+script. The content may contain generator expressions.
+
+This command is intended for generating custom deployment scripts that
+directly call functions of Qt's deployment API. For less complex
+deployment purposes, it is more convenient to use
+\l{qt6_generate_deploy_app_script}{qt_generate_deploy_app_script()} or
+\l{qt6_generate_deploy_qml_app_script}{qt_generate_deploy_qml_app_script()}.
+
+\sa {qt6_generate_deploy_app_script}{qt_generate_deploy_app_script()},
+    {qt6_generate_deploy_qml_app_script}{qt_generate_deploy_qml_app_script()}
+
+\section1 Example
+
+\snippet cmake-macros/deployment.cmake qt_generate_deploy_script_example
+
+*/
diff --git a/src/corelib/doc/src/includes/cmake-deploy-runtime-dependencies.qdocinc b/src/corelib/doc/src/includes/cmake-deploy-runtime-dependencies.qdocinc
index 3c7fb8d5ee..26503ddece 100644
--- a/src/corelib/doc/src/includes/cmake-deploy-runtime-dependencies.qdocinc
+++ b/src/corelib/doc/src/includes/cmake-deploy-runtime-dependencies.qdocinc
@@ -23,13 +23,11 @@ endif()
 qt_add_executable(HelperApp helper.cpp)
 set(helper_app_path "\${QT_DEPLOY_BIN_DIR}/$<TARGET_FILE_NAME:HelperApp>")
 
-# The following script must only be executed at install time
-set(deploy_script "${CMAKE_CURRENT_BINARY_DIR}/deploy_MyApp.cmake")
-
-file(GENERATE OUTPUT ${deploy_script} CONTENT "
-# Including the file pointed to by QT_DEPLOY_SUPPORT ensures the generated
-# deployment script has access to qt_deploy_runtime_dependencies()
-include(\"${QT_DEPLOY_SUPPORT}\")
+# Generate a deployment script to be executed at install time
+qt_generate_deploy_script(
+    TARGET MyApp
+    FILENAME_VARIABLE deploy_script
+    CONTENT "
 qt_deploy_runtime_dependencies(
     EXECUTABLE \"${executable_path}\"
     ADDITIONAL_EXECUTABLES \"${helper_app_path}\"