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 | |
parent | d3a622f8173c3c9cde4b29f7c984c7c48bfc18cc (diff) | |
download | qtbase-3ce0672143d2eb3c3809f82998a4d71c5800d77a.tar.gz |
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>
-rw-r--r-- | src/corelib/Qt6CoreMacros.cmake | 20 | ||||
-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 |
4 files changed, 116 insertions, 20 deletions
diff --git a/src/corelib/Qt6CoreMacros.cmake b/src/corelib/Qt6CoreMacros.cmake index 8e3564e36e..526738b16a 100644 --- a/src/corelib/Qt6CoreMacros.cmake +++ b/src/corelib/Qt6CoreMacros.cmake @@ -954,26 +954,6 @@ if(NOT QT_NO_CREATE_VERSIONLESS_FUNCTIONS) endif() # This function is currently in Technical Preview. It's signature may change or be removed entirely. - -# This function allows enabling or disabling finalizer modes for a specific target. -# Currently, the only supported finalizer mode is for plugin importing in static Qt builds which -# is called 'static_plugins'. You can enable / disable it by calling -# -# qt6_set_finalizer_mode(${target} ENABLE MODES "static_plugins") -# qt6_set_finalizer_mode(${target} DISABLE MODES "static_plugins") -# -# When the "static_plugins" finalizer mode is enabled, all plugins initializer object libraries are -# directly linked to the given ${target} (executable or shared library). -# This prevents cycles between Qt provided static libraries and reduces link time, thanks to the -# libraries not being repeated on the link line because they are not part of a cycle anymore. -# -# When the finalizer mode is disabled, each plugin initializer is propagated via usage requirements -# of its associated module, which may cause cycles in the current build system implementation. -# -# The "static_plugins" finalizer mode is enabled by default if: -# - the project calls qt_finalize_target explicitly at the end of the project file or -# - the project uses qt_add_executable and a CMake version greater than or equal to 3.19 -# (which will DEFER CALL qt_finalize_target) function(qt6_set_finalizer_mode target) cmake_parse_arguments(arg "ENABLE;DISABLE" "" "MODES" ${ARGN}) if(NOT arg_ENABLE AND NOT arg_DISABLE) 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 + +*/ |