Doc: Turn "Running on Multiple Platforms" into how-to topics

And hide it from the top level TOC in the manual.
Link to "How To: Build with CMake" from CMake topics.

Task-number: QTCREATORBUG-29361
Change-Id: If0522cdd9636ac075e8bdeafa0fc7248199aaf2a
Reviewed-by: Christian Kandeler <christian.kandeler@qt.io>

doc/qtcreator/src/android/androiddev.qdoc

@@ -202,7 +202,7 @@
 
     To start an AVD, select \uicontrol {Start AVD}. Usually, you don't need to
     start AVDs separately because \QC starts them when you
-    select them in the \l{Building for Multiple Platforms}{kit selector} to
+    select them in the \l{Build for many platforms}{kit selector} to
     \l{Deploying to Android}{deploy applications} to them.
 
     To remove an AVD from the list and the kit selector, select

doc/qtcreator/src/android/deploying-android.qdoc

@@ -61,7 +61,7 @@
     To remove the current deployment method, select \uicontrol Remove.
 
     \QC deploys the packages on the Android device that you select in the
-    \l{Building for Multiple Platforms}{kit selector}. To add devices, select
+    \l{Build for many platforms}{kit selector}. To add devices, select
     \uicontrol Manage.
 
     For more information about specifying additional start options for

doc/qtcreator/src/baremetal/creator-baremetal-dev.qdoc

@@ -262,7 +262,7 @@
 
     You can build applications for and run them on bare metal devices
     in the same way as for and on the desktop. For more information, see
-    \l{Building for Multiple Platforms} and \l{Run on many platforms}.
+    \l{Build for many platforms} and \l{Run on many platforms}.
 
     \sa {Enable and disable plugins}
 */

doc/qtcreator/src/cmake/creator-projects-cmake-building.qdoc

@@ -301,5 +301,5 @@
 
     \sa {Activate kits for a project}, {Add custom output parsers},
     {Configure projects for building}, {Configure projects for running},
-    {Open projects}, {CMake}
+    {Build with CMake}{How To: Build with CMake}, {Open projects}, {CMake}
 */

doc/qtcreator/src/cmake/creator-projects-cmake.qdoc

@@ -47,8 +47,8 @@
             Typically, you cannot compile such projects without manual changes.
     \endlist
 
-    \sa {Build with CMake}{How To: Build with CMake}, {CMake Build Configuration},
+    \sa {Configure projects for building}, {Configure projects for running},
-    {Configure projects for building}, {Configure projects for running},
+    {Build with CMake}{How To: Build with CMake}, {CMake Build Configuration},
     {Debug CMake project files}, {Deploying to Remote Linux}, {Open projects},
     {Use compilation databases}
 */
@@ -70,9 +70,8 @@
 
     \image qtcreator-projects-view-edit.png {CMake project in Projects view}
 
-    To disable this
+    To disable this behavior, go to \preferences > \uicontrol CMake >
-    behavior, select \preferences > \uicontrol CMake > \uicontrol General, and
+    \uicontrol General and clear \uicontrol {Autorun CMake}.
-    then deselect the \uicontrol {Autorun CMake} check box.
 
     \image qtcreator-preferences-cmake-general.webp {General tab in CMake Preferences}
 
@@ -100,7 +99,7 @@
     box. The change takes effect after you select \uicontrol Build >
     \uicontrol {Run CMake}.
 
-    \sa {CMake}, {Manage files in CMake projects}, {Open projects},
+    \sa {Build with CMake}{How To: Build with CMake}, {CMake}, {Open projects},
     {File System}, {Projects}
 */
 
@@ -125,7 +124,8 @@
         \li Switching to the Help mode
     \endlist
 
-    \sa {CMake}, {Read Documentation}{How To: Read Documentation}
+    \sa {Build with CMake}{How To: Build with CMake}, {CMake},
+    {Read Documentation}{How To: Read Documentation}
 */
 
 /*!
@@ -183,7 +183,8 @@
 
     \image qtcreator-kits-cmake.png {Kits preferences}
 
-    \sa {CMake}, {Add kits}, {kits-tab}{Kits}
+    \sa {Build with CMake}{How To: Build with CMake}, {CMake}, {Add kits},
+    {kits-tab}{Kits}
 */
 
 /*!
@@ -234,8 +235,8 @@
 
     Warnings and errors are displayed in \l {Issues}.
 
-    \sa {CMake}, {Add libraries to CMake projects}, {Complete CMake code},
+    \sa {Build with CMake}{How To: Build with CMake}, {CMake}, {Completion},
-    {Format CMake files}, {Completion}, {Snippets}
+    {Snippets}
 */
 
 /*!
@@ -263,7 +264,8 @@
     Press \key Tab or \key Enter to accept the selected suggestion and complete
     the code.
 
-    \sa {CMake}, {Edit CMake configuration files}, {Completion}, {Snippets}
+    \sa {Build with CMake}{How To: Build with CMake}, {CMake}, {Completion},
+    {Snippets}
 */
 
 /*!
@@ -297,8 +299,7 @@
             current project.
     \endlist
 
-    \sa {CMake},{Complete CMake code}, {Edit CMake configuration files},
+    \sa {Build with CMake}{How To: Build with CMake}, {Edit MIME types}, {CMake}
-    {Edit MIME types}
 */
 
 /*!
@@ -324,8 +325,7 @@
     When you rename or remove files in the \l {Projects} or \l {File System}
     view, \QC renames them in the CMakeLists.txt file or removes them from it.
 
-    \sa {CMake}, {Add libraries to CMake projects}, {Create files},
+    \sa {Create files}, {Build with CMake}{How To: Build with CMake}, {CMake},
-    {Edit CMake configuration files}, {View CMake project contents},
     {File System}, {Projects}
 */
 
@@ -377,6 +377,6 @@
     list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
     \endcode
 
-    \sa {CMake}, {Edit CMake configuration files}, {Complete CMake code},
+    \sa {Build with CMake}{How To: Build with CMake}, {CMake}, {Completion},
-    {Completion}, {Snippets}
+    {Snippets}
 */

doc/qtcreator/src/debugger/creator-only/creator-debugger.qdoc

@@ -154,7 +154,7 @@
 
     For \l {Creating a Qt for Python Application with Qt Widgets}{Python} projects,
     start debugging the \c main.py file. If you encounter problems, check the
-    active build target in the \l{Building for Multiple Platforms}{kit selector}.
+    active build target in the \l{Build for many platforms}{kit selector}.
 
     \section1 Debugger Operating Modes
 

doc/qtcreator/src/projects/creator-only/creator-build-settings-qmake.qdoc

@@ -39,7 +39,7 @@
 
     In the \uicontrol {Tooltip in target selector} field, you can enter text
     that is displayed as a tooltip when you hover the mouse over the build
-    configuration in the \l{Building for Multiple Platforms}{kit selector}.
+    configuration in the \l{Build for many platforms}{kit selector}.
 
     You can create separate versions of project files to keep platform-dependent
     code separate. You can use qmake \l{Adding Platform Specific Source Files}

doc/qtcreator/src/projects/creator-only/creator-projects-building-running.qdoc

@@ -12,9 +12,7 @@
     \page creator-building-running.html
     \nextpage creator-live-preview.html
 
-    \title Building and Running
+    \title Running on Devices
-
-    \image front-preview.png
 
     \QC supports running and deploying Qt applications that you build
     for different target platforms or with different compilers, debuggers, or
@@ -31,12 +29,6 @@
             Android and embedded Linux devices. The changes you make to
             the UI are instantly visible to you in the preview.
 
-        \li \l{Building for Multiple Platforms}
-
-            \e {Build configurations} have everything you need to compile
-            the sources into binaries. Build configurations use the tools and settings
-            defined in their corresponding kit.
-
         \li \l{Deploying to Devices}
 
             \e {Deploy configurations} handle the packaging and copying of

doc/qtcreator/src/projects/creator-only/creator-projects-building.qdoc

@@ -8,23 +8,26 @@
 // **********************************************************************
 
 /*!
-    \previouspage qt-design-viewer.html
     \page creator-building-targets.html
-    \nextpage creator-running-targets.html
+    \previouspage creator-how-tos.html
 
-    \title Building for Multiple Platforms
+    \ingroup creator-how-to-build
 
-    You can build applications for multiple target platforms, or using different
+    \title Build for many platforms
+
+    You can build applications for many target platforms, or using different
     compilers, debuggers or Qt versions. \l{glossary-buildandrun-kit}{Kits}
-    define the tools, \l{glossary-device}{device} type and other settings to use.
+    define the tools, \l{glossary-device}{device} type, and other settings to use.
 
     By default, when you run the application, you
     automatically build and deploy it first.
     However, you can also perform each operation separately.
 
     To check that the application code can be compiled and linked for a device,
-    you can build the project. The build errors and warnings are displayed in
+    build the project. You can see build errors and warnings in \l Issues and
-    the \l Issues. More detailed information is displayed in \l {Compile Output}.
+    more details in \l {Compile Output}.
+
+    \section1 Build an application
 
     To build an application:
 
@@ -37,7 +40,7 @@
 
             \image qtcreator-kit-selector.webp {Kit selector}
 
-        \li  Choose \uicontrol Build > \uicontrol {Build Project} or press
+        \li  Select \uicontrol Build > \uicontrol {Build Project} or press
              \key {Ctrl+B}.
 
              Or, select \inlineimage icons/run_small.png (\uicontrol Run) to
@@ -45,23 +48,25 @@
 
     \endlist
 
+    \section1 Cancel builds
+
     While the application is being built, the \inlineimage icons/build.png
     (\uicontrol Build) button changes to a \inlineimage icons/cancel-build.png
-    (\uicontrol {Cancel Build}) button. To cancel the build, select
+    (\uicontrol {Cancel Build}) button. To cancel the build:
-    the button, press \key {Alt+Backspace}, or select \uicontrol Build >
-    \uicontrol {Cancel Build}.
 
-    If you selected a build command and
+    \list
-    decide you would also like to run the application, you can select the
+        \li Select \inlineimage icons/cancel-build.png.
-    \uicontrol Run button to schedule running the project after building is done.
+        \li Press \key {Alt+Backspace}.
+        \li Go to \uicontrol Build > \uicontrol {Cancel Build}.
+    \endlist
 
-    For more information on the options you have, see
+    If you selected a build command and now would also like to run the
-    \l{Specifying Build Settings}.
+    application, select the \uicontrol Run button to schedule running
+    the project after building is done.
 
-    \section1 Additional Build Commands
+    \section1 Build projects in several configurations
 
-    The \uicontrol Build menu has additional commands for building,
+    Go to \uicontrol Build to build, rebuild, and clean projects.
-    rebuilding, and cleaning projects.
 
     To build the current project in all its configurations, that
     is, for all build configurations in all enabled kits, select
@@ -74,20 +79,24 @@
     To build all open projects in all their configurations, select
     \uicontrol {Build All Projects for All Configurations}.
 
+    \section1 Build files or subprojects
+
     To quickly check the compile output for changes that you made in one file or
-    subproject, you can use the \uicontrol Build menu commands to build a file or
+    subproject, use the \uicontrol Build menu commands to build it. The available
-    subproject. The available build menu commands depend on the build system
+    build menu commands depend on the build system you selected for the project:
-    you selected for the project: CMake, qmake, or Qbs.
+    CMake, qmake, or Qbs.
 
     Select \uicontrol {Build for Run Configuration} to
     build the executable that corresponds to the selected run configuration.
     You can also use the \c cm filter in the \l {Navigate with locator}
     {locator}.
 
-    To remove all build artifacts, select one of \uicontrol {Clean} menu commands.
+    \section1 Remove build artifacts
+
+    To remove all build artifacts, go to \uicontrol Build > \uicontrol {Clean}.
 
     To clean the build directory and then build the project, select
-    one of \uicontrol {Rebuild} menu commands.
+    \uicontrol {Rebuild}.
 
     To build and clean projects without dependencies, select the
     \uicontrol {Build Without Dependencies},
@@ -95,30 +104,23 @@
     \uicontrol {Clean Without Dependencies} options in the context menu in the
     \uicontrol Projects view.
 
-    To run qmake or CMake to regenerate build system files, select
+    \sa {Configure projects for building}, {Build and Run}{How To: Build and Run},
-    \uicontrol Build > \uicontrol {Run qmake} or \uicontrol {Run CMake}.
+    {Adding Docker Devices}, {Specifying Build Settings}
-
+*/
-    \section1 Building with CMake
+
-
+/*!
-    \QC automatically runs CMake when you make changes to \c {CMakeLists.txt}
+    \page creator-how-to-run-qmake-before-building.html
-    files. To disable this feature, select \preferences > \uicontrol CMake >
+    \previouspage creator-how-tos.html
-    \uicontrol General. Select the CMake executable to edit, and then deselect
+
-    the \uicontrol {Autorun CMake} check box.
+    \ingroup creator-how-to-build-with-qmake
-
+
-    \image qtcreator-preferences-cmake-tools.webp "Tools tab in CMake Preferences"
+    \title Run qmake before building
-
+
-    For more information, see \l {CMake}.
+    To prevent failures on incremental builds, always run qmake before building,
-
+    even though it takes more time. Go to \preferences > \uicontrol {Build & Run}
-    \section1 Building with qmake
+    > \uicontrol Qmake, and select \uicontrol {Run qmake on every build}.
-
+
-    To prevent failures on incremental builds, it might make sense
+    \image qtcreator-preferences-build-run-qmake.png {Build & Run Qmake Preferences}
-    to always run qmake before building, even though it means that
+
-    building will take more time. To enable this option, select \preferences >
+    \sa {Build and Run}{How To: Build and Run}, {qmake Build Configuration}
-    \uicontrol {Build & Run} > \uicontrol Qmake >
-    \uicontrol {Run qmake on every build}.
-
-    \image qtcreator-preferences-build-run-qmake.png "qmake tab in Build & Run Preferences"
-
-    \sa {Configure projects for building}, {Configure projects for running},
-    {qmake Build Configuration}
 */

doc/qtcreator/src/projects/creator-only/creator-projects-settings-build-qbs.qdoc

@@ -22,7 +22,7 @@
 
     In the \uicontrol {Tooltip in target selector} field, you can enter text
     that is displayed as a tooltip when you hover the mouse over the build
-    configuration in the \l{Building for Multiple Platforms}{kit selector}.
+    configuration in the \l{Build for many platforms}{kit selector}.
 
     You can enter a name for the build configuration in the
     \uicontrol {Configuration name} field.

doc/qtcreator/src/qtcreator-toc.qdoc

@@ -35,7 +35,7 @@
             \endlist
             \li \l{Configuring the Editor}
         \endlist
-        \li \l{Building and Running}
+        \li \l{Running on Devices}
         \list
             \li \l{Validating with Target Hardware}
             \list
@@ -43,7 +43,6 @@
                 \li \l{Previewing on Devices}
                 \li \l{Previewing in Browsers}
             \endlist
-            \li \l{Building for Multiple Platforms}
             \li \l{Deploying to Devices}
             \list
                 \li \l{Deploying to Android}

doc/qtcreator/src/qtcreator.qdoc

@@ -46,10 +46,9 @@
                     \li \l{Writing Code}
                     \li \l{Configuring the Editor}
                 \endlist
-            \li \b {\l{Building and Running}}
+            \li \b {\l{Running on Devices}}
                 \list
                     \li \l{Validating with Target Hardware}
-                    \li \l{Building for Multiple Platforms}
                     \li \l{Deploying to Devices}
                     \li \l{Connecting Devices}
                 \endlist

doc/qtcreator/src/user-interface/creator-ui.qdoc

@@ -50,7 +50,7 @@
         \li \inlineimage numbers/05.png
         \li Build button
         \li Build the application using the selected kit.
-        \li \l{Building for Multiple Platforms}
+        \li \l{Build for many platforms}
     \row
         \li \inlineimage numbers/06.png
         \li Locator

doc/qtcreator/src/webassembly/creator-webassembly.qdoc

@@ -109,7 +109,7 @@
     \endlist
 
     You can now build Qt applications in WebAssembly format and run them in
-    a web browser as described in \l {Building for Multiple Platforms} and
+    a web browser as described in \l {Build for many platforms} and
     \l{Run on many platforms}.
 
     \sa {Enable and disable plugins}