Add support for system-level settings

In addition to the traditional per-user settings, there is now also a
system-wide settings file affecting all users. The file's platform-
specific default location can be overridden at build time.
The qbs-config tool can write these settings via the new --system
option.

[ChangeLog] Introduced the concept of system-level qbs settings

Change-Id: Ie6f675a74e96ce1fa7b2dd0712f6106071e848a6
Reviewed-by: Joerg Bornemann <joerg.bornemann@qt.io>

6 files changed, 70 insertions, 8 deletions

diff --git a/doc/qbs.qdoc b/doc/qbs.qdoc
index b37ef4b95..bfeda503a 100644
--- a/doc/qbs.qdoc
+++ b/doc/qbs.qdoc
@@ -509,6 +509,10 @@
     \row    \li qbs_use_bundled_qtscript        \li Use the bundled QtScript library.
     \endtable
 
+    In addition, you can set the \c QBS_SYSTEM_SETTINGS_DIR environment variable
+    before running qmake to specify a custom location for \QBS to look for its
+    system-level settings.
+
     \section1 Using Docker
 
     A set of Docker images for developing \QBS (which are maintained by the \QBS team) is available
diff --git a/doc/reference/cli/cli-options.qdocinc b/doc/reference/cli/cli-options.qdocinc
index 5ce7aab1c..189a3526a 100644
--- a/doc/reference/cli/cli-options.qdocinc
+++ b/doc/reference/cli/cli-options.qdocinc
@@ -287,6 +287,33 @@
 
 //! [list-root]
 
+//! [config-user]
+
+    \section2 \c {--user}
+
+    Causes read operations to display only the user-level settings,
+    while the system-level settings are ignored.
+    Write operations will target the user-level settings, which is also the default.
+
+//! [config-user]
+
+//! [config-system]
+
+    \section2 \c {--system}
+
+    Read and write operations will consider only the system-level settings.
+
+//! [config-system]
+
+//! [config-ui-system]
+
+    \section2 \c {--system}
+
+    Instructs the tool to work on the system-level settings. Otherwise,
+    the user-level settings are presented.
+
+//! [config-ui-system]
+
 //! [log-level]
 
     \section2 \c {--log-level <level>}
@@ -418,6 +445,16 @@
 
 //! [show-progress]
 
+//! [setup-tools-system]
+
+    \section2 \c {--system}
+
+    If this option is given, the profile(s) created by this tool will end up
+    in the system-level settings and thus be available to all users.
+    Otherwise, they go into the user-level settings.
+
+//! [setup-tools-system]
+
 //! [type]
 
     \section2 \c {--type <toolchain type>}
diff --git a/doc/reference/cli/tools/cli-config-ui.qdoc b/doc/reference/cli/tools/cli-config-ui.qdoc
index 29c0ed732..66f46e3e1 100644
--- a/doc/reference/cli/tools/cli-config-ui.qdoc
+++ b/doc/reference/cli/tools/cli-config-ui.qdoc
@@ -37,7 +37,7 @@
     \section1 Synopsis
 
     \code
-    qbs config-ui [--settings-dir <directory>]
+    qbs config-ui [--settings-dir <directory>] [--system]
     \endcode
 
     \section1 Description
@@ -54,6 +54,7 @@
     \section1 Options
 
     \include cli-options.qdocinc settings-dir
+    \include cli-options.qdocinc config-ui-system
     \include cli-options.qdocinc help
 
     \section1 Examples
diff --git a/doc/reference/cli/tools/cli-config.qdoc b/doc/reference/cli/tools/cli-config.qdoc
index 0d2ba9989..e32ffee0e 100644
--- a/doc/reference/cli/tools/cli-config.qdoc
+++ b/doc/reference/cli/tools/cli-config.qdoc
@@ -36,10 +36,10 @@
     \section1 Synopsis
 
     \code
-    qbs config [--settings-dir <directory>] [--list [<root> ...]]
+    qbs config [--settings-dir <directory>] [--user|--system] [--list [<root> ...]]
                [--unset <key>] [--export <file>] [--import <file>]
-    qbs config [--settings-dir <directory>] <key>
-    qbs config [--settings-dir <directory>] <key> <value>
+    qbs config [--settings-dir <directory>] [--user|--system] <key>
+    qbs config [--settings-dir <directory>] [--user|--system] <key> <value>
     \endcode
 
     \section1 Description
@@ -52,6 +52,22 @@
 
     The third form sets the specified \c <key> with the specified \c <value>.
 
+    There are two sets of settings: The system-level settings affect all users,
+    while the user-level settings are specific to the current user.
+    By default, the read operations consider both sources. If the same key is
+    present in both settings, then for list values, the system value is
+    appended to the user value, while for other types of values the user-level
+    one takes precedence. Write operations go to the user-level settings by default.
+    Use the \c {--user} and \c {--system} options to change this behavior.
+    \note It is conceivable that the default system value of the
+    \c {preferences.qbsSearchPaths} setting could pull in unwanted \QBS modules,
+    in particular when doing cross-builds. In such a case, you can set
+    \c {preferences.ignoreSystemSearchPaths} to exclude the search paths coming
+    from the system settings. You'll typically do this for a specific profile:
+    \code
+    $ qbs config profiles.myprofile.preferences.ignoreSystemSearchPaths true
+    \endcode
+
     You can use the \l{config-ui} command to open the Qbs Settings tool for
     managing settings in a hierarchical view.
 
@@ -65,6 +81,8 @@
     \include cli-options.qdocinc unset
     \include cli-options.qdocinc export
     \include cli-options.qdocinc import
+    \include cli-options.qdocinc config-user
+    \include cli-options.qdocinc config-system
     \include cli-options.qdocinc help
 
     \section1 Parameters
diff --git a/doc/reference/cli/tools/cli-setup-qt.qdoc b/doc/reference/cli/tools/cli-setup-qt.qdoc
index 9673286b3..1cf961d0d 100644
--- a/doc/reference/cli/tools/cli-setup-qt.qdoc
+++ b/doc/reference/cli/tools/cli-setup-qt.qdoc
@@ -36,8 +36,8 @@
     \section1 Synopsis
 
     \code
-    qbs setup-qt [--settings-dir <directory>] --detect
-    qbs setup-qt [--settings-dir <directory>] <path to qmake> <profile name>
+    qbs setup-qt [--settings-dir <directory>] [--system] --detect
+    qbs setup-qt [--settings-dir <directory>] [--system] <path to qmake> <profile name>
     \endcode
 
     \section1 Description
@@ -56,6 +56,7 @@
 
     \include cli-options.qdocinc detect-qt-versions
     \include cli-options.qdocinc settings-dir
+    \include cli-options.qdocinc setup-tools-system
     \include cli-options.qdocinc help
 
     \section1 Examples
diff --git a/doc/reference/cli/tools/cli-setup-toolchains.qdoc b/doc/reference/cli/tools/cli-setup-toolchains.qdoc
index 15490cc2a..af3b25069 100644
--- a/doc/reference/cli/tools/cli-setup-toolchains.qdoc
+++ b/doc/reference/cli/tools/cli-setup-toolchains.qdoc
@@ -36,8 +36,8 @@
     \section1 Synopsis
 
     \code
-    qbs setup-toolchains [--settings-dir <directory>] --detect
-    qbs setup-toolchains [--settings-dir <directory>] [--type <toolchain type>]
+    qbs setup-toolchains [--settings-dir <directory>] [--system] --detect
+    qbs setup-toolchains [--settings-dir <directory>] [--system] [--type <toolchain type>]
                          <compiler path> <profile name>
     \endcode
 
@@ -57,6 +57,7 @@
     \section1 Options
 
     \include cli-options.qdocinc settings-dir
+    \include cli-options.qdocinc setup-tools-system
     \include cli-options.qdocinc detect-toolchains
     \include cli-options.qdocinc type
     \include cli-options.qdocinc help