1// Copyright (C) 2021 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
5\page qt-set-finalizer-mode.html
6\ingroup cmake-commands-qtcore
8\title qt_set_finalizer_mode
9\keyword qt6_set_finalizer_mode
11\summary {Customizes aspects of a target's finalization.}
14\preliminarycmakecommand
19qt_set_finalizer_mode(target
25\versionlessCMakeCommandsNote qt6_set_finalizer_mode()
29This command is used to customize some aspects of the finalization of a
30specific \c target. It only has an effect if called before \c target is
31finalized, which occurs in one of the following scenarios:
34\li The project explicitly calls \l{qt6_finalize_target}{qt_finalize_target()}
35 for the \c target. This usually means the \c MANUAL_FINALIZATION keyword was
36 passed to \l{qt6_add_executable}{qt_add_executable()} when the \c target
38\li CMake 3.17 or earlier is being used, in which case finalization always
39 occurs immediately as part of the call to
40 \l{qt6_add_executable}{qt_add_executable()}.
41\li CMake 3.18 or later is being used, the \c MANUAL_FINALIZATION keyword was
42 not passed to \l{qt6_add_executable}{qt_add_executable()} when the \c target
43 was defined, and deferred finalization has been completed at the end of the
44 \c target's directory scope.
47\c{qt_set_finalizer_mode()} is used to enable or disable a list of \e modes,
48where a mode corresponds to a specific aspect of finalization. The currently
49supported finalization modes are:
55 \li Finalization behavior
59 \li When Qt is built statically, it creates initializer object libraries
60 for its static plugins. If \c target is an executable and this
61 finalization mode is enabled, any plugin initializer object libraries
62 needed by the \c target will be directly linked to it. This
63 prevents cycles between Qt-provided static libraries and may reduce
64 link time. When this finalizer mode is disabled, each plugin
65 initializer is instead propagated via usage requirements of its
66 associated Qt library, which may cause cycles. If Qt is not built
67 statically, this finalizer mode is not relevant and isn't used.
70\sa {qt6_finalize_target}{qt_finalize_target()}
74The following example assumes you are using CMake 3.19 or later (required for
75deferred finalization):
78qt_add_executable(my_app main.cpp)
79qt_set_finalizer_mode(my_app ENABLE MODES static_plugins)
82The same example using manual finalization might look like this:
85qt_add_executable(my_app MANUAL_FINALIZATION main.cpp)
86qt_set_finalizer_mode(my_app ENABLE MODES static_plugins)
87qt_finalize_target(my_app)