CMake: Clean up qt_deploy_runtime_dependencies for 6.3

Ensure both versioned and versionless functions
are available.

Use the versioned function in the implementation of
qt6_generate_deploy_app_script.

Move the low-level warning to the top of the documentation page,
after the TP message.

Clarify documentation of the EXECUTABLE and
ADDITIONAL_ options, that they take relative paths and can use
generator expressions, but can't reference raw target names.

Adjust documentation snippet to cover mac / windows cases.
This mostly coincides with the internal implementation of
qt_generate_deploy_app_script.
Also adjust it to show case more options, like installation of a
helper app and its dependencies.

Output the working directory when executing the deploy tool.

Remove the MACOS_BUNDLE option, it serves no good purpose at the
moment, we already detect bundles by checking if the dir name has
an '.app' suffix.

Fixes: QTBUG-100923
Change-Id: If7e5d65ce920eb69fd45f004aa4c5bad800c7ba9
Reviewed-by: Alexey Edelev <alexey.edelev@qt.io>
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
(cherry picked from commit 0ada264dda533cd3be2699330a5c1e2dd27a0e6a)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

4 files changed, 66 insertions, 22 deletions

diff --git a/src/corelib/Qt6CoreDeploySupport.cmake b/src/corelib/Qt6CoreDeploySupport.cmake
index f3318ce404..a9d2dfe955 100644
--- a/src/corelib/Qt6CoreDeploySupport.cmake
+++ b/src/corelib/Qt6CoreDeploySupport.cmake
@@ -104,14 +104,13 @@ endif()
 
 # This function is currently in Technical Preview.
 # Its signature and behavior might change.
-function(qt_deploy_runtime_dependencies)
+function(qt6_deploy_runtime_dependencies)
 
     if(NOT __QT_DEPLOY_TOOL)
         message(FATAL_ERROR "No Qt deploy tool available for this target platform")
     endif()
 
     set(no_value_options
-        MACOS_BUNDLE
         GENERATE_QT_CONF
         VERBOSE
         NO_OVERWRITE
@@ -162,7 +161,7 @@ function(qt_deploy_runtime_dependencies)
 
     # macdeployqt always writes out a qt.conf file. It will complain if one
     # already exists, so leave it to create it for us if we will be running it.
-    if(MACOS_BUNDLE AND __QT_DEPLOY_SYSTEM_NAME STREQUAL Darwin)
+    if(__QT_DEPLOY_SYSTEM_NAME STREQUAL Darwin)
         # We might get EXECUTABLE pointing to either the actual binary under the
         # Contents/MacOS directory, or it might be pointing to the top of the
         # app bundle (i.e. the <appname>.app directory). We want the latter to
@@ -239,7 +238,8 @@ function(qt_deploy_runtime_dependencies)
         list(APPEND tool_options "${extra_binaries_option}${extra_binary}")
     endforeach()
 
-    message(STATUS "Running Qt deploy tool for ${arg_EXECUTABLE}")
+    message(STATUS
+        "Running Qt deploy tool for ${arg_EXECUTABLE} in working directory '${QT_DEPLOY_PREFIX}'")
     execute_process(
         COMMAND_ECHO STDOUT
         COMMAND "${__QT_DEPLOY_TOOL}" "${arg_EXECUTABLE}" ${tool_options}
@@ -252,6 +252,16 @@ function(qt_deploy_runtime_dependencies)
 
 endfunction()
 
+if(NOT __QT_NO_CREATE_VERSIONLESS_FUNCTIONS)
+    function(qt_deploy_runtime_dependencies)
+        if(__QT_DEFAULT_MAJOR_VERSION EQUAL 6)
+            qt6_deploy_runtime_dependencies(${ARGV})
+        else()
+            message(FATAL_ERROR "qt_deploy_runtime_dependencies() is only available in Qt 6.")
+        endif()
+    endfunction()
+endif()
+
 function(_qt_internal_show_skip_runtime_deploy_message qt_build_type_string)
     message(STATUS
         "Skipping runtime deployment steps. "
diff --git a/src/corelib/Qt6CoreMacros.cmake b/src/corelib/Qt6CoreMacros.cmake
index 4785d528d0..b0a5fad15f 100644
--- a/src/corelib/Qt6CoreMacros.cmake
+++ b/src/corelib/Qt6CoreMacros.cmake
@@ -2684,16 +2684,15 @@ function(qt6_generate_deploy_app_script)
         endif()
         file(GENERATE OUTPUT "${file_name}" CONTENT "
 include(${QT_DEPLOY_SUPPORT})
-qt_deploy_runtime_dependencies(
+qt6_deploy_runtime_dependencies(
     EXECUTABLE $<TARGET_FILE_NAME:${arg_TARGET}>.app
-    MACOS_BUNDLE
 )
 ")
 
     elseif(WIN32 AND QT6_IS_SHARED_LIBS_BUILD)
         file(GENERATE OUTPUT "${file_name}" CONTENT "
 include(${QT_DEPLOY_SUPPORT})
-qt_deploy_runtime_dependencies(
+qt6_deploy_runtime_dependencies(
     EXECUTABLE \${QT_DEPLOY_BIN_DIR}/$<TARGET_FILE_NAME:${arg_TARGET}>
     GENERATE_QT_CONF
 )")
diff --git a/src/corelib/doc/src/cmake/qt_deploy_runtime_dependencies.qdoc b/src/corelib/doc/src/cmake/qt_deploy_runtime_dependencies.qdoc
index 817dbef980..a9554187dd 100644
--- a/src/corelib/doc/src/cmake/qt_deploy_runtime_dependencies.qdoc
+++ b/src/corelib/doc/src/cmake/qt_deploy_runtime_dependencies.qdoc
@@ -42,13 +42,15 @@ project during the configure stage.
 
 \cmakecommandsince 6.3
 \preliminarycmakecommand
+\note This command does not usually need to be called directly. It is used
+      internally by other higher level commands, but projects wishing to
+      implement more customized deployment logic may find it useful.
 
 \section1 Synopsis
 
 \badcode
 qt_deploy_runtime_dependencies(
     EXECUTABLE executable
-    [MACOS_BUNDLE]
     [ADDITIONAL_EXECUTABLES files...]
     [ADDITIONAL_LIBRARIES files...]
     [ADDITIONAL_MODULES files...]
@@ -65,10 +67,6 @@ qt_deploy_runtime_dependencies(
 
 \section1 Description
 
-\note This command does not usually need to be called directly. It is used
-      internally by other higher level commands, but projects wishing to
-      implement more customized deployment logic may find it useful.
-
 When installing an application, it may be desirable to also install the
 libraries and plugins it depends on. When the application is a macOS app bundle
 or a Windows executable, \c{qt_deploy_runtime_dependencies()} can be called
@@ -82,22 +80,35 @@ see \l{qt_deploy_qml_imports()} for that.
 
 \section1 Arguments
 
-The \c{EXECUTABLE} option must be provided. The \c{executable} argument should
-be the path relative to the base install location. For macOS app bundles, the
-\c{MACOS_BUNDLE} option should be given and the \c{executable} argument should
-be the path to the executable in the \c{<bundle-name>.app/Contents/MacOS}
-directory.
+The \c{EXECUTABLE} option must be provided.
+
+The \c{executable} argument should be a path to the executable file, relative to
+the base install location. For example, \c{bin/MyApp.exe}, or more dynamically
+\c{\${QT_DEPLOY_BIN_DIR}/$<TARGET_FILE_NAME:MyApp>}.
+Specifying raw target names not wrapped in a generator epxression like
+\c{<TARGET_FILE_NAME:>} is not supported.
+
+For macOS app bundles, the \c{executable} argument should be a path to the
+bundle directory, relative to the base install location.
+For example \c{MyApp.app}, or more dynamically
+\c{$<TARGET_FILE_NAME:MyApp>.app}.
+Specifying raw target names not wrapped in a generator epxression like
+\c{<TARGET_FILE_NAME:>} is not supported.
 
 It may also be desirable to install dependencies for other binaries related to
 the \c{executable}. For example, plugins provided by the project might have
 further dependencies, but because those plugins won't be linked directly to the
 executable, \c{qt_deploy_runtime_dependencies()} won't automatically discover
 them. The \c{ADDITIONAL_EXECUTABLES}, \c{ADDITIONAL_LIBRARIES}, and
-\c{ADDITIONAL_MODULES} arguments can be used to specify additional binaries
+\c{ADDITIONAL_MODULES} options can be used to specify additional binaries
 whose dependencies should also be deployed (installing the named binaries
 themselves is still the project's responsibility). The naming of these keywords
 follows CMake's conventions, so Qt plugins would be specified using
 \c{ADDITIONAL_MODULES}.
+Each value should be a path relative to the base install location. The values
+can use generator expressions, same as with the \c{EXECUTABLE} option.
+Specifying raw target names not wrapped in a generator epxression like
+\c{<TARGET_FILE_NAME:>} is not supported.
 
 When installing a Windows application, it is common to need a
 \l{Using qt.conf}{qt.conf} file when following CMake's default install
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 291bfcfe5c..5ac43a98b2 100644
--- a/src/corelib/doc/src/includes/cmake-deploy-runtime-dependencies.qdocinc
+++ b/src/corelib/doc/src/includes/cmake-deploy-runtime-dependencies.qdocinc
@@ -7,16 +7,40 @@ qt_standard_project_setup()
 
 qt_add_executable(MyApp main.cpp)
 
+set_target_properties(MyApp PROPERTIES
+    WIN32_EXECUTABLE TRUE
+    MACOSX_BUNDLE TRUE
+)
+
+# App bundles on macOS have an .app suffix
+if(APPLE)
+    set(executable_path "$<TARGET_FILE_NAME:MyApp>.app")
+else()
+    set(executable_path "\${QT_DEPLOY_BIN_DIR}/$<TARGET_FILE_NAME:MyApp>")
+endif()
+
+# Helper app, not necessarily built as part of this project.
+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 "
 include(\"${QT_DEPLOY_SUPPORT}\")
 qt_deploy_runtime_dependencies(
-    EXECUTABLE \"\${QT_DEPLOY_BIN_DIR}/$<TARGET_FILE_NAME:MyApp>\"
-)
-")
+    EXECUTABLE \"${executable_path}\"
+    ADDITIONAL_EXECUTABLES \"${helper_app_path}\"
+    GENERATE_QT_CONF
+    VERBOSE
+)")
 
-install(TARGETS MyApp)              # Install the target
+# Omitting RUNTIME DESTINATION will install a non-bundle target to CMAKE_INSTALL_BINDIR,
+# which coincides with the default value of QT_DEPLOY_BIN_DIR used above, './bin'.
+# Installing macOS bundles always requires an explicit BUNDLE DESTINATION option.
+install(TARGETS MyApp HelperApp    # Install to CMAKE_INSTALL_PREFIX/bin/MyApp.exe
+                                   #                           and ./binHelperApp.exe
+        BUNDLE  DESTINATION .      # Install to CMAKE_INSTALL_PREFIX/MyApp.app/Contents/MacOS/MyApp
+)
 install(SCRIPT ${deploy_script})    # Add its runtime dependencies
 \endcode