diff options
Diffstat (limited to 'src/corelib/doc/src/cmake/qt_add_plugin.qdoc')
-rw-r--r-- | src/corelib/doc/src/cmake/qt_add_plugin.qdoc | 87 |
1 files changed, 87 insertions, 0 deletions
diff --git a/src/corelib/doc/src/cmake/qt_add_plugin.qdoc b/src/corelib/doc/src/cmake/qt_add_plugin.qdoc new file mode 100644 index 0000000000..d2322086e7 --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_add_plugin.qdoc @@ -0,0 +1,87 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-add-plugin.html +\ingroup cmake-commands-qtcore + +\title qt_add_plugin +\keyword qt6_add_plugin + +\summary {Creates a Qt plugin target.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 6.0 + +\section1 Synopsis + +\badcode +qt_add_plugin(target + [SHARED | STATIC] + [CLASS_NAME class_name] + [OUTPUT_TARGETS variable_name] + [MANUAL_FINALIZATION] + sources... +) +\endcode + +The \c MANUAL_FINALIZATION option and the ability to set sources +were introduced in Qt 6.5. + +\versionlessCMakeCommandsNote qt6_add_plugin() + +\section1 Description + +Qt plugin targets have additional requirements over and above an ordinary CMake +library target. The \c{qt_add_plugin()} command adds the necessary handling to +ensure these requirements are met. It should be called rather than the built-in +CMake \c{add_library()} command when defining a Qt plugin target. + +By default, the plugin will be created as a \c STATIC library if Qt was built +statically, or as a \c MODULE library otherwise. You can override this default +by explicitly providing the \c STATIC or \c SHARED option. + +Any \c{sources} provided will be passed through to the internal call to +\c{add_library()}. + +\note Non-static plugins are meant to be loaded dynamically at runtime, not +linked to at build time. CMake differentiates between these two scenarios by +providing the \c MODULE library type for dynamically loaded libraries, and +the \c SHARED library type for libraries that may be linked to directly. This +distinction is important for some toolchains (notably Visual Studio), due to +the way symbol exports are handled. It may not be possible to link to +\c MODULE libraries, and generating a \c SHARED library with no exported +symbols can result in build-time errors. If the \c SHARED option is passed to +\c{qt_add_plugin()}, it will therefore create a \c MODULE library rather than a +\c SHARED library. + +Every Qt plugin has a class name. By default, this will be the same as the +\c target, but it can be overridden with the \c CLASS_NAME option. The class +name corresponds to the name of the C++ class that declares the metadata for +the plugin. For static plugins, it is also the name passed to +\l Q_IMPORT_PLUGIN, which imports the plugin into an application and ensures it +is available at run time. + +If the plugin is built statically, \c{qt_add_plugin()} may define additional +internal targets. These facilitate automatic importing of the plugin for any +executable or shared library that links to the plugin. If the project installs +the plugin and intends to make it available for other projects to link to, the +project should also install these internal targets. The names of these targets +can be obtained by providing the \c OUTPUT_TARGETS option, followed by the name +of a variable in which to return the target list. + +\section2 Finalization + +After a target is created, further processing or \e{finalization} steps may be +needed. The finalization processing is implemented by the +\l{qt6_finalize_target}{qt_finalize_target()} command. + +For details and the meaning of the \c{MANUAL_FINALIZATION} option, refer to the +\l{qt_add_library finalization}{finalization documentation} for +\c{qt_add_library}. + +\sa {qt6_finalize_target}{qt_finalize_target()}, + {qt6_add_executable}{qt_add_executable()} + +*/ |