Clarify limitations of QCoreApplication::libraryPaths()

If you call libraryPaths() before constructing a QCoreApplication,
intersting things may happen.

Task-number: QTBUG-38598
Change-Id: I2861746277e391ede9e921e4a8ad825007e25fa0
Reviewed-by: Topi Reiniö <topi.reinio@digia.com>

1 files changed, 16 insertions, 5 deletions

diff --git a/src/corelib/kernel/qcoreapplication.cpp b/src/corelib/kernel/qcoreapplication.cpp
index 0bde57c8b3..dbffa83cee 100644
--- a/src/corelib/kernel/qcoreapplication.cpp
+++ b/src/corelib/kernel/qcoreapplication.cpp
@@ -2420,16 +2420,27 @@ Q_GLOBAL_STATIC_WITH_ARGS(QMutex, libraryPathMutex, (QMutex::Recursive))
     Returns a list of paths that the application will search when
     dynamically loading libraries.
 
+    The return value of this function may change when a QCoreApplication
+    is created. It is not recommended to call it before creating a
+    QCoreApplication. The directory of the application executable (\b not
+    the working directory) is part of the list if it is known. In order
+    to make it known a QCoreApplication has to be constructed as it will
+    use \c {argv[0]} to find it.
+
     Qt provides default library paths, but they can also be set using
     a \l{Using qt.conf}{qt.conf} file. Paths specified in this file
-    will override default values.
+    will override default values. Note that if the qt.conf file is in
+    the directory of the application executable, it may not be found
+    until a QCoreApplication is created. If it is not found when calling
+    this function, the default library paths will be used.
 
-    This list will include the installation directory for plugins if
+    The list will include the installation directory for plugins if
     it exists (the default installation directory for plugins is \c
     INSTALL/plugins, where \c INSTALL is the directory where Qt was
-    installed).  The directory of the application executable (NOT the
-    working directory) is always added, as well as the colon separated
-    entries of the \c QT_PLUGIN_PATH environment variable.
+    installed). The colon separated entries of the \c QT_PLUGIN_PATH
+    environment variable are always added. The plugin installation
+    directory (and its existence) may change when the directory of
+    the application executable becomes known.
 
     If you want to iterate over the list, you can use the \l foreach
     pseudo-keyword: