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
