qt_add_qml_plugin.qdoc

Go to the documentation of this file.

// 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
\keyword qt6_add_qml_plugin
 
\brief Defines a plugin associated with a QML module.
 
\include cmake-find-package-qml.qdocinc
 
\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.
 
*/