1 files changed, 120 insertions, 0 deletions
diff --git a/src/qml/doc/src/cmake/qt_add_qml_plugin.qdoc b/src/qml/doc/src/cmake/qt_add_qml_plugin.qdoc
new file mode 100644
index 0000000000..2ce744559c
--- /dev/null
+++ b/src/qml/doc/src/cmake/qt_add_qml_plugin.qdoc
@@ -0,0 +1,120 @@
+// Copyright (C) 2021 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+\page qt-add-qml-plugin.html
+\ingroup cmake-commands-qtqml
+
+\title qt_add_qml_plugin
+\target qt6_add_qml_plugin
+
+\brief Defines a plugin associated with a QML module.
+
+\section1 Synopsis
+
+\badcode
+qt_add_qml_plugin(
+    target
+    [BACKING_TARGET backing_target]
+    [STATIC | SHARED]
+    [OUTPUT_DIRECTORY]
+    [URI]
+    [CLASS_NAME]
+    [NO_GENERATE_PLUGIN_SOURCE]
+    [NAMESPACE namespace]
+)
+
+\endcode
+
+\versionlessCMakeCommandsNote qt6_add_qml_plugin()
+
+\section1 Description
+
+This command creates the plugin target associated with a QML module. It would
+normally be called internally by \l{qt6_add_qml_module}{qt_add_qml_module()} to
+create or update the plugin associated with its backing target. You should not
+call this function directly unless you have special circumstances that require
+you to create the target in a special way.
+
+The documentation for \l{qt6_add_qml_module}{qt_add_qml_module()} describes
+different structural patterns for how the CMake targets associated with a QML
+module can be arranged. Note that even if the QML module has no separate backing
+target and all functionality is implemented directly in the plugin (not the
+recommended arrangement), you should still call
+\l{qt6_add_qml_module}{qt_add_qml_module()} rather than \c{qt_add_qml_plugin()}.
+
+
+\section1 Arguments
+
+The \c target specifies the name of the target to use for the QML plugin. If it
+does not already exist, it will be created.
+
+\c BACKING_TARGET specifies the name of the backing target that the plugin is
+associated with. The backing target can be the same as the plugin \c target, in
+which case there is only the one merged target, but this is not typically
+recommended (see \l{qt6_add_qml_module}{qt_add_qml_module()} for more
+information). \c BACKING_TARGET should always be provided unless there are
+special circumstances that require the plugin target to be created before the
+backing target. If \c BACKING_TARGET is not provided, a \c URI option must be
+given.
+
+By default, the plugin is created with a type that is compatible with the
+backing target. If the backing target is a static library, the plugin will also
+be created as a static library. If the backing target is a shared library, the
+plugin will be created as a module library. Where no backing target is
+provided or the plugin has no separate backing target, the plugin type can be
+specified with either the \c STATIC or \c SHARED keywords. If the plugin type
+is not determined by any of the preceding conditions, a static plugin will be
+created if Qt was built as static libraries, or a module library plugin
+otherwise.
+
+\c OUTPUT_DIRECTORY specifies the directory where the plugin library will be
+created. It should always be the same location as the QML module's
+\l{Module Definition qmldir Files}{qmldir} file. When \c OUTPUT_DIRECTORY is
+not given, it will be obtained from information stored on the
+\c BACKING_TARGET, where available. Note that this could be different to the
+directory of the backing target's own library. If an output directory cannot be
+obtained from the backing target, the \c CMAKE_CURRENT_BINARY_DIR is used by
+default.
+
+\c URI declares the module identifier of the QML module this plugin is
+associated with. The module identifier is the (dotted URI notation) identifier
+for the QML module. If \c URI is not given, a \c BACKING_TARGET must be
+provided and the backing target must have its URI recorded on it (typically by
+an earlier call to \l{qt6_add_qml_module}{qt_add_qml_module()}).
+
+Each plugin should have a C++ class that registers the module with the QML
+engine. By default, \c{qt_add_qml_plugin()} auto-generates the sources for this
+C++ class, and adds them to the \c{target}'s list of sources. The generated
+plugin class satisfies the requirements of the plugin being optional (see
+\l{Module Definition qmldir Files}). The class name is determined as follows:
+
+\list
+  \li If \c CLASS_NAME has been given, it will be used. It must match the name
+      used in the QML module's \c qmldir file.
+  \li If \c CLASS_NAME has not been given, but \c BACKING_TARGET has, the C++
+      class name will be taken from details recorded on that backing target.
+      Those details are usually recorded by an earlier call to
+      \l{qt_add_qml_module}{qt_add_qml_module()}, and they will match the name
+      used in the generated \c qmldir file. This is the recommended way to
+      provide the class name in most scenarios.
+  \li If the class name still cannot be determined, it is set to the module's
+      URI with dots replaced by underscores, and \c Plugin appended.
+\endlist
+
+If a namespace is given with the \c NAMESPACE keyword, the plugin
+code will be generated into a C++ namespace of this name.
+
+Some plugins may require the plugin class to be written manually. For example,
+the plugin may need to perform additional initialization or register things
+not implemented by the default plugin class. In such cases, the
+\c NO_GENERATE_PLUGIN_SOURCE option can be given. You are then responsible for
+writing your own C++ plugin class and adding it to the \c target. Note that if
+you need to write your own plugin class, it is very unlikely that the plugin
+can be optional. This in turn means that the \c NO_PLUGIN_OPTIONAL keyword
+should be included in the call to \l{qt_add_qml_module}{qt_add_qml_module()}
+when defining the QML module, or else the generated \c qmldir file will be
+incorrect. Make sure your plugin class uses the same class name as determined
+from the logic just above.
+
+*/