extra-cmake-modules/modules/ECMQtDeclareLoggingCategory.cmake

0001 # SPDX-FileCopyrightText: 2015 Alex Merry <alex.merry@kde.org>
0002 # SPDX-FileCopyrightText: 2020 Friedrich W. H. Kossebau <kossebau@kde.org>
0003 #
0004 # SPDX-License-Identifier: BSD-3-Clause
0005
0006 #[=======================================================================[.rst:
0007 ECMQtDeclareLoggingCategory
0008 ---------------------------
0009
0010 This module provides the ``ecm_qt_declare_logging_category`` function for
0011 generating declarations for logging categories in Qt5, and the
0012 ``ecm_qt_install_logging_categories`` function for generating and installing
0013 a file in KDebugSettings format with the info about all those categories,
0014 as well as a file with info about any renamed categories if defined.
0015 To include in that file any logging categories that are manually defined
0016 also a function ``ecm_qt_export_logging_category`` is provided.
0017
0018 ::
0019
0020   ecm_qt_declare_logging_category(<sources_var_name(|target (since 5.80))>
0021       HEADER <filename>
0022       IDENTIFIER <identifier>
0023       CATEGORY_NAME <category_name>
0024       [OLD_CATEGORY_NAMES <oldest_cat_name> [<second_oldest_cat_name> [...]]]
0025       [DEFAULT_SEVERITY <Debug|Info|Warning|Critical|Fatal>]
0026       [EXPORT <exportid>]
0027       [DESCRIPTION <description>]
0028   )
0029
0030 A header file, ``<filename>``, will be generated along with a corresponding
0031 source file. These will provide a QLoggingCategory category that can be referred
0032 to from C++ code using ``<identifier>``, and from the logging configuration using
0033 ``<category_name>``.
0034
0035 The generated source file will be added to the variable with the name
0036 ``<sources_var_name>``. If the given argument is a target though, instead both the
0037 generated header file and the generated source file will be added to the target as
0038 private sources (since 5.80). The target must not be an alias.
0039
0040 If ``<filename>`` is not absolute, it will be taken relative to the current
0041 binary directory.
0042
0043 ``<identifier>`` may include namespaces (eg: ``foo::bar::IDENT``).
0044
0045 If ``EXPORT`` is passed, the category will be registered for the group id
0046 ``<exportid>``. Info about the categories of that group can then be
0047 generated in a file and installed by that group id with the
0048 ``ecm_qt_install_logging_categories`` function. In that case also ``DESCRIPTION``
0049 will need to be passed, with ``<description>`` being a short single line text.
0050 And ``OLD_CATEGORY_NAMES`` can be used to inform about any renamings of the category,
0051 so user settings can be migrated. Since 5.68.0.
0052
0053 Since 5.14.0.
0054
0055 ::
0056
0057   ecm_qt_export_logging_category(
0058       IDENTIFIER <identifier>
0059       CATEGORY_NAME <category_name>
0060       [OLD_CATEGORY_NAMES <oldest_category_name> [<second_oldest_category_name> [...]]]
0061       EXPORT <exportid>
0062       DESCRIPTION <description>
0063       [DEFAULT_SEVERITY <Debug|Info|Warning|Critical|Fatal>]
0064   )
0065
0066 Registers a logging category for being included in the generated and
0067 installed KDebugSettings files. To be used for categories who are declared by
0068 manual code or other ways instead of code generated with
0069 ``ecm_qt_declare_logging_category``.
0070
0071 ``<identifier>`` may include namespaces (eg: ``foo::bar::IDENT``).
0072
0073 ``EXPORT`` specifies the group id with which the category will be registered.
0074 Info about the categories of that group can then be generated in a file and
0075 installed by that group id with the ``ecm_qt_install_logging_categories`` function.
0076
0077 ``DESCRIPTION`` specifies a short single line text describing the category.
0078
0079 ``OLD_CATEGORY_NAMES`` can be used to inform about any renamings of the category,
0080 so user settings can be migrated.
0081
0082 Since 5.68.0.
0083
0084 ::
0085
0086   ecm_qt_install_logging_categories(
0087       EXPORT <exportid>
0088       [FILE <filename>]
0089       DESTINATION <install_path>
0090       [SORT]
0091       [COMPONENT <component>]
0092   )
0093
0094 Generates and installs a file in KDebugSettings format with the info about all
0095 the categories registered for the group ``<exportid>``, as well as a file with
0096 info about any renamed categories, if there are.
0097
0098 The method call needs to be after the last ``ecm_qt_declare_logging_category``
0099 call which uses the same ``<exportid>``. This can be in the same directory, or
0100 any subdirectory or parent directory.
0101
0102 ``EXPORT`` specifies the group id of categories whose information should be
0103 stored in the file generated and installed.
0104
0105 ``FILE`` specifies the name of the file generated and installed. It will default
0106 to lower-cased ``<exportid>.categories``. The name of the file with info about
0107 renamed categories will use the same final base name and the suffix
0108 ``.renamecategories``. Note: Before 5.113, the base name should not have any
0109 further ``.`` in the name, as its end would be defined by that.
0110
0111 ``DESTINATION`` specifies where the generated file will be
0112 installed.
0113
0114 IF ``SORT`` is set, entries will be sorted by identifiers.
0115
0116 ``COMPONENT`` specifies the installation component name with which the install
0117 rules for the generated file are associated.
0118
0119 Since 5.85.0 this is a no-op when building for Android, as KDebugSettings is
0120 not available on that platform and the logging category files therefore just
0121 bloat the APK.
0122
0123 Example usage:
0124
0125 .. code-block:: cmake
0126
0127   ecm_qt_declare_logging_category(
0128       MYPROJECT_SRCS
0129       HEADER "myproject_debug.h"
0130       IDENTIFIER "MYPROJECT_DEBUG"
0131       CATEGORY_NAME "myproject"
0132       OLD_CATEGORY_NAMES "myprojectlog"
0133       DESCRIPTION "My project"
0134       EXPORT MyProject
0135   )
0136
0137   ecm_qt_export_logging_category(
0138       IDENTIFIER "MYPROJECT_SUBMODULE_DEBUG"
0139       CATEGORY_NAME "myproject.submodule"
0140       DESCRIPTION "My project - submodule"
0141       EXPORT MyProject
0142   )
0143
0144   ecm_qt_install_logging_categories(
0145       EXPORT MyProject
0146       FILE myproject.categories
0147       DESTINATION "${KDE_INSTALL_LOGGINGCATEGORIESDIR}"
0148   )
0149
0150 Since 5.68.0.
0151 #]=======================================================================]
0152
0153 set(_ECM_QT_DECLARE_LOGGING_CATEGORY_TEMPLATE_CPP "${CMAKE_CURRENT_LIST_DIR}/ECMQtDeclareLoggingCategory.cpp.in")
0154 set(_ECM_QT_DECLARE_LOGGING_CATEGORY_TEMPLATE_H   "${CMAKE_CURRENT_LIST_DIR}/ECMQtDeclareLoggingCategory.h.in")
0155
0156 function(ecm_qt_export_logging_category)
0157     set(options)
0158     set(oneValueArgs IDENTIFIER CATEGORY_NAME DEFAULT_SEVERITY EXPORT DESCRIPTION)
0159     set(multiValueArgs OLD_CATEGORY_NAMES)
0160     cmake_parse_arguments(ARG "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
0161
0162     if(ARG_UNPARSED_ARGUMENTS)
0163         message(FATAL_ERROR "Unexpected arguments to ecm_qt_export_logging_category: ${ARG_UNPARSED_ARGUMENTS}")
0164     endif()
0165     if(NOT ARG_IDENTIFIER)
0166         message(FATAL_ERROR "Missing IDENTIFIER argument for ecm_qt_export_logging_category")
0167     endif()
0168     if(NOT ARG_CATEGORY_NAME)
0169         message(FATAL_ERROR "Missing CATEGORY_NAME argument for ecm_qt_export_logging_category")
0170     endif()
0171     if(NOT ARG_DEFAULT_SEVERITY)
0172         set(ARG_DEFAULT_SEVERITY Info)
0173         set(is_explicite_default_severity FALSE)
0174     else()
0175         set(acceptible_severities Debug Info Warning Critical Fatal)
0176         list(FIND acceptible_severities "${ARG_DEFAULT_SEVERITY}" pos)
0177         if (pos EQUAL -1)
0178             message(FATAL_ERROR "Unknown DEFAULT_SEVERITY ${pos}")
0179         endif()
0180         set(is_explicite_default_severity TRUE)
0181     endif()
0182     if(NOT ARG_EXPORT)
0183         message(FATAL_ERROR "Missing EXPORT argument for ecm_qt_export_logging_category.")
0184     endif()
0185     if(NOT ARG_DESCRIPTION)
0186         message(FATAL_ERROR "Missing DESCRIPTION argument for ecm_qt_export_logging_category.")
0187     endif()
0188
0189     # note data in global properties
0190     set(_propertyprefix "ECM_QT_LOGGING_CATEGORY_${ARG_EXPORT}")
0191     set_property(GLOBAL APPEND PROPERTY "${_propertyprefix}_CATEGORIES" ${ARG_CATEGORY_NAME})
0192     set_property(GLOBAL PROPERTY "${_propertyprefix}_IDENTIFIER_${ARG_CATEGORY_NAME}" "${ARG_IDENTIFIER}")
0193     set_property(GLOBAL PROPERTY "${_propertyprefix}_DESCRIPTION_${ARG_CATEGORY_NAME}" "${ARG_DESCRIPTION}")
0194     set_property(GLOBAL PROPERTY "${_propertyprefix}_OLD_NAMES_${ARG_CATEGORY_NAME}" "${ARG_OLD_CATEGORY_NAMES}")
0195     if (is_explicite_default_severity)
0196         set_property(GLOBAL PROPERTY "${_propertyprefix}_DEFAULT_SEVERITY_${ARG_CATEGORY_NAME}" "${ARG_DEFAULT_SEVERITY}")
0197     endif()
0198 endfunction()
0199
0200
0201 function(ecm_qt_declare_logging_category sources_var)
0202     set(options)
0203     set(oneValueArgs HEADER IDENTIFIER CATEGORY_NAME DEFAULT_SEVERITY EXPORT DESCRIPTION)
0204     set(multiValueArgs OLD_CATEGORY_NAMES)
0205     cmake_parse_arguments(ARG "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
0206
0207     if(ARG_UNPARSED_ARGUMENTS)
0208         message(FATAL_ERROR "Unexpected arguments to ecm_qt_declare_logging_category: ${ARG_UNPARSED_ARGUMENTS}")
0209     endif()
0210     if(NOT ARG_HEADER)
0211         message(FATAL_ERROR "Missing HEADER argument for ecm_qt_declare_logging_category")
0212     endif()
0213     if(NOT ARG_IDENTIFIER)
0214         message(FATAL_ERROR "Missing IDENTIFIER argument for ecm_qt_declare_logging_category")
0215     endif()
0216     if(NOT ARG_CATEGORY_NAME)
0217         message(FATAL_ERROR "Missing CATEGORY_NAME argument for ecm_qt_declare_logging_category")
0218     endif()
0219     if(NOT ARG_DEFAULT_SEVERITY)
0220         set(ARG_DEFAULT_SEVERITY Info)
0221         set(is_explicite_default_severity FALSE)
0222     else()
0223         set(acceptible_severities Debug Info Warning Critical Fatal)
0224         list(FIND acceptible_severities "${ARG_DEFAULT_SEVERITY}" pos)
0225         if (pos EQUAL -1)
0226             message(FATAL_ERROR "Unknown DEFAULT_SEVERITY ${pos}")
0227         endif()
0228         set(is_explicite_default_severity TRUE)
0229     endif()
0230     if(ARG_EXPORT AND NOT ARG_DESCRIPTION)
0231         message(FATAL_ERROR "Missing DESCRIPTION argument for ecm_qt_declare_logging_category.")
0232     endif()
0233     if (TARGET ${sources_var})
0234         get_target_property(aliased_target ${sources_var} ALIASED_TARGET)
0235         if(aliased_target)
0236             message(FATAL_ERROR "Target argument passed to ecm_qt_declare_logging_category must not be an alias: ${sources_var}")
0237         endif()
0238     endif()
0239
0240     if (NOT IS_ABSOLUTE "${ARG_HEADER}")
0241         set(ARG_HEADER "${CMAKE_CURRENT_BINARY_DIR}/${ARG_HEADER}")
0242     endif()
0243
0244     string(REPLACE "::" ";" namespaces "${ARG_IDENTIFIER}")
0245     list(LENGTH namespaces len)
0246     math(EXPR last_pos "${len} - 1")
0247     list(GET namespaces ${last_pos} IDENTIFIER)
0248     list(REMOVE_AT namespaces ${last_pos})
0249
0250     set(OPEN_NAMESPACES)
0251     set(CLOSE_NAMESPACES)
0252     foreach(ns ${namespaces})
0253         set(OPEN_NAMESPACES "${OPEN_NAMESPACES} namespace ${ns} {")
0254         set(CLOSE_NAMESPACES "} ${CLOSE_NAMESPACES}")
0255     endforeach()
0256
0257     string(FIND "${ARG_HEADER}" "." pos REVERSE)
0258     if (pos EQUAL -1)
0259         set(cpp_filename "${ARG_HEADER}.cpp")
0260     else()
0261         string(SUBSTRING "${ARG_HEADER}" 0 ${pos} cpp_filename)
0262         set(cpp_filename "${cpp_filename}.cpp")
0263     endif()
0264
0265     get_filename_component(HEADER_NAME "${ARG_HEADER}" NAME)
0266
0267     string(REGEX REPLACE "[^a-zA-Z0-9]" "_" GUARD_NAME "${HEADER_NAME}")
0268     string(REPLACE "::" "_" GUARD_PREFIX "ECM_QLOGGINGCATEGORY_${ARG_IDENTIFIER}")
0269     string(TOUPPER "${GUARD_PREFIX}_${GUARD_NAME}" GUARD_NAME)
0270
0271     if (NOT _ECM_QT_DECLARE_LOGGING_CATEGORY_TEMPLATE_CPP)
0272        message(FATAL_ERROR "You must include(ECMQtDeclareLoggingCategory) before using ecm_qt_declare_logging_category")
0273     endif()
0274
0275     configure_file("${_ECM_QT_DECLARE_LOGGING_CATEGORY_TEMPLATE_CPP}" "${cpp_filename}")
0276     configure_file("${_ECM_QT_DECLARE_LOGGING_CATEGORY_TEMPLATE_H}" "${ARG_HEADER}")
0277
0278     if(TARGET ${sources_var})
0279         target_sources(${sources_var} PRIVATE ${cpp_filename} "${ARG_HEADER}")
0280     else()
0281         set(sources "${${sources_var}}")
0282         list(APPEND sources "${cpp_filename}")
0283         set(${sources_var} "${sources}" PARENT_SCOPE)
0284     endif()
0285
0286     # note data in global properties
0287     if (ARG_EXPORT)
0288         set(_default_severity)
0289         if (is_explicite_default_severity)
0290             set(_default_severity DEFAULT_SEVERITY ${ARG_DEFAULT_SEVERITY})
0291         endif()
0292         set(_old_category_name)
0293         if (ARG_OLD_CATEGORY_NAMES)
0294             set(_old_category_names OLD_CATEGORY_NAMES ${ARG_OLD_CATEGORY_NAMES})
0295         endif()
0296         ecm_qt_export_logging_category(
0297             IDENTIFIER ${ARG_IDENTIFIER}
0298             CATEGORY_NAME ${ARG_CATEGORY_NAME}
0299             ${_old_category_names}
0300             ${_default_severity}
0301             EXPORT ${ARG_EXPORT}
0302             DESCRIPTION "${ARG_DESCRIPTION}"
0303         )
0304     endif()
0305 endfunction()
0306
0307
0308 function(ecm_qt_install_logging_categories)
0309     # on Android there is no KDebugSettings, and thus the logging categories files make no sense in APKs
0310     if (ANDROID)
0311         return()
0312     endif()
0313
0314     set(options SORT)
0315     set(oneValueArgs FILE EXPORT DESTINATION COMPONENT)
0316     set(multiValueArgs)
0317
0318     cmake_parse_arguments(ARGS "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
0319
0320     if(NOT ARGS_EXPORT)
0321         message(FATAL_ERROR "Missing EXPORT argument for ecm_qt_install_logging_categories")
0322     endif()
0323
0324     if(NOT ARGS_DESTINATION)
0325         message(FATAL_ERROR "Missing DESTINATION argument for ecm_qt_install_logging_categories")
0326     endif()
0327
0328     if(NOT ARGS_FILE)
0329         string(TOLOWER "${ARGS_EXPORT}.categories" ARGS_FILE)
0330     endif()
0331
0332     set(_propertyprefix "ECM_QT_LOGGING_CATEGORY_${ARGS_EXPORT}")
0333     get_property(has_category GLOBAL PROPERTY "${_propertyprefix}_CATEGORIES" SET)
0334
0335     if (NOT has_category)
0336         message(AUTHOR_WARNING "No Qt logging categories exported for \"${ARGS_EXPORT}\", generating & installing an empty file.")
0337     endif()
0338
0339     get_property(_categories GLOBAL PROPERTY "${_propertyprefix}_CATEGORIES")
0340     if (ARGS_SORT)
0341         list(SORT _categories)
0342     endif()
0343
0344     set(_renamed_categories)
0345
0346     # generate categories file
0347     if (NOT IS_ABSOLUTE "${ARGS_FILE}")
0348         set(ARGS_FILE "${CMAKE_CURRENT_BINARY_DIR}/${ARGS_FILE}")
0349     endif()
0350
0351     set(_categories_content
0352 "# KDebugSettings data file
0353 # This file was generated by ecm_qt_install_logging_categories(). DO NOT EDIT!
0354
0355 ")
0356
0357     foreach(_category IN LISTS _categories)
0358         get_property(_description GLOBAL PROPERTY "${_propertyprefix}_DESCRIPTION_${_category}")
0359         get_property(_identifier GLOBAL PROPERTY "${_propertyprefix}_IDENTIFIER_${_category}")
0360         get_property(_default_severity GLOBAL PROPERTY "${_propertyprefix}_DEFAULT_SEVERITY_${_category}")
0361         if (_default_severity)
0362             string(TOUPPER "${_default_severity}" _default_severity)
0363             set(_default_severity "DEFAULT_SEVERITY [${_default_severity}] ") # final space wanted
0364         endif()
0365         get_property(_old_category_names GLOBAL PROPERTY "${_propertyprefix}_OLD_NAMES_${_category}")
0366         if (_old_category_names)
0367             list(APPEND _renamed_categories ${_category})
0368         endif()
0369
0370         # Format:
0371         # logname<space>description(optional <space> DEFAULT_SEVERITY [DEFAULT_CATEGORY] as WARNING/DEBUG/INFO/CRITICAL) optional IDENTIFIER [...])
0372         string(APPEND _categories_content "${_category} ${_description} ${_default_severity}IDENTIFIER [${_identifier}]\n")
0373     endforeach()
0374
0375     file(GENERATE
0376         OUTPUT ${ARGS_FILE}
0377         CONTENT ${_categories_content}
0378     )
0379
0380     set(_renamed_cats_file)
0381     if (_renamed_categories)
0382         get_filename_component(_dir ${ARGS_FILE} DIRECTORY)
0383         get_filename_component(_base_name ${ARGS_FILE} NAME_WLE)
0384         set(_renamed_cats_file "${_dir}/${_base_name}.renamecategories")
0385         set(_renamed_cats_content
0386 "# KDebugSettings data file
0387 # This file was generated by ecm_qt_install_logging_categories(). DO NOT EDIT!
0388
0389 ")
0390
0391         foreach(_category IN LISTS _renamed_categories)
0392             get_property(_category_name_history GLOBAL PROPERTY "${_propertyprefix}_OLD_NAMES_${_category}")
0393
0394             list(APPEND _category_name_history ${_category})
0395             list(GET _category_name_history 0 _old_category_name)
0396             list(REMOVE_AT _category_name_history 0)
0397             foreach(_category_name IN LISTS _category_name_history)
0398                 # Format:
0399                 # oldlogname<space>newlogname
0400                 string(APPEND _renamed_cats_content "${_old_category_name} ${_category_name}\n")
0401                 set(_old_category_name ${_category_name})
0402             endforeach()
0403         endforeach()
0404
0405         file(GENERATE
0406             OUTPUT ${_renamed_cats_file}
0407             CONTENT ${_renamed_cats_content}
0408         )
0409     endif()
0410
0411     # install files
0412     set(_component_install)
0413     if (ARGS_COMPONENT)
0414         set(_component_install COMPONENT ${ARGS_COMPONENT})
0415     endif()
0416     install(
0417         FILES ${ARGS_FILE} ${_renamed_cats_file}
0418         DESTINATION "${ARGS_DESTINATION}"
0419         ${_component_install}
0420     )
0421 endfunction()