CMake: Introduce qt_configure_file

It has the same kind of signature as file(GENERATE) but
creates the files at configure time rather than generation time.

CMake provides a few ways to generate files
file(WRITE) -> always overrides content
configure_file() -> only overrides if content changes, creates file
                    at configure time, can only take a file as input
file(GENERATE)   -> only overrides if content changes, creats file
                    at generation time, can take a string or file
                    as input

Because dealing with an input file is a hassle (need to create one,
make sure it's installed, make sure it's used correctly in the
various build types like super-build, non-prefix-build, etc)
people tend to use file(GENERATE) instead, which can take a string
argument, and is thus easier to use.

Unfortunately that introduces subtle bugs because the
file is created at generation time, but there are existence
checks which are done at configuration time.

Thus qt_configure_file allows creation of files at configure time,
without having to provide an input file. Underneath it uses
configure_file(). Once CMake 3.18 is released, the implementation
can be switched to use file(CONFIGURE).

Change-Id: Ic8f8d88541ef0b25d01af143352c8c9ba390ad5f
Reviewed-by: Leander Beernaert <leander.beernaert@qt.io>
Reviewed-by: Simon Hausmann <simon.hausmann@qt.io>

cmake/QtBaseGlobalTargets.cmake

@@ -288,6 +288,7 @@ qt_copy_or_install(FILES
                    cmake/QtFeature.cmake
                    cmake/QtFindWrapHelper.cmake
                    cmake/QtFindWrapConfigExtra.cmake.in
+                   cmake/QtFileConfigure.txt.in
                    cmake/QtPlatformSupport.cmake
                    cmake/QtPlatformAndroid.cmake
                    cmake/QtPostProcess.cmake

cmake/QtBuild.cmake

@@ -3960,6 +3960,41 @@ function(qt_process_qlalr consuming_target input_file_list flags)
     endforeach()
 endfunction()
 
+
+# qt_configure_file(OUTPUT output-file <INPUT input-file | CONTENT content>)
+# input-file is relative to ${CMAKE_CURRENT_SOURCE_DIR}
+# output-file is relative to ${CMAKE_CURRENT_BINARY_DIR}
+#
+# This function is similar to file(GENERATE OUTPUT) except it writes the content
+# to the file at configure time, rather than at generate time. Once CMake 3.18 is released, it can use file(CONFIGURE) in its implmenetation. Until then, it
+# uses configure_file() with a generic input file as source, when used with the CONTENT signature.
+function(qt_configure_file)
+    qt_parse_all_arguments(arg "qt_configure_file" "" "OUTPUT;INPUT;CONTENT" "" ${ARGN})
+
+    if(NOT arg_OUTPUT)
+        message(FATAL_ERROR "No output file provided to qt_configure_file.")
+    endif()
+
+    if(arg_CONTENT)
+        set(template_name "QtFileConfigure.txt.in")
+        # When building qtbase, use the source template file.
+        # Otherwise use the installed file.
+        # This should work for non-prefix and superbuilds as well.
+        if(QtBase_SOURCE_DIR)
+            set(input_file "${QtBase_SOURCE_DIR}/cmake/${template_name}")
+        else()
+            set(input_file "${Qt6_DIR}/${template_name}")
+        endif()
+        set(__qt_file_configure_content "${arg_CONTENT}")
+    elseif(arg_INPUT)
+        set(input_file "${arg_INPUT}")
+    else()
+        message(FATAL_ERROR "No input value provided to qt_configure_file.")
+    endif()
+
+    configure_file("${input_file}" "${arg_OUTPUT}" @ONLY)
+endfunction()
+
 macro(qt_add_string_to_qconfig_cpp str)
     string(LENGTH "${str}" length)
     string(APPEND QT_CONFIG_STRS "    \"${str}\\0\"\n")

cmake/QtFileConfigure.txt.in

@@ -0,0 +1 @@
+@__qt_file_configure_content@