CMake: Clean up qt_deploy_qt_conf for 6.3

Ensure both versioned and versionless functions
are available.
Document that the first argument should be an absolute path
and check that in the code.
Move the low-level warning to the top, after the TP message.
Use a few more options in the doc snippet.
Mention what the default values are.

Pick-to: 6.3
Fixes: QTBUG-100922
Change-Id: I0d852733e51750f4c8f15721b707cb1d27dfee9a
Reviewed-by: Jörg Bornemann <joerg.bornemann@qt.io>

3 files changed, 34 insertions, 9 deletions

diff --git a/src/corelib/Qt6CoreDeploySupport.cmake b/src/corelib/Qt6CoreDeploySupport.cmake
index a116a0dc08..f3318ce404 100644
--- a/src/corelib/Qt6CoreDeploySupport.cmake
+++ b/src/corelib/Qt6CoreDeploySupport.cmake
@@ -6,7 +6,7 @@ cmake_minimum_required(VERSION 3.16...3.21)
 
 # This function is currently in Technical Preview.
 # Its signature and behavior might change.
-function(qt_deploy_qt_conf file_to_write)
+function(qt6_deploy_qt_conf qt_conf_absolute_path)
     set(no_value_options "")
     set(single_value_options
         PREFIX
@@ -33,6 +33,11 @@ function(qt_deploy_qt_conf file_to_write)
         message(FATAL_ERROR "Unparsed arguments: ${arg_UNPARSED_ARGUMENTS}")
     endif()
 
+    if(NOT IS_ABSOLUTE "${qt_conf_absolute_path}")
+        message(FATAL_ERROR
+                "Given qt.conf path is not an absolute path: '${qt_conf_absolute_path}'")
+    endif()
+
     # Only write out locations that differ from the defaults
     set(contents "[Paths]\n")
     if(arg_PREFIX)
@@ -83,10 +88,20 @@ function(qt_deploy_qt_conf file_to_write)
         string(APPEND contents "Settings = ${arg_SETTINGS_DIR}\n")
     endif()
 
-    message(STATUS "Writing ${file_to_write}")
-    file(WRITE "${file_to_write}" "${contents}")
+    message(STATUS "Writing ${qt_conf_absolute_path}")
+    file(WRITE "${qt_conf_absolute_path}" "${contents}")
 endfunction()
 
+if(NOT __QT_NO_CREATE_VERSIONLESS_FUNCTIONS)
+    function(qt_deploy_qt_conf)
+        if(__QT_DEFAULT_MAJOR_VERSION EQUAL 6)
+            qt6_deploy_qt_conf(${ARGV})
+        else()
+            message(FATAL_ERROR "qt_deploy_qt_conf() is only available in Qt 6.")
+        endif()
+    endfunction()
+endif()
+
 # This function is currently in Technical Preview.
 # Its signature and behavior might change.
 function(qt_deploy_runtime_dependencies)
@@ -166,7 +181,7 @@ function(qt_deploy_runtime_dependencies)
             string(REPEAT "../" ${path_count} rel_path)
             string(REGEX REPLACE "/+$" "" prefix "${rel_path}")
         endif()
-        qt_deploy_qt_conf("${QT_DEPLOY_PREFIX}/${exe_dir}/qt.conf"
+        qt6_deploy_qt_conf("${QT_DEPLOY_PREFIX}/${exe_dir}/qt.conf"
             PREFIX "${prefix}"
             BIN_DIR "${arg_BIN_DIR}"
             LIB_DIR "${arg_LIB_DIR}"
diff --git a/src/corelib/Qt6CoreMacros.cmake b/src/corelib/Qt6CoreMacros.cmake
index 3b1e8a83e1..d138149d0d 100644
--- a/src/corelib/Qt6CoreMacros.cmake
+++ b/src/corelib/Qt6CoreMacros.cmake
@@ -2563,6 +2563,8 @@ set(__QT_DEPLOY_VERBOSE \"${QT_ENABLE_VERBOSE_DEPLOYMENT}\")
 set(__QT_CMAKE_EXPORT_NAMESPACE \"${QT_CMAKE_EXPORT_NAMESPACE}\")
 set(__QT_DEPLOY_GENERATOR_IS_MULTI_CONFIG \"${is_multi_config}\")
 set(__QT_DEPLOY_ACTIVE_CONFIG \"$<CONFIG>\")
+set(__QT_NO_CREATE_VERSIONLESS_FUNCTIONS \"${QT_NO_CREATE_VERSIONLESS_FUNCTIONS}\")
+set(__QT_DEFAULT_MAJOR_VERSION \"${QT_DEFAULT_MAJOR_VERSION}\")
 
 # Define the CMake commands to be made available during deployment.
 set(__qt_deploy_support_files
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 2480c4e6a2..4c7f02e9e6 100644
--- a/src/corelib/doc/src/cmake/qt_deploy_qt_conf.qdoc
+++ b/src/corelib/doc/src/cmake/qt_deploy_qt_conf.qdoc
@@ -42,11 +42,14 @@ project.
 
 \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_qt_conf(file_name
+qt_deploy_qt_conf(file_path
     [PREFIX prefix]
     [DOC_DIR doc_dir]
     [HEADERS_DIR headers_dir]
@@ -71,10 +74,12 @@ during deployment. The default value of any path supported by \c{qt.conf} can
 be overridden with the corresponding \c{..._DIR} option. The command will only
 write a path to the generated \c{qt.conf} file if it differs from the default
 value.
+The default values can be found at \l{Overriding Paths}.
 
-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.
+The \c file_path argument expects an absolute path to the location where the
+\c qt.conf file should be written to. The \l{QT_DEPLOY_PREFIX} and \l{QT_DEPLOY_BIN_DIR}
+variables can be used to dynamically specify a path relative to the deployment binary directory,
+as shown in the example below. This helps avoid hard-coding an absolute path.
 
 \sa {qt6_generate_deploy_app_script}{qt_generate_deploy_app_script()},
     qt_deploy_runtime_dependencies()
@@ -87,7 +92,10 @@ set(deploy_script "${CMAKE_CURRENT_BINARY_DIR}/deploy_custom.cmake")
 
 file(GENERATE OUTPUT ${deploy_script} CONTENT "
 include(\"${QT_DEPLOY_SUPPORT}\")
-qt_deploy_qt_conf(\"\${QT_DEPLOY_BIN_DIR}/qt.conf\")
+qt_deploy_qt_conf(\"\${QT_DEPLOY_PREFIX}/\${QT_DEPLOY_BIN_DIR}/qt.conf\"
+    DATA_DIR \"./custom_data_dir\"
+    TRANSLATIONS_DIR \"./custom_translations_dir\"
+)
 ")
 
 install(SCRIPT ${deploy_script})