diff options
Diffstat (limited to 'src/corelib/doc/src/cmake/qt_import_plugins.qdoc')
-rw-r--r-- | src/corelib/doc/src/cmake/qt_import_plugins.qdoc | 97 |
1 files changed, 97 insertions, 0 deletions
diff --git a/src/corelib/doc/src/cmake/qt_import_plugins.qdoc b/src/corelib/doc/src/cmake/qt_import_plugins.qdoc new file mode 100644 index 0000000000..1f81a21cd2 --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_import_plugins.qdoc @@ -0,0 +1,97 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-import-plugins.html +\ingroup cmake-commands-qtcore + +\title qt_import_plugins +\keyword qt6_import_plugins + +\summary {Specifies a custom set of plugins to import or exclude.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 5.14 + +\section1 Synopsis + +\badcode +qt_import_plugins(target + [INCLUDE plugin ...] + [EXCLUDE plugin ...] + [INCLUDE_BY_TYPE plugin_type plugin ...] + [EXCLUDE_BY_TYPE plugin_type] + [NO_DEFAULT] +) +\endcode + +\versionlessCMakeCommandsNote qt6_import_plugins() + +\section1 Description + +Specifies a custom set of plugins to import. The optional arguments: +\c INCLUDE, \c EXCLUDE, \c INCLUDE_BY_TYPE, and \c EXCLUDE_BY_TYPE, +can be used more than once. + +\list +\li \c INCLUDE -- can be used to specify a list of plugins to import. +\li \c EXCLUDE -- can be used to specify a list of plugins to exclude. +\li \c INCLUDE_BY_TYPE -- can be used to override the list of plugins to + import for a certain plugin type. +\li \c EXCLUDE_BY_TYPE -- can be used to specify a plugin type to exclude; + then no plugins of that type are imported. +\li \c NO_DEFAULT -- prevent the default plugins from being included + automatically (for example, the default platform plugin). +\endlist + +Qt provides plugin types such as \c imageformats, \c platforms, +and \c sqldrivers. + +\section2 Dynamic plugins + +If plugins are dynamic libraries, the function controls the plugin deployment. +Using this function, you may exclude specific plugin types from +being packaged into an Android APK, for example: + +\badcode +qt_add_executable(MyApp ...) +... +qt_import_plugins(MyApp EXCLUDE_BY_TYPE imageformats) +\endcode + +In the snippet above, all plugins that have the \c imageformats type will +be excluded when deploying \c MyApp. The resulting Android APK will not +contain any of the \c imageformats plugins. + +If the command isn't used, the target automatically deploys all plugins that +belong to the Qt modules that the target is linked against. + +\section2 Static plugins + +If the command isn't used the target automatically links against +a sane set of default static plugins, for each Qt module that the target is +linked against. For more information, see +\l{CMake target_link_libraries Documentation}{target_link_libraries}. + +Each plugin comes with a C++ stub file that automatically +initializes the static plugin. Consequently, any target that links against +a plugin has this C++ file added to its \c SOURCES. + +\section1 Examples + +\snippet cmake-macros/examples.cmake qt_import_plugins + +In the snippet above, the following occurs with the executable \c myapp: + +\list +\li The \c Qt6::QCocoaIntegrationPlugin is imported into myapp. +\li The \c Qt6::QMinimalIntegrationPlugin plugin is + excluded from being automatically imported into myapp. +\li The default list of plugins for \c imageformats is + overridden to only include Qt6::QGifPlugin and Qt6::QJpegPlugin. +\li All \c sqldrivers plugins are excluded from automatic importing. +\endlist + +\sa{qt6_import_qml_plugins}{qt_import_qml_plugins()} +*/ |