Doc: Update info about CMake support

Fixes: QTCREATORBUG-24497
Change-Id: I524907e461ba91b18a6741690bef9ed27a40fb5f
Reviewed-by: Cristian Adam <cristian.adam@qt.io>

11 files changed, 103 insertions, 66 deletions

diff --git a/doc/qtcreator/images/qtcreator-android-cmake-settings.png b/doc/qtcreator/images/qtcreator-android-cmake-settings.png
index 7f8026bcca..e02c77c38b 100644
--- a/doc/qtcreator/images/qtcreator-android-cmake-settings.png
+++ b/doc/qtcreator/images/qtcreator-android-cmake-settings.png
diff --git a/doc/qtcreator/images/qtcreator-cmake-build-settings.png b/doc/qtcreator/images/qtcreator-cmake-build-settings.png
index c5da0555aa..33be38d67c 100644
--- a/doc/qtcreator/images/qtcreator-cmake-build-settings.png
+++ b/doc/qtcreator/images/qtcreator-cmake-build-settings.png
diff --git a/doc/qtcreator/images/qtcreator-cmake-build-steps.png b/doc/qtcreator/images/qtcreator-cmake-build-steps.png
index 5809136a85..02784e47d2 100644
--- a/doc/qtcreator/images/qtcreator-cmake-build-steps.png
+++ b/doc/qtcreator/images/qtcreator-cmake-build-steps.png
diff --git a/doc/qtcreator/images/qtcreator-cmake-clean-steps.png b/doc/qtcreator/images/qtcreator-cmake-clean-steps.png
index 88be99d715..e04711c3a7 100644
--- a/doc/qtcreator/images/qtcreator-cmake-clean-steps.png
+++ b/doc/qtcreator/images/qtcreator-cmake-clean-steps.png
diff --git a/doc/qtcreator/images/qtcreator-cmakeexecutable.png b/doc/qtcreator/images/qtcreator-cmakeexecutable.png
index 5c57588762..31f162d48b 100755
--- a/doc/qtcreator/images/qtcreator-cmakeexecutable.png
+++ b/doc/qtcreator/images/qtcreator-cmakeexecutable.png
diff --git a/doc/qtcreator/images/qtcreator-kits-cmake.png b/doc/qtcreator/images/qtcreator-kits-cmake.png
new file mode 100644
index 0000000000..9ccecb61db
--- /dev/null
+++ b/doc/qtcreator/images/qtcreator-kits-cmake.png
diff --git a/doc/qtcreator/src/cmake/creator-projects-cmake-building.qdocinc b/doc/qtcreator/src/cmake/creator-projects-cmake-building.qdocinc
index a31449984c..d197facbc6 100644
--- a/doc/qtcreator/src/cmake/creator-projects-cmake-building.qdocinc
+++ b/doc/qtcreator/src/cmake/creator-projects-cmake-building.qdocinc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2019 The Qt Company Ltd.
+** Copyright (C) 2020 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the Qt Creator documentation.
@@ -34,32 +34,45 @@
 
     \section2 CMake Build Configuration
 
+    Configuring medium-sized to large CMake projects in \QC can be a
+    challenge due to the number of options that you need to pass to
+    CMake to configure the project correctly. \QC creates an initial
+    configuration for you based on the kit settings and displays it in
+    the \uicontrol {Initial CMake parameters} field.
+
     \image qtcreator-cmake-build-settings.png
 
-    Setting names with a common prefix (up to the first underscore character)
-    are grouped under the prefix. To view all settings, select the
-    \uicontrol Advanced check box.
+    In the \uicontrol Value column, you can view and edit the actual values
+    of the parameters that are passed to CMake. Parameter names are listed
+    in the \uicontrol Key column. Names with a common prefix (up to the first
+    underscore character) are grouped under the prefix. To view all parameters,
+     select the \uicontrol Advanced check box.
 
-    To add build settings, select \uicontrol Add, and then select the type of
-    the setting that you are adding: \uicontrol Boolean, \uicontrol String,
+    To add parameters, select \uicontrol Add, and then select the type of
+    the parameter that you are adding: \uicontrol Boolean, \uicontrol String,
     \uicontrol Directory, or \uicontrol File.
 
-    To change the type of the selected setting, select
+    To change the type of the selected parameter, select
     \uicontrol {Force to bool}, \uicontrol {Force to file},
     \uicontrol {Force to directory}, or \uicontrol {Force to string}.
 
-    To modify the value of a build setting, double-click it, or select it,
+    To modify the value of a parameter, double-click it, or select it,
     and then select \uicontrol Edit. To save the changes, select
     \uicontrol {Apply Configuration Changes}. Keep in mind that a
     configuration change might trigger a follow-up configuration change.
 
-    To remove a setting, select \uicontrol Unset.
+    To remove a parameter, select \uicontrol Unset.
 
     To reset the changes that you made, select \uicontrol Reset.
 
-    To reconfigure CMake, select \uicontrol Build >
-    \uicontrol {Clear CMake Configuration}, and then
-    select \uicontrol Build > \uicontrol {Rescan Project}.
+    The parameter values that you change are passed via \c -D<option>=<value>
+    to CMake, which stores the options in the CMakeCache.txt file. This means
+    that if you remove the build directory, all the custom parameters that are
+    not part of the initial CMake parameters are also removed.
+
+    To reconfigure a project after making changes to the initial parameters,
+    select \uicontrol Build > \uicontrol {Clear CMake Configuration}, which
+    removes the CMakeCache.txt file. This enables you to do a full rebuild.
 
 //! [cmake build configuration]
 
@@ -69,11 +82,12 @@
     \section2 CMake Build Steps
 
     \QC builds CMake projects by running \c {cmake . --build}, which then runs
-    whatever is needed based on how the project was configured: \c make,
-    \c mingw32-make, \c nmake, or \c ninja, for example.
+    the CMake generator specified in the project configuration: \c make,
+    \c mingw32-make, \c nmake, or \c ninja, for example. The CMake generator
+    produces project files for \QC.
 
-    You can add arguments and targets for the build command in
-    \uicontrol {Build Steps}.
+    You can add arguments to pass to CMake and the generator and targets for
+    the build command in \uicontrol {Build Steps}.
 
     \image qtcreator-cmake-build-steps.png
 
@@ -117,8 +131,8 @@
 
     \section2 CMake Clean Steps
 
-    When building with CMake, you can add arguments and targets for the clean
-    command in \uicontrol {Clean Steps}.
+    When building with CMake, you can add arguments to pass to CMake and the
+    generator and targets for the clean command in \uicontrol {Clean Steps}.
 
     \image qtcreator-cmake-clean-steps.png
 
diff --git a/doc/qtcreator/src/cmake/creator-projects-cmake.qdoc b/doc/qtcreator/src/cmake/creator-projects-cmake.qdoc
index fa055e6975..594e7c1682 100644
--- a/doc/qtcreator/src/cmake/creator-projects-cmake.qdoc
+++ b/doc/qtcreator/src/cmake/creator-projects-cmake.qdoc
@@ -62,41 +62,53 @@
     \QC requires CMake's \l{https://cmake.org/cmake/help/latest/manual/cmake-file-api.7.html}
     {file-based API}.  Please make sure to use CMake version 3.14, or later.
 
-    To specify paths to CMake executables:
+    To view and specify settings for CMake:
 
     \list 1
 
         \li Select \uicontrol Tools > \uicontrol Options > \uicontrol Kits >
-            \uicontrol CMake > \uicontrol Add.
+            \uicontrol CMake.
 
             \image qtcreator-cmakeexecutable.png
 
-        \li In the \uicontrol Name field, specify a name for the tool.
+        \li The \uicontrol Name field displays a name for the CMake
+            installation.
 
-        \li In the \uicontrol Path field, specify the path to the CMake
+        \li The \uicontrol Path field displays the path to the CMake
             executable.
 
-        \li In the \uicontrol {Help file} field, specify the path to the
+        \li The \uicontrol {Help file} field displays the path to the
             CMake help file (.qch) provided by and installed with CMake.
 
+        \li Deselect the \uicontrol {Autorun CMake} check box if you do not want
+            to automatically run CMake every time when you save changes to
+            \c {CMakeLists.txt} files.
+
         \li Select the \uicontrol {Auto-create build directories} check box to
-            automatically create build directories for CMake projects.
+            initially configure the project in a temporary directory. When you
+            build the project \QC starts from scratch and configures the
+            project again using the build directory.
 
         \li Select \uicontrol Apply to save your changes.
 
     \endlist
 
-    \note When the \uicontrol {Autorun CMake} check box is enabled, \QC
-    automatically runs CMake when you make changes to \c {CMakeLists.txt} files.
-    We recommend that you do not disable this check box, because that would
-    eventually make \QC and the project disagree on what the project information
-    is.
+    To add a path to a CMake executable that \QC does not detect automatically,
+    and to specify settings for it, select \uicontrol Add. To make changes to
+    automatically detected installations, select \uicontrol Clone.
+
+    \QC uses the \e {default CMake} if it does not have enough information
+    to choose the CMake to use. To set the selected CMake executable as the
+    default, select \uicontrol {Make Default}.
+
+    To remove the selected CMake executable from the list, select
+    \uicontrol Remove.
 
     Select the \uicontrol Kits tab to add the CMake tool to a build and run kit.
     The kit also specifies the CMake generator that is used for producing
-    project files for \QC and the configuration variables that are used:
+    project files for \QC and the initial configuration parameters:
 
-    \image qtcreator-kits.png
+    \image qtcreator-kits-cmake.png
 
     For more information, see \l {Adding Kits}.
 
@@ -134,14 +146,12 @@
     Through external libraries, \QC can support code completion and syntax
     highlighting as if they were part of the current project or the Qt library.
 
-    \QC detects the external libraries using the \c {FIND_PACKAGE()}
+    \QC detects the external libraries using the \c {find_package()}
     macro. Some libraries come with the CMake installation. You can find those
     in the \c {Modules} directory of your CMake installation.
-
-    \note If you provide your own libraries, you also need to provide your own
-    \c {FindXXX.cmake} file. For more information, see
-    \l{https://gitlab.kitware.com/cmake/community/wikis/FAQ#writing-findxxxcmake-files}
-    {Writing FindXXX.cmake files}.
+    For more information, see
+    \l{https://cmake.org/cmake/help/latest/manual/cmake-packages.7.html}
+    {cmake-packages(7)}.
 
     Syntax completion and highlighting work once your project successfully
     builds and links against the external library.
diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-building.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-building.qdoc
index 29ab47eae9..e453b315db 100644
--- a/doc/qtcreator/src/projects/creator-only/creator-projects-building.qdoc
+++ b/doc/qtcreator/src/projects/creator-only/creator-projects-building.qdoc
@@ -122,8 +122,9 @@
 
     \QC automatically runs CMake when you make changes to \c {CMakeLists.txt}
     files. To disable this feature, select \uicontrol Tools >
-    \uicontrol Options > \uicontrol Kits > \uicontrol CMake >
-    \uicontrol {Autorun CMake}.
+    \uicontrol Options > \uicontrol Kits > \uicontrol CMake. Select the CMake
+    executable to edit, and then deselect the \uicontrol {Autorun CMake} check
+    box.
 
     For more information, see \l {Setting Up CMake}.
 
diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-build.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-build.qdoc
index c148252405..4d13904606 100644
--- a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-build.qdoc
+++ b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-build.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2018 The Qt Company Ltd.
+** Copyright (C) 2020 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the Qt Creator documentation.
@@ -42,15 +42,25 @@
     debug symbols that you need for debugging the application but that you
     can leave out from the release version. Generally, you use the debug
     configuration for testing and the release configuration for creating
-    the final installation file. A profile configuration is an optimized release
-    build that is delivered with separate debug information. It is best suited
-    for analyzing applications.
+    the final installation file.
+
+    If you selected CMake as the build system for the project, you can
+    use a \e {minimum size release} build configuration to create the
+    final  installation file. It is a release build that makes the size
+    of the binary package as small as possible, even if this makes the
+    application slower.
+
+    A profile build (which is called \e {release with debug information}
+    when using CMake) is an optimized release build that is delivered
+    with separate debug information. It is best suited for analyzing
+    applications.
 
     \section1 Managing Build Configurations
 
     You specify build settings in the \uicontrol Projects mode.
     To add a new build configuration, click \uicontrol Add and select the type of
-    configuration you would like to add. You can add as many build
+    configuration you would like to add. The options you have depend on the
+    build system that you selected for the project. You can add as many build
     configurations as you need. You can also select \uicontrol Clone to
     add a build configuration that is based on the currently selected one.
 
@@ -67,6 +77,21 @@
     The available build settings depend on the build system that you selected
     for the project.
 
+    \section2 Compiling QML
+
+    Since Qt 5.11, you can compile QML source code into the final binary. This
+    improves the startup time of the application and eliminates the need to
+    deploy QML files together with the application. For more information, see
+    \l{Ahead-of-Time Compilation}.
+
+    \QC project wizard templates create Qt Quick projects that can be compiled,
+    because they are set up to use the Qt Resource System. To compile Qt Quick
+    code, select \uicontrol Enable in the \uicontrol {Qt Quick Compiler}
+    field. To use default settings, select \uicontrol {Leave at Default}.
+
+    \note In earlier Qt versions, this was a commercial feature. For more
+    information, see \l{http://doc.qt.io/QtQuickCompiler/}{Qt Quick Compiler}.
+
     \section2 qmake Build Configuration
 
     \image qtcreator-projectpane.png "qmake general build settings pane"
@@ -97,21 +122,6 @@
     > \uicontrol Options > \uicontrol {Build & Run} >
     \uicontrol {Default Build Properties}.
 
-    \section3 Compiling QML
-
-    Since Qt 5.11, you can compile QML source code into the final binary. This
-    improves the startup time of the application and eliminates the need to
-    deploy QML files together with the application. For more information, see
-    \l{Ahead-of-Time Compilation}.
-
-    \QC new project wizards create Qt Quick projects that can be compiled,
-    because they are set up to use the Qt Resource System. To compile Qt Quick
-    code, select \uicontrol Enable in the \uicontrol {Qt Quick Compiler}
-    field. To use default settings, select \uicontrol {Leave at Default}.
-
-    \note In earlier Qt versions, this was a commercial feature. For more
-    information, see \l{http://doc.qt.io/QtQuickCompiler/}{Qt Quick Compiler}.
-
     \include creator-projects-cmake-building.qdocinc cmake build configuration
     \include creator-projects-meson-building.qdocinc meson build configuration
 
@@ -130,9 +140,11 @@
     apply.
 
     You can specify command-line arguments in the arguments fields:
-    \uicontrol {Additional arguments}, \uicontrol {Command arguments},
-    \uicontrol {Make arguments}, \uicontrol Arguments, \uicontrol {Default Arguments},
-    or \uicontrol {Extra arguments}. You can create shell command lines
+    \uicontrol Arguments, \uicontrol {Additional arguments},
+    \uicontrol {CMake arguments}, \uicontrol {Command arguments},
+    \uicontrol {Default arguments}, \uicontrol {Extra arguments},
+    \uicontrol {Make arguments}, or \uicontrol {Tool arguments}.
+    You can create shell command lines
     that can contain redirection and other advanced constructs. However, some
     more complex use cases, such as piping test data into the application being
     tested or grouping commands, are not supported because the value of the
diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-targets.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-targets.qdoc
index 6c3f32596d..40d486ebad 100644
--- a/doc/qtcreator/src/projects/creator-only/creator-projects-targets.qdoc
+++ b/doc/qtcreator/src/projects/creator-only/creator-projects-targets.qdoc
@@ -162,9 +162,9 @@
             \uicontrol Change to add settings to Qbs build profiles. For more
             information, see \l {Editing Qbs Profiles}.
 
-        \li In the \uicontrol {CMake Tool} field, select the CMake tool to use
-            for building the project. Select \uicontrol Manage to add installed
-            CMake tools to the list. For more information, see
+        \li In the \uicontrol {CMake Tool} field, select the CMake executable
+            to use for building the project. Select \uicontrol Manage to add
+            installed CMake executables to the list. For more information, see
             \l{Adding CMake Tools}.
 
         \li In the \uicontrol {CMake generator} field, select \uicontrol Change
@@ -175,7 +175,7 @@
             warning if you select a generator that is not supported.
 
         \li In the \uicontrol {CMake configuration} field, select
-            \uicontrol Change to edit the variables of the CMake configuration
+            \uicontrol Change to edit the parameters of the CMake configuration
             for the kit.
 
         \li In the \uicontrol {Meson tool} field, select the Meson tool to use