Hi,

First things first: Users of Qt are unaffected by most of this. They get a nicer macro to define static logging categories, but everything else stays the same for them.

Logging categories have been a source of some frustration in Qt itself because they tend to create symbols that don't start with 'q' or 'Q' and that like to clash with each other and user symbols, especially in static builds. On top of this, logging categories are often not declared in a header, but rather multiple times in all implementation files that use them. This makes it unnecessarily hard to spot and fix the problem.

Since https://codereview.qt-project.org/c/qt/qtbase/+/417028 we've had a macro that declares an exported logging category. If you feel the need to export a logging category, you should:
1. Think twice. This is probably a bad idea.
2. If it's in Qt library code, use QT_DECLARE_EXPORTED_QT_LOGGING_CATEGORY, see below. 3. Otherwise, Q_DECLARE_EXPORTED_LOGGING_CATEGORY is better style, but nothing actually changes for you. Do not just prepend the export macro to Q_DECLARE_LOGGING_CATEGORY in Qt code since that relies on implementation details of Q_DECLARE_LOGGING_CATEGORY which are soon going to change.

Since https://codereview.qt-project.org/c/qt/qtbase/+/565342 you can define a logging category as static, and thereby prevent its name from escaping the compilation unit it's defined it. You should use the new Q_STATIC_LOGGING_CATEGORY macro wherever you can. Do not just prepend 'static' to Q_LOGGING_CATEGORY since that relies on implementation details of Q_LOGGING_CATEGORY which are soon going to change for logging categories in Qt itself.

Since https://codereview.qt-project.org/c/qt/qtbase/+/566456 you can declare a logging category as exported from a Qt library with a specific export macro. This is different from Q_DECLARE_EXPORTED_LOGGING_CATEGORY because logging categories defined in Qt itself will soon be different from logging categories defined in user (or plugin or tool) code. Whenever you feel the need to export one of the logging categories in Qt itself, you should:
1. Think twice. This is probably a bad idea
2. If you are sure, use QT_DECLARE_EXPORTED_QT_LOGGING_CATEGORY

Once https://codereview.qt-project.org/c/qt/qtbase/+/235873 is in, Qt's own non-static logging categories will live in the namespace QtPrivateLogging, resolving the issue of the missing 'q' prefix and avoiding name clashes with user code. The old name is retained via a "using" declaration, so you don't have to change any code that uses logging categories.

Once https://codereview.qt-project.org/c/qt/qtbase/+/567907 is in, non-static logging categories that haven't been forward declared will generate a deprecation warning. This way you are gently encouraged to either:
1. Make the logging category static to hide it from the symbol table.
2. Declare the logging category exactly once, in a header you include wherever you need it. This makes it obvious that there is an extra symbol generated from your logging category.

best regards,
Ulf
--
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Reply via email to