ECMSetupQtPluginMacroNames — Extra CMake Modules 6.29.0 documentation

# ECMSetupQtPluginMacroNames

Instruct CMake’s automoc about C++ preprocessor macros used to define Qt-style plugins.

    ecm_setup_qtplugin_macro_names(
        [MACRO_NAMES <macro_name> [<macro_name> [...]]] # since 6.18
        [JSON_NONE <macro_name> [<macro_name> [...]]]
        [JSON_ARG1 <macro_name> [<macro_name> [...]]]
        [JSON_ARG2 <macro_name> [<macro_name> [...]]]
        [JSON_ARG3 <macro_name> [<macro_name> [...]]]
        [CONFIG_CODE_VARIABLE <variable_name>] )

CMake’s automoc needs some support when parsing C++ source files to detect whether moc should be run on those files and if there are also dependencies on other files, like those with Qt plugin metadata in JSON format. Because automoc just greps overs the raw plain text of the sources without any C++ preprocessor-like processing. CMake in newer versions provides the variable `CMAKE_AUTOMOC_MACRO_NAMES` (CMake >= 3.10) to allow the developer to assist automoc. For Qt up to version 5.15 additionally the variable `CMAKE_AUTOMOC_DEPEND_FILTERS` (CMake >= 3.9.0) can be used.

This macro cares for the explicit setup needed for those variables for common cases of C++ preprocessor macros used for Qt-style plugins.

`MACRO_NAMES` lists the names of C++ preprocessor macros for Qt-style plugins. Requires at least Qt 5.15. Since 6.18.

`JSON_NONE` lists the names of C++ preprocessor macros for Qt-style plugins which do not refer to external files with the plugin metadata. Use `MACRO_NAMES` instead for Qt >= 5.15.

`JSON_ARG1` lists the names of C++ preprocessor macros for Qt-style plugins where the first argument to the macro is the name of the external file with the plugin metadata. Use `MACRO_NAMES` instead for Qt >= 5.15.

`JSON_ARG2` is the same as `JSON_ARG1` but with the file name being the second argument. Use `MACRO_NAMES` instead for Qt >= 5.15.

`JSON_ARG3` is the same as `JSON_ARG1` but with the file name being the third argument. Use `MACRO_NAMES` instead for Qt >= 5.15.

`CONFIG_CODE_VARIABLE` specifies the name of the variable which will get set as value some generated CMake code for instructing automoc for the given macro names, as useful in an installed CMake config file. The variable can then be used as usual in the template file for such a CMake config file, by `@<variable_name>@`.

Example usage:

Given some plugin-oriented Qt-based software which defines a custom C++ preprocessor macro `EXPORT_MYPLUGIN` for declaring the central plugin object:

    #define EXPORT_MYPLUGIN_WITH_JSON(classname, jsonFile) \
    class classname : public QObject \
    { \
        Q_OBJECT \
        Q_PLUGIN_METADATA(IID "myplugin" FILE jsonFile) \
        explicit classname() {} \
    };

In the CMake buildsystem of the library one calls

    ecm_setup_qtplugin_macro_names(
        MACRO_NAMES
           EXPORT_MYPLUGIN_WITH_JSON
    )

to instruct automoc about the usage of that macro in the sources of the library itself.

Given the software installs a library including the header with the macro definition and a CMake config file, so 3rd-party can create additional plugins by linking against the library, one passes additionally the name of a variable which shall be set as value the CMake code needed to instruct automoc about the usage of that macro.

    ecm_setup_qtplugin_macro_names(
        MACRO_NAMES
           EXPORT_MYPLUGIN_WITH_JSON
        CONFIG_CODE_VARIABLE
           PACKAGE_SETUP_AUTOMOC_VARIABLES
    )

This variable then is used in the template file (e.g. `MyProjectConfig.cmake.in`) for the libary’s installed CMake config file and that way will ensure that in the 3rd-party plugin’s buildsystem automoc is instructed as well as needed:

    @PACKAGE_SETUP_AUTOMOC_VARIABLES@

Since 5.45.0.