Doc: Document how to use static plugins with CMake

Also, update the existing QTPLUGIN example to import a plugin that is
not imported by default.  This is closer what one would do in reality.

Make the CMake examples match the qmake ones.

Move text that describes CMake and qmake to the start of the section,
and add a subsection for CMake and qmake each.

Fixes: QTBUG-91413
Change-Id: Ie67518dc8757c69f382067a7225c72ff0b512ff8
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
Reviewed-by: Alexey Edelev <alexey.edelev@qt.io>
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
(cherry picked from commit 456b4078252e615e35ae8c4157f1e2c645aeace0)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

3 files changed, 74 insertions, 30 deletions

diff --git a/doc/snippets/plugins/doc_src_plugins-howto.cmake b/doc/snippets/plugins/doc_src_plugins-howto.cmake
new file mode 100644
index 00000000..78157d60
--- /dev/null
+++ b/doc/snippets/plugins/doc_src_plugins-howto.cmake
@@ -0,0 +1,21 @@
+#! [import_plugins]
+qt_import_plugins(myapp INCLUDE Qt::QLibInputPlugin)
+#! [import_plugins]
+
+#! [import_minimal_plugin]
+qt_import_plugins(myapp
+    INCLUDE_BY_TYPE platforms Qt::MinimalIntegrationPlugin
+)
+#! [import_minimal_plugin]
+
+#! [some_imageformat_plugins]
+qt_import_plugins(myapp
+    INCLUDE_BY_TYPE imageformats Qt::QJpegPlugin Qt::QGifPlugin
+)
+#! [some_imageformat_plugins]
+
+#! [no_imageformats_plugins]
+qt_import_plugins(myapp
+    EXCLUDE_BY_TYPE imageformats
+)
+#! [no_imageformats_plugins]
diff --git a/doc/snippets/plugins/doc_src_plugins-howto.pro b/doc/snippets/plugins/doc_src_plugins-howto.pro
index 4840c6d1..c6971e93 100644
--- a/doc/snippets/plugins/doc_src_plugins-howto.pro
+++ b/doc/snippets/plugins/doc_src_plugins-howto.pro
@@ -57,9 +57,7 @@ QTPLUGIN.platforms = qminimal
 #! [4]
 
 #! [5]
-QTPLUGIN     += qjpeg \
-                qgif \
-                qkrcodecs
+QTPLUGIN += qlibinputplugin
 #! [5]
 
 #! [6]
diff --git a/doc/src/howtos/plugins-howto.qdoc b/doc/src/howtos/plugins-howto.qdoc
index 6eecc0a7..55071908 100644
--- a/doc/src/howtos/plugins-howto.qdoc
+++ b/doc/src/howtos/plugins-howto.qdoc
@@ -304,19 +304,54 @@
     functionality from plugins can be added without a complete rebuild
     and redistribution of the application.
 
-    To link plugins statically, you need to add
-    the required plugins to your build using \c QTPLUGIN.
+    CMake and qmake automatically add the plugins that are typically needed by
+    the Qt modules used, while more specialized plugins need to be added
+    manually. The default list of automatically added plugins can be overridden
+    per type.
+
+    The defaults are tuned towards an optimal out-of-the-box experience, but may
+    unnecessarily bloat the application. It is recommended to inspect the linker
+    command line and eliminate unnecessary plugins.
+
+    To cause static plugins actually being linked and instantiated,
+    Q_IMPORT_PLUGIN() macros are also needed in application code, but those are
+    automatically generated by the build system and added to your application
+    project.
+
+    \section2 Importing Static Plugins in CMake
+
+    To statically link plugins in a CMake project, you need to call the
+    \l{qt6_import_plugins}{qt_import_plugins} command.
+
+    For example, the Linux \c libinput plugin is not imported by default. The
+    following command imports it:
+
+    \snippet plugins/doc_src_plugins-howto.cmake import_plugins
+
+    To link the minimal platform integration plugin instead of the default Qt
+    platform adaptation plugin, use:
+
+    \snippet plugins/doc_src_plugins-howto.cmake import_minimal_plugin
 
-    In the \c .pro file for your application, you need the following
-    entry:
+    Another typical use case is to link only a certain set of \c imageformats
+    plugins:
+
+    \snippet plugins/doc_src_plugins-howto.cmake some_imageformat_plugins
+
+    If you want to prevent the linking of any \c imageformats plugin, use:
+
+    \snippet plugins/doc_src_plugins-howto.cmake no_imageformats_plugins
+
+    If you want to turn off the addition of any default plugin, use the \c
+    NO_DEFAULT option of \l{qt6_import_plugins}{qt_import_plugins}.
+
+    \section2 Importing Static Plugins in qmake
+
+    In a qmake project, you need to add the required plugins to your build using
+    \c{QTPLUGIN}:
 
     \snippet plugins/doc_src_plugins-howto.pro 5
 
-    qmake automatically adds the plugins to QTPLUGIN that are typically
-    needed by the Qt modules used (see \l QT), while more specialized
-    plugins need to be added manually.
-    The default list of automatically added plugins can be overridden
-    per type.
     For example, to link the minimal plugin instead of the default Qt
     platform adaptation plugin, use:
 
@@ -327,18 +362,6 @@
 
     \snippet plugins/doc_src_plugins-howto.pro 6
 
-    The defaults are tuned towards an optimal out-of-the-box experience,
-    but may unnecessarily bloat the application.
-    It is recommended to inspect the linker command line built by qmake
-    and eliminate unnecessary plugins.
-
-    \section2 Details of Linking Static Plugins
-
-    To cause static plugins actually being linked and instantiated,
-    Q_IMPORT_PLUGIN() macros are also needed in application code,
-    but those are automatically generated by qmake and added to
-    your application project.
-
     If you do not want all plugins added to QTPLUGIN to be automatically
     linked, remove \c import_plugins from the \c CONFIG variable:
 
@@ -350,21 +373,23 @@
     following these steps:
 
     \list 1
-    \li Add \c{CONFIG += static} to your plugin's \c .pro file.
+    \li Pass the \c STATIC option to the \l{qt6_add_plugin}{qt_add_plugin}
+        command in your \c{CMakeLists.txt}. For a qmake project, add \c{CONFIG
+        += static} to your plugin's \c .pro file.
     \li Use the Q_IMPORT_PLUGIN() macro in your application.
     \li Use the Q_INIT_RESOURCE() macro in your application if the plugin ships
        qrc files.
-    \li Link your application with your plugin library using \c LIBS
-       in the \c .pro file.
+    \li Link your application with your plugin library using \l{CMake
+        target_link_libraries Documentation}{target_link_libraries} in your
+        \c{CMakeLists.txt} or \c LIBS in your \c .pro file.
     \endlist
 
     See the \l{tools/plugandpaint/app}{Plug & Paint} example and the
     associated \l{tools/plugandpaint/plugins/basictools}{Basic Tools}
     plugin for details on how to do this.
 
-    \note If you are not using qmake to build your plugin you need
-    to make sure that the \c{QT_STATICPLUGIN} preprocessor macro is
-    defined.
+    \note If you are not using CMake or qmake to build your plugin, you need to
+    make sure that the \c{QT_STATICPLUGIN} preprocessor macro is defined.
 
     \section1 Deploying and Debugging Plugins