Add a way to declare _exported_ logging categories

If a library declares a logging category that needs to be used
by clients (e.g. via inline methods, macros, etc.), then the
logging category function generated by Q_DECLARE_LOGGING_CATEGORY
has to be exported.

We've seen this problem with Q_NAMESPACE, Q_GADGET, etc.: these
macros also declare functions or objects that in some cases need to
be exported.

And precisely like Q_NAMESPACE, Q_GADGET, etc., people end up
relying on the implementation details of Q_DECLARE_LOGGING_CATEGORY
(specifically, what does it expand to) in order to place the
export directives in the right place.

Introduce a more robust solution and apply it around qtbase.
Cleanup some minor code as a drive-by (remove `extern` and useless
semicolons).

[ChangeLog][QtCore][QLoggingCategory] Added the
Q_DECLARE_EXPORTED_LOGGING_CATEGORY macro, in order to allow dynamic
libraries to declare a logging category that can be then used by
client code.

Change-Id: I18f40cc937cfe8277b8d62ebc824c27a0773de04
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
Reviewed-by: Kai Koehne <kai.koehne@qt.io>

8 files changed, 39 insertions, 10 deletions

diff --git a/src/corelib/global/qnativeinterface_p.h b/src/corelib/global/qnativeinterface_p.h
index 0deae3cb29..aa7705e153 100644
--- a/src/corelib/global/qnativeinterface_p.h
+++ b/src/corelib/global/qnativeinterface_p.h
@@ -21,7 +21,7 @@
 QT_BEGIN_NAMESPACE
 
 namespace QtPrivate {
-Q_CORE_EXPORT Q_DECLARE_LOGGING_CATEGORY(lcNativeInterface)
+Q_DECLARE_EXPORTED_LOGGING_CATEGORY(lcNativeInterface, Q_CORE_EXPORT)
 }
 
 // Provides a definition for the interface destructor
diff --git a/src/corelib/io/qloggingcategory.cpp b/src/corelib/io/qloggingcategory.cpp
index 08b7b2d584..201a50317b 100644
--- a/src/corelib/io/qloggingcategory.cpp
+++ b/src/corelib/io/qloggingcategory.cpp
@@ -51,6 +51,9 @@ static void setBoolLane(QBasicAtomicInt *atomic, bool enable, int shift)
 
     \snippet qloggingcategory/main.cpp 1
 
+    There is also the Q_DECLARE_EXPORTED_LOGGING_CATEGORY() macro in
+    order to use a logging category across library boundaries.
+
     Category names are free text; to configure categories using \l{Logging Rules}, their
     names should follow this convention:
     \list
@@ -574,7 +577,7 @@ void QLoggingCategory::setFilterRules(const QString &rules)
 */
 /*!
     \macro Q_DECLARE_LOGGING_CATEGORY(name)
-    \sa Q_LOGGING_CATEGORY()
+    \sa Q_LOGGING_CATEGORY(), Q_DECLARE_EXPORTED_LOGGING_CATEGORY()
     \relates QLoggingCategory
     \since 5.2
 
@@ -585,8 +588,31 @@ void QLoggingCategory::setFilterRules(const QString &rules)
 */
 
 /*!
+    \macro Q_DECLARE_EXPORTED_LOGGING_CATEGORY(name, EXPORT_MACRO)
+    \sa Q_LOGGING_CATEGORY(), Q_DECLARE_LOGGING_CATEGORY()
+    \relates QLoggingCategory
+    \since 6.5
+
+    Declares a logging category \a name. The macro can be used to declare
+    a common logging category shared in different parts of the program.
+
+    This works exactly like Q_DECLARE_LOGGING_CATEGORY(). However,
+    the logging category declared by this macro is additionally
+    qualified with \a EXPORT_MACRO. This is useful if the logging
+    category needs to be exported from a dynamic library.
+
+    For example:
+
+    \code
+    Q_DECLARE_EXPORTED_LOGGING_CATEGORY("lib.core", LIB_EXPORT_MACRO)
+    \endcode
+
+    This macro must be used outside of a class or function.
+*/
+
+/*!
     \macro Q_LOGGING_CATEGORY(name, string)
-    \sa Q_DECLARE_LOGGING_CATEGORY()
+    \sa Q_DECLARE_LOGGING_CATEGORY(), Q_DECLARE_EXPORTED_LOGGING_CATEGORY()
     \relates QLoggingCategory
     \since 5.2
 
diff --git a/src/corelib/io/qloggingcategory.h b/src/corelib/io/qloggingcategory.h
index 60773bd2a9..ae8425142a 100644
--- a/src/corelib/io/qloggingcategory.h
+++ b/src/corelib/io/qloggingcategory.h
@@ -118,8 +118,11 @@ template <> const bool QLoggingCategoryMacroHolder<QtWarningMsg>::IsOutputEnable
 #endif
 } // unnamed namespace
 
+#define Q_DECLARE_EXPORTED_LOGGING_CATEGORY(name, ...) \
+    __VA_ARGS__ const QLoggingCategory &name();
+
 #define Q_DECLARE_LOGGING_CATEGORY(name) \
-    extern const QLoggingCategory &name();
+    Q_DECLARE_EXPORTED_LOGGING_CATEGORY(name)
 
 #define Q_LOGGING_CATEGORY(name, ...) \
     const QLoggingCategory &name() \
diff --git a/src/corelib/kernel/qeventdispatcher_cf_p.h b/src/corelib/kernel/qeventdispatcher_cf_p.h
index ce2c36700e..c4c0d14027 100644
--- a/src/corelib/kernel/qeventdispatcher_cf_p.h
+++ b/src/corelib/kernel/qeventdispatcher_cf_p.h
@@ -63,8 +63,8 @@ Q_FORWARD_DECLARE_OBJC_CLASS(QT_MANGLE_NAMESPACE(RunLoopModeTracker));
 QT_BEGIN_NAMESPACE
 
 namespace QtPrivate {
-Q_CORE_EXPORT Q_DECLARE_LOGGING_CATEGORY(lcEventDispatcher);
-Q_CORE_EXPORT Q_DECLARE_LOGGING_CATEGORY(lcEventDispatcherTimers)
+Q_DECLARE_EXPORTED_LOGGING_CATEGORY(lcEventDispatcher, Q_CORE_EXPORT)
+Q_DECLARE_EXPORTED_LOGGING_CATEGORY(lcEventDispatcherTimers, Q_CORE_EXPORT)
 }
 
 class QEventDispatcherCoreFoundation;
diff --git a/src/gui/opengl/qopenglprogrambinarycache_p.h b/src/gui/opengl/qopenglprogrambinarycache_p.h
index 0553121a22..0237c81fc5 100644
--- a/src/gui/opengl/qopenglprogrambinarycache_p.h
+++ b/src/gui/opengl/qopenglprogrambinarycache_p.h
@@ -28,7 +28,7 @@ QT_BEGIN_NAMESPACE
 // therefore stay independent from QOpenGLShader(Program). Must rely only on
 // QOpenGLContext/Functions.
 
-Q_GUI_EXPORT Q_DECLARE_LOGGING_CATEGORY(lcOpenGLProgramDiskCache)
+Q_DECLARE_EXPORTED_LOGGING_CATEGORY(lcOpenGLProgramDiskCache, Q_GUI_EXPORT)
 
 class Q_GUI_EXPORT QOpenGLProgramBinaryCache
 {
diff --git a/src/gui/painting/qplatformbackingstore.h b/src/gui/painting/qplatformbackingstore.h
index a1bae50555..85bb0fe936 100644
--- a/src/gui/painting/qplatformbackingstore.h
+++ b/src/gui/painting/qplatformbackingstore.h
@@ -23,7 +23,7 @@
 
 QT_BEGIN_NAMESPACE
 
-Q_GUI_EXPORT Q_DECLARE_LOGGING_CATEGORY(lcQpaBackingStore)
+Q_DECLARE_EXPORTED_LOGGING_CATEGORY(lcQpaBackingStore, Q_GUI_EXPORT)
 
 class QRegion;
 class QRect;
diff --git a/src/plugins/platforms/eglfs/deviceintegration/eglfs_kms_support/qeglfskmsintegration_p.h b/src/plugins/platforms/eglfs/deviceintegration/eglfs_kms_support/qeglfskmsintegration_p.h
index 7000b9d35e..36e65a0bd4 100644
--- a/src/plugins/platforms/eglfs/deviceintegration/eglfs_kms_support/qeglfskmsintegration_p.h
+++ b/src/plugins/platforms/eglfs/deviceintegration/eglfs_kms_support/qeglfskmsintegration_p.h
@@ -27,7 +27,7 @@ QT_BEGIN_NAMESPACE
 class QKmsDevice;
 class QKmsScreenConfig;
 
-Q_EGLFS_EXPORT Q_DECLARE_LOGGING_CATEGORY(qLcEglfsKmsDebug)
+Q_DECLARE_EXPORTED_LOGGING_CATEGORY(qLcEglfsKmsDebug, Q_EGLFS_EXPORT)
 
 class Q_EGLFS_EXPORT QEglFSKmsIntegration : public QEglFSDeviceIntegration
 {
diff --git a/src/plugins/platforms/xcb/gl_integrations/qxcbglintegration.h b/src/plugins/platforms/xcb/gl_integrations/qxcbglintegration.h
index 6e841370d8..c6492f02ae 100644
--- a/src/plugins/platforms/xcb/gl_integrations/qxcbglintegration.h
+++ b/src/plugins/platforms/xcb/gl_integrations/qxcbglintegration.h
@@ -14,7 +14,7 @@ class QPlatformOffscreenSurface;
 class QOffscreenSurface;
 class QXcbNativeInterfaceHandler;
 
-Q_XCB_EXPORT Q_DECLARE_LOGGING_CATEGORY(lcQpaGl)
+Q_DECLARE_EXPORTED_LOGGING_CATEGORY(lcQpaGl, Q_XCB_EXPORT)
 
 class Q_XCB_EXPORT QXcbGlIntegration
 {