diff options
Diffstat (limited to 'modules/ECMSetupQtPluginMacroNames.cmake')
| -rw-r--r-- | modules/ECMSetupQtPluginMacroNames.cmake | 190 |
1 files changed, 95 insertions, 95 deletions
diff --git a/modules/ECMSetupQtPluginMacroNames.cmake b/modules/ECMSetupQtPluginMacroNames.cmake index e4a03ba5..632149ca 100644 --- a/modules/ECMSetupQtPluginMacroNames.cmake +++ b/modules/ECMSetupQtPluginMacroNames.cmake @@ -1,102 +1,102 @@ -#.rst: -# ECMSetupQtPluginMacroNames -# -------------------------- -# -# Instruct CMake's automoc about C++ preprocessor macros used to define Qt-style plugins. -# -# :: -# -# ecm_setup_qtplugin_macro_names( -# [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 variables ``CMAKE_AUTOMOC_DEPEND_FILTERS`` (CMake >= 3.9.0) -# and ``CMAKE_AUTOMOC_MACRO_NAMES`` (CMake >= 3.10) to allow the developer to assist automoc. -# -# This macro cares for the explicit setup needed for those variables for common cases of -# C++ preprocessor macros used for Qt-style plugins. -# -# JSON_NONE lists the names of C++ preprocessor macros for Qt-style plugins which do not refer to -# external files with the plugin metadata. -# -# 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. -# -# JSON_ARG2 is the same as JSON_ARG1 but with the file name being the second argument. -# -# JSON_ARG3 is the same as JSON_ARG1 but with the file name being the third argument. -# -# 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: -# -# .. code-block:: c++ -# -# #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 -# -# .. code-block:: cmake -# -# ecm_setup_qtplugin_macro_names( -# JSON_ARG2 -# 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. -# -# .. code-block:: cmake -# -# ecm_setup_qtplugin_macro_names( -# JSON_ARG2 -# 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. - -#============================================================================= # SPDX-FileCopyrightText: 2018 Friedrich W. H. Kossebau <kossebau@kde.org> # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +ECMSetupQtPluginMacroNames +-------------------------- + +Instruct CMake's automoc about C++ preprocessor macros used to define Qt-style plugins. + +:: + + ecm_setup_qtplugin_macro_names( + [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 variables ``CMAKE_AUTOMOC_DEPEND_FILTERS`` (CMake >= 3.9.0) +and ``CMAKE_AUTOMOC_MACRO_NAMES`` (CMake >= 3.10) to allow the developer to assist automoc. + +This macro cares for the explicit setup needed for those variables for common cases of +C++ preprocessor macros used for Qt-style plugins. + +``JSON_NONE`` lists the names of C++ preprocessor macros for Qt-style plugins which do not refer to +external files with the plugin metadata. + +``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. + +``JSON_ARG2`` is the same as ``JSON_ARG1`` but with the file name being the second argument. + +``JSON_ARG3`` is the same as ``JSON_ARG1`` but with the file name being the third argument. + +``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: + +.. code-block:: c++ + + #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 + +.. code-block:: cmake + + ecm_setup_qtplugin_macro_names( + JSON_ARG2 + 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. + +.. code-block:: cmake + + ecm_setup_qtplugin_macro_names( + JSON_ARG2 + 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. +#]=======================================================================] + include(CMakePackageConfigHelpers) macro(ecm_setup_qtplugin_macro_names) |