# ECMQtDeclareLoggingCategory

This module provides the `ecm_qt_declare_logging_category` function for generating declarations for logging categories in Qt5, and the `ecm_qt_install_logging_categories` function for generating and installing a file in KDebugSettings format with the info about all those categories, as well as a file with info about any renamed categories if defined. To include in that file any logging categories that are manually defined also a function `ecm_qt_export_logging_category` is provided.

    ecm_qt_declare_logging_category(<sources_var_name(|target (since 5.80))>
        HEADER <filename>
        IDENTIFIER <identifier>
        CATEGORY_NAME <category_name>
        [OLD_CATEGORY_NAMES <oldest_cat_name> [<second_oldest_cat_name> [...]]]
        [DEFAULT_SEVERITY <Debug|Info|Warning|Critical|Fatal>]
        [EXPORT <exportid>]
        [DESCRIPTION <description>]
    )

A header file, `<filename>`, will be generated along with a corresponding source file. These will provide a QLoggingCategory category that can be referred to from C++ code using `<identifier>`, and from the logging configuration using `<category_name>`.

The generated source file will be added to the variable with the name `<sources_var_name>`. If the given argument is a target though, instead both the generated header file and the generated source file will be added to the target as private sources (since 5.80). The target must not be an alias.

If `<filename>` is not absolute, it will be taken relative to the current binary directory.

`<identifier>` may include namespaces (eg: `foo::bar::IDENT`).

If `EXPORT` is passed, the category will be registered for the group id `<exportid>`. Info about the categories of that group can then be generated in a file and installed by that group id with the `ecm_qt_install_logging_categories` function. In that case also `DESCRIPTION` will need to be passed, with `<description>` being a short single line text. And `OLD_CATEGORY_NAMES` can be used to inform about any renamings of the category, so user settings can be migrated. Since 5.68.0.

Since 5.14.0.

    ecm_qt_export_logging_category(
        IDENTIFIER <identifier>
        CATEGORY_NAME <category_name>
        [OLD_CATEGORY_NAMES <oldest_category_name> [<second_oldest_category_name> [...]]]
        EXPORT <exportid>
        DESCRIPTION <description>
        [DEFAULT_SEVERITY <Debug|Info|Warning|Critical|Fatal>]
    )

Registers a logging category for being included in the generated and installed KDebugSettings files. To be used for categories who are declared by manual code or other ways instead of code generated with `ecm_qt_declare_logging_category`.

`<identifier>` may include namespaces (eg: `foo::bar::IDENT`).

`EXPORT` specifies the group id with which the category will be registered. Info about the categories of that group can then be generated in a file and installed by that group id with the `ecm_qt_install_logging_categories` function.

`DESCRIPTION` specifies a short single line text describing the category.

`OLD_CATEGORY_NAMES` can be used to inform about any renamings of the category, so user settings can be migrated.

Since 5.68.0.

    ecm_qt_install_logging_categories(
        EXPORT <exportid>
        [FILE <filename>]
        DESTINATION <install_path>
        [SORT]
        [COMPONENT <component>]
    )

Generates and installs a file in KDebugSettings format with the info about all the categories registered for the group `<exportid>`, as well as a file with info about any renamed categories, if there are.

The method call needs to be after the last `ecm_qt_declare_logging_category` call which uses the same `<exportid>`. This can be in the same directory, or any subdirectory or parent directory.

`EXPORT` specifies the group id of categories whose information should be stored in the file generated and installed.

`FILE` specifies the name of the file generated and installed. It will default to lower-cased `<exportid>.categories`. The name of the file with info about renamed categories will use the same final base name and the suffix `.renamecategories`. Note: Before 5.113, the base name should not have any further `.` in the name, as its end would be defined by that.

`DESTINATION` specifies where the generated file will be installed.

IF `SORT` is set, entries will be sorted by identifiers.

`COMPONENT` specifies the installation component name with which the install rules for the generated file are associated.

Since 5.85.0 this is a no-op when building for Android, as KDebugSettings is not available on that platform and the logging category files therefore just bloat the APK.

Example usage:

    ecm_qt_declare_logging_category(
        MYPROJECT_SRCS
        HEADER "myproject_debug.h"
        IDENTIFIER "MYPROJECT_DEBUG"
        CATEGORY_NAME "myproject"
        OLD_CATEGORY_NAMES "myprojectlog"
        DESCRIPTION "My project"
        EXPORT MyProject
    )

    ecm_qt_export_logging_category(
        IDENTIFIER "MYPROJECT_SUBMODULE_DEBUG"
        CATEGORY_NAME "myproject.submodule"
        DESCRIPTION "My project - submodule"
        EXPORT MyProject
    )

    ecm_qt_install_logging_categories(
        EXPORT MyProject
        FILE myproject.categories
        DESTINATION "${KDE_INSTALL_LOGGINGCATEGORIESDIR}"
    )

Since 5.68.0.