1 files changed, 90 insertions, 0 deletions
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..28622c11e8
--- /dev/null
+++ b/src/corelib/doc/src/cmake/qt_set_finalizer_mode.qdoc
@@ -0,0 +1,90 @@
+// Copyright (C) 2021 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+\page qt-set-finalizer-mode.html
+\ingroup cmake-commands-qtcore
+
+\title qt_set_finalizer_mode
+\keyword qt6_set_finalizer_mode
+
+\summary {Customizes aspects of a target's finalization.}
+
+\cmakecommandsince 6.2
+\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
+
+*/