qt_add_qml_plugin | Qt QML 6.4.1

- Qt 6.4
- Qt QML
- qt_add_qml_plugin
- Qt 6.4.1 Reference Documentation

# 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.