Warning, /frameworks/extra-cmake-modules/modules/ECMQtDeclareLoggingCategory.cmake is written in an unsupported language. File is not indexed.
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()