qt_add_qml_plugin

Synopsis

qt_add_qml_plugin(
    target
    [BACKING_TARGET backing_target]
    [STATIC | SHARED]
    [OUTPUT_DIRECTORY]
    [URI]
    [CLASS_NAME]
    [NO_GENERATE_PLUGIN_SOURCE]
    [NAMESPACE namespace]
)

If versionless commands are disabled, use qt6_add_qml_plugin() instead. It supports the same set of arguments as this command.

Description

This command creates the plugin target associated with a QML module. It would normally be called internally by 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 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 qt_add_qml_module() rather than qt_add_qml_plugin().

Arguments

The target specifies the name of the target to use for the QML plugin. If it does not already exist, it will be created.

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 target, in which case there is only the one merged target, but this is not typically recommended (see qt_add_qml_module() for more information). BACKING_TARGET should always be provided unless there are special circumstances that require the plugin target to be created before the backing target. If BACKING_TARGET is not provided, a 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 STATIC or 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.

OUTPUT_DIRECTORY specifies the directory where the plugin library will be created. It should always be the same location as the QML module's qmldir file. When OUTPUT_DIRECTORY is not given, it will be obtained from information stored on the 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 CMAKE_CURRENT_BINARY_DIR is used by default.

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 URI is not given, a BACKING_TARGET must be provided and the backing target must have its URI recorded on it (typically by an earlier call to qt_add_qml_module()).

Each plugin should have a C++ class that registers the module with the QML engine. By default, qt_add_qml_plugin() auto-generates the sources for this C++ class, and adds them to the target's list of sources. The generated plugin class satisfies the requirements of the plugin being optional (see Module Definition qmldir Files). The class name is determined as follows:

• If CLASS_NAME has been given, it will be used. It must match the name used in the QML module's qmldir file.
• If CLASS_NAME has not been given, but 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 qt_add_qml_module(), and they will match the name used in the generated qmldir file. This is the recommended way to provide the class name in most scenarios.
• If the class name still cannot be determined, it is set to the module's URI with dots replaced by underscores, and Plugin appended.

If a namespace is given with the 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 NO_GENERATE_PLUGIN_SOURCE option can be given. You are then responsible for writing your own C++ plugin class and adding it to the 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 NO_PLUGIN_OPTIONAL keyword should be included in the call to qt_add_qml_module() when defining the QML module, or else the generated qmldir file will be incorrect. Make sure your plugin class uses the same class name as determined from the logic just above.