Add docs for qt_set_finalizer_mode()

Task-number: QTBUG-95712
Change-Id: Ie7b9282cfc6a27415db5e623a66317c9681c3991
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
Reviewed-by: Joerg Bornemann <joerg.bornemann@qt.io>
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
(cherry picked from commit 3ce0672143d2eb3c3809f82998a4d71c5800d77a)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

4 files changed, 116 insertions, 20 deletions

diff --git a/src/corelib/Qt6CoreMacros.cmake b/src/corelib/Qt6CoreMacros.cmake
index a35943ca7f..a927d4b91e 100644
--- a/src/corelib/Qt6CoreMacros.cmake
+++ b/src/corelib/Qt6CoreMacros.cmake
@@ -927,26 +927,6 @@ if(NOT QT_NO_CREATE_VERSIONLESS_FUNCTIONS)
 endif()
 
 # This function is currently in Technical Preview. It's signature may change or be removed entirely.
-
-# This function allows enabling or disabling finalizer modes for a specific target.
-# Currently, the only supported finalizer mode is for plugin importing in static Qt builds which
-# is called 'static_plugins'. You can enable / disable it by calling
-#
-#   qt6_set_finalizer_mode(${target} ENABLE MODES "static_plugins")
-#   qt6_set_finalizer_mode(${target} DISABLE MODES "static_plugins")
-#
-# When the "static_plugins" finalizer mode is enabled, all plugins initializer object libraries are
-# directly linked to the given ${target} (executable or shared library).
-# This prevents cycles between Qt provided static libraries and reduces link time, thanks to the
-# libraries not being repeated on the link line because they are not part of a cycle anymore.
-#
-# When the finalizer mode is disabled, each plugin initializer is propagated via usage requirements
-# of its associated module, which may cause cycles in the current build system implementation.
-#
-# The "static_plugins" finalizer mode is enabled by default if:
-#   - the project calls qt_finalize_target explicitly at the end of the project file or
-#   - the project uses qt_add_executable and a CMake version greater than or equal to 3.19
-#     (which will DEFER CALL qt_finalize_target)
 function(qt6_set_finalizer_mode target)
     cmake_parse_arguments(arg "ENABLE;DISABLE" "" "MODES" ${ARGN})
     if(NOT arg_ENABLE AND NOT arg_DISABLE)
diff --git a/src/corelib/doc/src/cmake/qt_add_executable.qdoc b/src/corelib/doc/src/cmake/qt_add_executable.qdoc
index e240086059..5248a12ed0 100644
--- a/src/corelib/doc/src/cmake/qt_add_executable.qdoc
+++ b/src/corelib/doc/src/cmake/qt_add_executable.qdoc
@@ -97,6 +97,7 @@ yourself instead at some later time. In general, \c MANUAL_FINALIZATION should
 not be needed unless the project has to support CMake 3.18 or earlier.
 
 \sa {qt6_finalize_target}{qt_finalize_target()},
+    {qt6_set_finalizer_mode}{qt_set_finalizer_mode()},
     {qt6_add_library}{qt_add_library()}
 
 \section1 Examples
diff --git a/src/corelib/doc/src/cmake/qt_finalize_target.qdoc b/src/corelib/doc/src/cmake/qt_finalize_target.qdoc
index 0d01e52227..408b4fb4b0 100644
--- a/src/corelib/doc/src/cmake/qt_finalize_target.qdoc
+++ b/src/corelib/doc/src/cmake/qt_finalize_target.qdoc
@@ -57,6 +57,8 @@ This command is ordinarily invoked as part of a call to
 place and when it might need to be called explicitly by a project is discussed
 in the documentation of those commands.
 
+\sa {qt6_set_finalizer_mode}{qt_set_finalizer_mode()}
+
 \section1 Executable Targets
 
 For executable targets, \c{qt_finalize_target()} implements the logic described
diff --git a/src/corelib/doc/src/cmake/qt_set_finalizer_mode.qdoc b/src/corelib/doc/src/cmake/qt_set_finalizer_mode.qdoc
new file mode 100644
index 0000000000..7697920b44
--- /dev/null
+++ b/src/corelib/doc/src/cmake/qt_set_finalizer_mode.qdoc
@@ -0,0 +1,113 @@
+/****************************************************************************
+**
+** Copyright (C) 2021 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\page qt_set_finalizer_mode.html
+\ingroup cmake-macros-qtcore
+
+\title qt_set_finalizer_mode
+\target qt6_set_finalizer_mode
+
+\brief Customizes aspects of a target's finalization.
+
+\preliminarycmakecommand
+
+\section1 Synopsis
+
+\badcode
+qt_set_finalizer_mode(target
+    ENABLE | DISABLE
+    MODES modes...
+)
+\endcode
+
+\versionlessCMakeCommandsNote qt6_set_finalizer_mode()
+
+\section1 Description
+
+This command is used to customize some aspects of the finalization of a
+specific \c target. It only has an effect if called before \c target is
+finalized, which occurs in one of the following scenarios:
+
+\list
+\li The project explicitly calls \l{qt6_finalize_target}{qt_finalize_target()}
+    for the \c target. This usually means the \c MANUAL_FINALIZATION keyword was
+    passed to \l{qt6_add_executable}{qt_add_executable()} when the \c target
+    was defined.
+\li CMake 3.17 or earlier is being used, in which case finalization always
+    occurs immediately as part of the call to
+    \l{qt6_add_executable}{qt_add_executable()}.
+\li CMake 3.18 or later is being used, the \c MANUAL_FINALIZATION keyword was
+    not passed to \l{qt6_add_executable}{qt_add_executable()} when the \c target
+    was defined, and deferred finalization has been completed at the end of the
+    \c target's directory scope.
+\endlist
+
+\c{qt_set_finalizer_mode()} is used to enable or disable a list of \e modes,
+where a mode corresponds to a specific aspect of finalization. The currently
+supported finalization modes are:
+
+\table
+\header
+    \li Mode
+    \li Default
+    \li Finalization behavior
+\row
+    \li \c static_plugins
+    \li Enabled
+    \li When Qt is built statically, it creates initializer object libraries
+        for its static plugins. If \c target is an executable and this
+        finalization mode is enabled, any plugin initializer object libraries
+        needed by the \c target will be directly linked to it. This
+        prevents cycles between Qt-provided static libraries and may reduce
+        link time. When this finalizer mode is disabled, each plugin
+        initializer is instead propagated via usage requirements of its
+        associated Qt library, which may cause cycles. If Qt is not built
+        statically, this finalizer mode is not relevant and isn't used.
+\endtable
+
+\sa {qt6_finalize_target}{qt_finalize_target()}
+
+\section1 Example
+
+The following example assumes you are using CMake 3.19 or later (required for
+deferred finalization):
+
+\badcode
+qt_add_executable(my_app main.cpp)
+qt_set_finalizer_mode(my_app ENABLE MODES static_plugins)
+\endcode
+
+The same example using manual finalization might look like this:
+
+\badcode
+qt_add_executable(my_app MANUAL_FINALIZATION main.cpp)
+qt_set_finalizer_mode(my_app ENABLE MODES static_plugins)
+qt_finalize_target(my_app)
+\endcode
+
+*/