Allow configuration of logging rules from file system

Allow configuration of logging rules from outside of the application,
either through a configuration file (.config/QtProject/qtlogging.ini),
or through a file specified by a QT_LOGGING_CONF environment
variable.

The logging rules from the different sources are concatenated: First
the rules from QtProject/qtlogging.ini are applied, then
QLoggingCategory::setLoggingRules(), finally from the environment.
This allows an application to overwrite/augment the system wide rules,
and in turn that can be tailored for a specific run by setting a
configuration in the environment variable.

[ChangeLog][QtCore][Logging] The logging framework can now be configured
with an .ini file.

Change-Id: I442efde1b7e0a2ebe135c6f6e0a4b656483fe4b1
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>

1 files changed, 57 insertions, 16 deletions

diff --git a/src/corelib/io/qloggingcategory.cpp b/src/corelib/io/qloggingcategory.cpp
index 5fa346dce5..168087659f 100644
--- a/src/corelib/io/qloggingcategory.cpp
+++ b/src/corelib/io/qloggingcategory.cpp
@@ -86,12 +86,62 @@ Q_GLOBAL_STATIC_WITH_ARGS(QLoggingCategory, qtDefaultCategory,
     In the default configuration \l isWarningEnabled() , \l isDebugEnabled() and
     \l isCriticalEnabled() will return \c true.
 
-    \section1 Changing the configuration of a category
+    \section1 Configuring Categories
 
-    Use either \l setFilterRules() or \l installFilter() to
-    configure categories, for example
+    Categories can be centrally configured by either setting logging rules,
+    or by installing a custom filter.
 
-    \snippet qloggingcategory/main.cpp 2
+    \section2 Logging Rules
+
+    Logging rules allow to enable or disable logging for categories in a flexible
+    way. Rules are specified in text, where every line must have the format
+
+    \code
+    <category>[.<type>] = true|false
+    \endcode
+
+    \c <category> is the name of the category, potentially with \c{*} as a
+    wildcard symbol as the first or last character (or at both positions).
+    The optional \c <type> must be either \c debug, \c warning, or \c critical.
+    Lines that do not fit to his scheme are ignored.
+
+    Rules are evaluated in text order, from first to last. That is, if two rules
+    apply to a category/type, the rule that comes later is applied.
+
+    Rules can be set via \l setFilterRules(). Since Qt 5.3 logging rules
+    are also automatically loaded from the \c [rules] section of a logging
+    configuration file. Such configuration files are looked up in the QtProject
+    configuration directory, or explicitly set in a \c QT_LOGGING_CONF
+    environment variable.
+
+    Rules set by \l setFilterRules() take precedence over rules specified
+    in the QtProject configuration directory, and can, in turn, be
+    overwritten by rules from the configuration file specified by
+    \c QT_LOGGING_CONF.
+
+    Order of evaluation:
+    \list
+    \li Rules from QtProject/qlogging.ini
+    \li Rules set by \l setFilterRules()
+    \li Rules from file in \c QT_LOGGING_CONF
+    \endlist
+
+    The \c QtProject/qlogging.ini file is looked up in all directories returned
+    by QStandardPaths::GenericConfigLocation, e.g.
+
+    \list
+    \li on Mac OS X: \c ~/Library/Preferences
+    \li on Unix: \c ~/.config, \c /etc/xdg
+    \li on Windows: \c %LOCALAPPDATA%, \c %ProgramData%,
+        \l QCoreApplication::applicationDirPath(),
+        QCoreApplication::applicationDirPath() + \c "/data"
+    \endlist
+
+    \section2 Installing a Custom Filter
+
+    As a lower-level alternative to the text rules you can also implement a
+    custom filter via \l installFilter(). All filter rules are ignored in this
+    case.
 
     \section1 Printing the category
 
@@ -278,27 +328,18 @@ QLoggingCategory::installFilter(QLoggingCategory::CategoryFilter filter)
     Configures which categories and message types should be enabled through a
     a set of \a rules.
 
-    Each line in \a rules must have the format
-
-    \code
-    <category>[.<type>] = true|false
-    \endcode
-
-    where \c <category> is the name of the category, potentially with \c{*} as a
-    wildcard symbol at the start and/or the end. The optional \c <type> must
-    be either \c debug, \c warning, or \c critical.
-
     Example:
 
     \snippet qloggingcategory/main.cpp 2
 
     \note The rules might be ignored if a custom category filter is installed
-    with \l installFilter().
+    with \l installFilter(), or if the user defined a custom logging
+    configuration file in the \c QT_LOGGING_CONF environment variable.
 
 */
 void QLoggingCategory::setFilterRules(const QString &rules)
 {
-    QLoggingRegistry::instance()->rulesParser.setRules(rules);
+    QLoggingRegistry::instance()->setApiRules(rules);
 }
 
 /*!