diff options
Diffstat (limited to 'src/corelib/doc/src/cmake/qt_set_finalizer_mode.qdoc')
-rw-r--r-- | src/corelib/doc/src/cmake/qt_set_finalizer_mode.qdoc | 90 |
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 + +*/ |