qt_add_plugin

Creates a Qt plugin target.

The command is defined in the Core component of the Qt6 package, which can be loaded like so:

find_package(Qt6 REQUIRED COMPONENTS Core)

This command was introduced in Qt 6.0.

Synopsis

qt_add_plugin(target
              [SHARED | STATIC]
              [CLASS_NAME class_name]
              [OUTPUT_TARGETS variable_name]
              [MANUAL_FINALIZATION]
              sources...
)

The MANUAL_FINALIZATION option and the ability to set sources were introduced in Qt 6.5.

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

Description

Qt plugin targets have additional requirements over and above an ordinary CMake library target. The qt_add_plugin() command adds the necessary handling to ensure these requirements are met. It should be called rather than the built-in CMake add_library() command when defining a Qt plugin target.

By default, the plugin will be created as a STATIC library if Qt was built statically, or as a MODULE library otherwise. You can override this default by explicitly providing the STATIC or SHARED option.

Any sources provided will be passed through to the internal call to add_library().

Note: Non-static plugins are meant to be loaded dynamically at runtime, not linked to at build time. CMake differentiates between these two scenarios by providing the MODULE library type for dynamically loaded libraries, and the SHARED library type for libraries that may be linked to directly. This distinction is important for some toolchains (notably Visual Studio), due to the way symbol exports are handled. It may not be possible to link to MODULE libraries, and generating a SHARED library with no exported symbols can result in build-time errors. If the SHARED option is passed to qt_add_plugin(), it will therefore create a MODULE library rather than a SHARED library.

Every Qt plugin has a class name. By default, this will be the same as the target, but it can be overridden with the CLASS_NAME option. The class name corresponds to the name of the C++ class that declares the metadata for the plugin. For static plugins, it is also the name passed to Q_IMPORT_PLUGIN, which imports the plugin into an application and ensures it is available at run time.

If the plugin is built statically, qt_add_plugin() may define additional internal targets. These facilitate automatic importing of the plugin for any executable or shared library that links to the plugin. If the project installs the plugin and intends to make it available for other projects to link to, the project should also install these internal targets. The names of these targets can be obtained by providing the OUTPUT_TARGETS option, followed by the name of a variable in which to return the target list.

Finalization

After a target is created, further processing or finalization steps may be needed. The finalization processing is implemented by the qt_finalize_target() command.

For details and the meaning of the MANUAL_FINALIZATION option, refer to the finalization documentation for qt_add_library.

See also qt_finalize_target() and qt_add_executable().

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.