[Development] Fixing Qt-internal logging categories

[Ulf Hermann]

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