Merge branch '1.17' into master

Change-Id: I20a6b02ee34719636f9996e02cff9e29cf160dd7

5 files changed, 176 insertions, 7 deletions

diff --git a/doc/howtos.qdoc b/doc/howtos.qdoc
index 7e01624a0..d216ea004 100644
--- a/doc/howtos.qdoc
+++ b/doc/howtos.qdoc
@@ -53,6 +53,7 @@
     \li \l{How do I add QML files to a project?}
     \li \l{How do I define a reusable Group of files that can be included in other \QBS files?}
     \li \l{How do I print the value of a property?}
+    \li \l{How do I debug \QBS scripts?}
     \endlist
 
     \section1 How do I build a Qt-based project?
@@ -707,4 +708,41 @@
         return qbs.targetOS.contains("unix")
     }
     \endcode
+
+    It is also possible to throw an exception with the text saying what is wrong - this might
+    be useful if the property contains invalid or unsupported value:
+    \code
+    readonly property bool unix: {
+        if (qbs.targetOS.contains("darwin"))
+            throw "Apple platforms are not supported";
+        return qbs.targetOS.contains("unix")
+    }
+    \endcode
+
+    \section1 How do I debug \QBS scripts?
+
+    To debug the value of a specific property, see the \l{How do I print the value of a property}
+    section.
+
+    Similar debugging techniques could be used within \l{Rule}{Rules} or \c .js files.
+
+    It is also possible to increase \QBS' logging level using the \c --more-verbose (\c -v) option
+    of the \c{qbs build} command:
+
+    \code
+    qbs build -v config:release
+    \endcode
+
+    \QBS uses the Qt Categorized Logging system which allows to configure logging categories
+    in \l{https://doc.qt.io/qt-5/qloggingcategory.html#configuring-categories}{multiple ways}. For
+    example, to enable debug logging for the \c moduleloader category, use the following command:
+    \code
+    QT_LOGGING_RULES="qbs.moduleloader.debug=true" qbs resolve
+    \endcode
+
+    To list all the files in the project directory and show whether they are known to qbs in the
+    respective configuration, use the \c{qbs status} command:
+    \code
+    qbs status config:release
+    \endcode
 */
diff --git a/doc/qbs.qdoc b/doc/qbs.qdoc
index 854a96aca..abd1b2aad 100644
--- a/doc/qbs.qdoc
+++ b/doc/qbs.qdoc
@@ -1445,6 +1445,9 @@
 
     \title Building Applications
 
+    This section assumes that \QBS is present in \c PATH. For the details how to install \QBS, see
+    the \l{Installing} page.
+
     To build applications from the command line, enter the following commands:
 
     \code
@@ -1530,7 +1533,7 @@
     \c{<build root>/install-root}. The \l{qbs::installPrefix}{qbs.installPrefix} and
     \l{qbs::installDir}{qbs.installDir} properties are appended to the root folder.
     \code
-    $ qbs build qbs.installPrefix:/usr
+    qbs build qbs.installPrefix:/usr
     \endcode
     In this example, the executable will be installed into the \c{<build root>/install-root/usr/bin}
     folder and the QML files will be installed into the
@@ -1541,12 +1544,12 @@
     To override the default location, use the \c --install-root option of the \c{qbs install}
     command:
     \code
-    $ qbs build --no-install qbs.installPrefix:/usr
-    # qbs install --no-build --install-root /
+    qbs build --no-install qbs.installPrefix:/usr
+    sudo qbs install --no-build --install-root /
     \endcode
     In this example, artifacts will be installed directly into the \c /usr folder. Since the
     \c{qbs install} command implies \c build, we use the \c --no-build parameter to ensure that
-    we do not accidentally rebuild the project, thereby changing the artifacts owner to \c root.
+    we do not accidentally rebuild the project, thereby changing the artifacts' owner to \c root.
 
     Sometimes, it makes sense to install the application into a temporary root folder, keeping the
     same folder structure within that root folder as in the examples above; for instance,
@@ -1564,7 +1567,7 @@
     parameter:
 
     \code
-    $ qbs install --clean-install-root --install-root /tmp/myProjectRoot
+    qbs install --clean-install-root --install-root /tmp/myProjectRoot
     \endcode
 
     For more information about how the installation path is constructed, see
diff --git a/doc/reference/items/language/product.qdoc b/doc/reference/items/language/product.qdoc
index 6b87cffc0..f3b51f0bf 100644
--- a/doc/reference/items/language/product.qdoc
+++ b/doc/reference/items/language/product.qdoc
@@ -207,9 +207,13 @@
 /*!
     \qmlproperty stringList Product::qbsSearchPaths
 
+    A list of paths that are searched for imports, modules and module providers.
+
     The value set here will be merged with the value of
     \l{Project::qbsSearchPaths}{project.qbsSearchPaths}.
 
+    For the details about how to add custom items, see the \l{Custom Modules and Items} page.
+
     \defaultvalue \l{Project::qbsSearchPaths}{project.qbsSearchPaths}
 */
 
diff --git a/doc/reference/items/language/project.qdoc b/doc/reference/items/language/project.qdoc
index d2db644f6..b0411649e 100644
--- a/doc/reference/items/language/project.qdoc
+++ b/doc/reference/items/language/project.qdoc
@@ -92,11 +92,13 @@
 /*!
     \qmlproperty stringList Project::qbsSearchPaths
 
-    A list of paths that are searched for imports and modules in addition to the ones listed
-    in \c{preferences.qbsSearchPaths}. The value set here is merged with the value
+    A list of paths that are searched for imports, modules and module providers in addition to the
+    ones listed in \c{preferences.qbsSearchPaths}. The value set here is merged with the value
     inherited from the parent project, if there is one. The result is inherited by
     all products in the project.
 
+    For the details about how to add custom items, see the \l{Custom Modules and Items} page.
+
     \defaultvalue An empty list
 */
 
diff --git a/doc/reference/modules/cpp-module.qdoc b/doc/reference/modules/cpp-module.qdoc
index f5f43f0f9..e92359377 100644
--- a/doc/reference/modules/cpp-module.qdoc
+++ b/doc/reference/modules/cpp-module.qdoc
@@ -365,6 +365,15 @@
 */
 
 /*!
+    \qmlproperty bool cpp::createSymlinks
+    \unixproperty
+
+    Whether to create version alias symlinks when building a dynamic library.
+
+    \defaultvalue \c true
+*/
+
+/*!
     \qmlproperty bool cpp::discardUnusedData
     \since Qbs 1.10
 
@@ -516,6 +525,100 @@
 */
 
 /*!
+    \qmlproperty string cpp::executablePrefix
+
+    A string to prepend to the executable file \l{Product::targetName}{name}.
+
+    \defaultvalue \c ""
+*/
+
+/*!
+    \qmlproperty string cpp::dynamicLibraryPrefix
+
+    A string to prepend to the dynamic library file \l{Product::targetName}{name}.
+
+    \defaultvalue \l{qbs::toolchain}{toolchain}-dependent, typical values are \c "" or \c "lib"
+*/
+
+/*!
+    \qmlproperty string cpp::loadableModulePrefix
+    \appleproperty
+
+    A string to prepend to the Darwin loadable module file \l{Product::targetName}{name}.
+
+    \defaultvalue \c ""
+*/
+
+/*!
+    \qmlproperty string cpp::staticLibraryPrefix
+
+    A string to prepend to the static library file \l{Product::targetName}{name}.
+
+    \defaultvalue \l{qbs::toolchain}{toolchain}-dependent, typical values are \c "" or \c "lib"
+*/
+
+/*!
+    \qmlproperty string cpp::executableSuffix
+
+    A string to append to the executable file \l{Product::targetName}{name}.
+
+    \defaultvalue \l{qbs::toolchain}{toolchain}-dependent, typical values are \c "" or \c ".exe"
+*/
+
+/*!
+    \qmlproperty string cpp::dynamicLibrarySuffix
+
+    A string to append to the dynamic library file \l{Product::targetName}{name}.
+
+    \defaultvalue \l{qbs::toolchain}{toolchain}-dependent, typical values are \c ".so", \c ".dll"
+    or \c "dylib"
+*/
+
+/*!
+    \qmlproperty string cpp::dynamicLibraryImportSuffix
+    \windowsproperty
+
+    A string to append to the dynamic library import file \l{Product::targetName}{name}.
+
+    \defaultvalue \c ".lib"
+*/
+
+/*!
+    \qmlproperty string cpp::loadableModuleSuffix
+    \appleproperty
+
+    A string to append to the Darwin loadable module file \l{Product::targetName}{name}.
+
+    \defaultvalue \c ".bundle"
+*/
+
+/*!
+    \qmlproperty string cpp::staticLibrarySuffix
+
+    A string to append to the executable file \l{Product::targetName}{name}.
+
+    \defaultvalue \l{qbs::toolchain}{toolchain}-dependent, typical values are \c ".a" or \c ".lib"
+*/
+
+/*!
+    \qmlproperty string cpp::debugInfoSuffix
+
+    A string to append to the debug information file name.
+
+    \defaultvalue \l{qbs::toolchain}{toolchain}-dependent, typical values are \c ".debug",
+    \c ".pdb" or \c ".dwarf"
+*/
+
+/*!
+    \qmlproperty string cpp::debugInfoBundleSuffix
+    \appleproperty
+
+    A string to append to the debug information bundle name.
+
+    \defaultvalue \c ".dSYM"
+*/
+
+/*!
     \qmlproperty pathList cpp::prefixHeaders
     \since Qbs 1.0.1
 
@@ -949,6 +1052,15 @@
 */
 
 /*!
+    \qmlproperty bool cpp::enableSuspiciousLinkerFlagWarnings
+    \since Qbs 1.8
+
+    Whether to print warnings about escaped linker flags (such as \c -Xlinker and \c -Wl).
+
+    \defaultvalue \c{true}
+*/
+
+/*!
     \qmlproperty string cpp::exceptionHandlingModel
     \since Qbs 1.5
 
@@ -1449,6 +1561,16 @@
 */
 
 /*!
+    \qmlproperty string cpp::rpathLinkFlag
+    \since Qbs 1.9
+
+    The rpath link flag used by the linker.
+
+    \defaultvalue \l{qbs::toolchain}{toolchain}-dependent, typical values are \c "-rpath-link="
+    or \c "-L"
+*/
+
+/*!
     \qmlproperty string cpp::variantSuffix
     \since Qbs 1.10