// 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
\target 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

*/