diff options
author | Craig Scott <craig.scott@qt.io> | 2021-09-22 15:57:09 +1000 |
---|---|---|
committer | Craig Scott <craig.scott@qt.io> | 2021-09-24 22:07:24 +1000 |
commit | 3ce0672143d2eb3c3809f82998a4d71c5800d77a (patch) | |
tree | 134336d69dcb8692c59b8c2c26bba30de0322551 /src/corelib/doc | |
parent | d3a622f8173c3c9cde4b29f7c984c7c48bfc18cc (diff) |
Add docs for qt_set_finalizer_mode()
Task-number: QTBUG-95712
Pick-to: 6.2 6.2.0
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>
Diffstat (limited to 'src/corelib/doc')
-rw-r--r-- | src/corelib/doc/src/cmake/qt_add_executable.qdoc | 1 | ||||
-rw-r--r-- | src/corelib/doc/src/cmake/qt_finalize_target.qdoc | 2 | ||||
-rw-r--r-- | src/corelib/doc/src/cmake/qt_set_finalizer_mode.qdoc | 113 |
3 files changed, 116 insertions, 0 deletions
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 + +*/ |