Clarify the meaning and usage of the build configuration parameter

The documentation for the build configuration parameter was a bit confusing. It
was also not explained that parameter assignments before the first occurrence of
config are global. This patch explains config in more detail and relates it to
qbs.configurationName and qbs.buildVariant.

Task-number: QBS-1425
Change-Id: I478f7228aaa0696149f937599b89f785a65c6717
Reviewed-by: Christian Kandeler <christian.kandeler@qt.io>
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>

3 files changed, 37 insertions, 12 deletions

diff --git a/doc/reference/cli/builtin/cli-build.qdoc b/doc/reference/cli/builtin/cli-build.qdoc
index 7844dceea..f9312350d 100644
--- a/doc/reference/cli/builtin/cli-build.qdoc
+++ b/doc/reference/cli/builtin/cli-build.qdoc
@@ -113,9 +113,10 @@
     Builds the application using different \l{cpp} module properties
     for debug and release configurations. For the debug configuration, warnings
     will cause the build to fail, whereas for the release configuration, the
-    size of the build artifacts will be optimized:
+    size of the build artifacts will be optimized. Both configurations are built
+    with a profile named \c{"qt"}:
 
     \code
-    qbs build config:debug modules.cpp.treatWarningsAsErrors:true config:release modules.cpp.optimization:small
+    qbs build profile:qt config:debug modules.cpp.treatWarningsAsErrors:true config:release modules.cpp.optimization:small
     \endcode
 */
diff --git a/doc/reference/cli/cli-parameters.qdocinc b/doc/reference/cli/cli-parameters.qdocinc
index 70f7a087f..36bb08649 100644
--- a/doc/reference/cli/cli-parameters.qdocinc
+++ b/doc/reference/cli/cli-parameters.qdocinc
@@ -41,17 +41,29 @@
 
     Specifies the build configuration to use.
 
-    The \c debug and \c release configuration names imply the respective build
-    variant. A debug build contains additional debug symbols that are needed for
-    debugging the application but that can be left out from the release
-    version. Generally, debug builds are used for testing and release builds
-    for creating the final installation file.
+    \QBS can build a project for one or multiple configurations at once, each
+    having a different set of parameters. The \c config parameter has a
+    special function: with each occurrence a new configuration instance begins
+    and all subsequent parameters until the next \c config are assigned to this
+    instance. Parameter assignments before the first occurrence of \c config are
+    applied to all build configurations. Inside products and modules, the
+    current active build configuration can be retrieved via
+    \l{qbs::configurationName}{qbs.configurationName}.
+
+    In the following snippet, a profile \c clang is applied to all
+    configurations while \c cpp.optimization is different for \c debug and
+    \c release:
 
-    The build variant can also be specified explicitly by using the
-    \l{qbs::buildVariant}{qbs.buildVariant} property.
+    \code
+    profile:clang config:debug cpp.optimization:none config:release cpp.optimization:small
+    \endcode
 
-    When naming configurations created for special purposes, follow the
-    rules for legal names generally used in programming languages:
+    The value of \c config determines the name of the build folder and affects
+    the default value of the \l{qbs::buildVariant}{qbs.buildVariant} property.
+    \QBS knows the \c config values \c{"debug"} and \c{"release"}, but in
+    general any name can be chosen. When naming configurations created for
+    special purposes, follow the rules for legal names generally used in
+    programming languages:
 
     \list
         \li The first character must be a letter (a-z), an underscore (_), or a
diff --git a/doc/reference/modules/qbs-module.qdoc b/doc/reference/modules/qbs-module.qdoc
index 2ca034397..eea67688b 100644
--- a/doc/reference/modules/qbs-module.qdoc
+++ b/doc/reference/modules/qbs-module.qdoc
@@ -98,9 +98,13 @@
 /*!
     \qmlproperty string qbs::configurationName
     \since Qbs 1.6
+    \readonly
 
     The name of the current build configuration.
 
+    The build configuration is set via the command line parameter \c
+    config. For more information, see \l{build}{build}.
+
     \defaultvalue \c{"default"}
 */
 
@@ -109,7 +113,15 @@
 
     The name of the build variant for the current build.
 
-    \defaultvalue \c{"debug"}
+    Possible values are \c{"debug"} and \c{"release"}. A debug build usually
+    contains additional debug symbols that are needed for debugging the
+    application but that can be left out from the release version. Debug builds
+    are used for testing and release builds for creating the final installation
+    file.
+
+    \defaultvalue \c{"release"} if
+    \l{qbs::configurationName}{qbs.configurationName} is \c{"release"}. Otherwise
+    \c{"debug"}
 */
 
 /*!