Doc: Move CMake information into the generic sections

Describe build, run, and deployment settings for all build systems
in the generic topics (using .qdocinc files) and keep only configuration
in the CMake specific topic.

Change-Id: I334d7488b32aba90ee1e4ca898a65438b9d304a4
Reviewed-by: Tobias Hunger <tobias.hunger@qt.io>

doc/src/cmake/creator-projects-cmake-building.qdocinc

+/****************************************************************************
+**
+** Copyright (C) 2017 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the Qt Creator documentation.
+**
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+**
+****************************************************************************/
+
+// **********************************************************************
+// NOTE: the sections are not ordered by their logical order to avoid
+// reshuffling the file each time the index order changes (i.e., often).
+// Run the fixnavi.pl script to adjust the links to the index order.
+// **********************************************************************
+
+/*!
+//! [cmake build configuration]
+
+    \section2 CMake Build Configuration
+
+    \image qtcreator-cmake-build-settings.png
+
+    To view all settings, select the \uicontrol Advanced check box.
+
+    To modify the value of a build setting, select it, and then select
+    \uicontrol Edit. The new value is displayed in italics until you save the
+    changes by selecting \uicontrol {Apply Configuration Changes}. Any
+    configuration change might trigger a follow-up configuration change, so keep
+    saving until no more values are displayed in italics.
+
+
+//! [cmake build configuration]
+
+
+//! [cmake build steps]
+
+    \section2 CMake Build Steps
+
+    \QC builds CMake projects by running \c {cmake . --build}, which then runs
+    run whatever is needed based on how the project was configured: \c make,
+    \c mingw32-make, \c nmake, or \c ninja, for example.
+
+    You can add arguments and targets for the build command in
+    \uicontrol {Build Steps}.
+
+    \image qtcreator-cmake-build-steps.png
+
+//! [cmake build steps]
+
+
+//! [cmake clean steps]
+
+    \section2 CMake Clean Steps
+
+    When building with CMake, you can add arguments and targets for the clean
+    command in \uicontrol {Clean Steps}.
+
+    \image qtcreator-cmake-clean-steps.png
+
+    The build errors and warnings are parsed and displayed in the
+    \uicontrol Issues output pane.
+
+//! [cmake clean steps]
+*/

doc/src/projects/creator-projects-cmake.qdoc → doc/src/cmake/creator-projects-cmake-deploying.qdocinc

 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2017 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the Qt Creator documentation.
@@ -30,196 +30,7 @@
 // **********************************************************************
 
 /*!
-    \contentspage {Qt Creator Manual}
-    \previouspage creator-project-other.html
-    \page creator-project-cmake.html
-    \nextpage creator-project-qbs.html
-
-    \title Setting Up a CMake Project
-
-    CMake is an alternative to qmake for automating the generation of build
-    configurations. It controls the software compilation process by using simple
-    configuration files, called \c {CMakeLists.txt} files. CMake generates
-    native build configurations and workspaces that you can use in the compiler
-    environment of your choice.
-
-    \QC automatically detects the CMake executable specified in the \c PATH.
-    You can add paths to other CMake executables and use them in different
-    build and run \l{glossary-buildandrun-kit}{kits}.
-
-    \QC automatically runs CMake to regenerate makefiles when you edit a
-    \c CMakeLists.txt configuration file in a project. If the project uses
-    several configuration files, you can disable the automatic generation of
-    makefiles by selecting \uicontrol Tools > \uicontrol Options >
-    \uicontrol {Build & Run} > \uicontrol CMake. Makefiles are automatically
-    regenerated when you build the project.
-
-    \section1 Adding CMake Tools
-
-    \QC supports CMake version 3.0, or later. For best results you should use
-    CMake version 3.3.2 or later. Earlier versions provide less information
-    to the code model, which will then fail to resolve includes and defines.
-
-    To specify paths to CMake executables and to add them to kits:
-
-    \list 1
-
-        \li Select \uicontrol Tools > \uicontrol Options >
-            \uicontrol {Build & Run} > \uicontrol CMake > \uicontrol Add.
-
-            \image qtcreator-cmakeexecutable.png
-
-        \li In the \uicontrol Name field, specify a name for the tool.
-
-        \li In the \uicontrol Path field, specify the path to the CMake
-            executable.
-
-        \li Deselect the \uicontrol {Autorun CMake} check box to prevent \QC
-            from running CMake when you make changes to \c {CMakeLists.txt}
-            files.
-
-        \li Select \uicontrol Apply to save your changes.
-
-        \li 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:
-
-            \image qtcreator-kits.png
-
-            For more information, see \l {Adding Kits}.
-
-    \endlist
-
-    \section1 Creating CMake Projects
-
-    To create a CMake project:
-
-    \list 1
-
-        \li Select \uicontrol File > \uicontrol {New File or Project} >
-            \uicontrol {Non-Qt Project} > \uicontrol {Plain C Application} or
-            \uicontrol {Plain C++ Application} > \uicontrol Choose.
-
-        \li In the \uicontrol Name field, enter a name for the project.
-
-        \li In the \uicontrol {Create in} field, enter the path for the project
-            files, and then select \uicontrol Next (or \uicontrol Continue on
-            \macos).
-
-        \li In the \uicontrol {Build system} field, select \uicontrol CMake, and
-            then select \uicontrol Next.
-
-        \li Select CMake kits for the platforms that you want to build the
-            application for, and then select \uicontrol Next.
-
-        \li Review the project settings, and click \uicontrol{Finish} (or
-            \uicontrol Done on \macos).
-
-        \li Select \uicontrol {Run CMake} to generate a .cbp file.
-
-            \image qtcreator-cmake-run-cmake.png
-
-            Some projects require command line arguments to the initial CMake
-            call. CMake will remember the arguments during subsequent calls.
-
-    \endlist
-
-    \QC generates a \c {main.cpp} and \c {CMakeLists.txt} file that you can
-    modify in the \uicontrol Edit mode.
-
-    \section1 Opening CMake Projects
-
-    To open an existing CMake project:
-
-    \list 1
-
-        \li Select \uicontrol File > \uicontrol {Open File or Project}.
-
-        \li Select the \c {CMakeLists.txt} file from your CMake project.
-
-        \li Select a kit that is configured to use CMake for building the
-            project.
-
-        \li In \uicontrol Projects, right-click the project name to open the
-            context menu, and then select \uicontrol {Run CMake} to have the
-            project contents listed in the view.
-
-    \endlist
-
-    \section1 Editing CMake Configuration Files
-
-    To open a CMakeLists.txt file for editing, right-click it in the
-    \uicontrol Projects view and select \uicontrol {Open with} >
-    \uicontrol {CMake Editor}.
-
-    The following features are supported:
-
-    \list
-
-        \li Pressing \key F2 when the cursor is on a filename to open the file
-
-        \li Keyword completion
-
-        \li Code completion
-
-        \li Auto-indentation
-
-        \li Matching parentheses and quotes
-
-    \endlist
-
-    \section1 Building CMake Projects
-
-    To build CMake projects, select \uicontrol {Build Project} or press
-    \key Ctrl+B (or \key Cmd+B on \macos).
-
-    \QC builds CMake projects by running \c make, \c mingw32-make, \c nmake, or
-    \c ninja depending on the selected kit.
-
-    By default, \QC uses the \uicontrol Default \l{glossary-build-config}
-    {build configuration}. You can select another build configuration in
-    \uicontrol Projects > \uicontrol {Build Settings} >
-    \uicontrol {Edit build configuration}. In addition to
-    debug and release build configurations, you can create a release build that
-    contains debug information or a release build with the smallest possible
-    size.
-
-    \image qtcreator-cmake-build-settings.png
-
-    In the \uicontrol {Build directory} field, you can specify the directory in
-    which the project is built (\l{glossary-shadow-build}{shadow build}).
-
-    To view all settings, select the \uicontrol Advanced check box.
-
-    To modify the value of a build setting, select it, and then select
-    \uicontrol Edit. The new value is displayed in italics until you save the
-    changes by selecting \uicontrol {Apply Configuration Changes}. Any
-    configuration change might trigger a follow-up configuration change, so keep
-    saving until no more values are displayed in italics.
-
-    You can add arguments and targets for the build command in
-    \uicontrol {Build Steps}.
-
-    \image qtcreator-cmake-build-steps.png
-
-    You can add arguments and targets for the clean command in
-    \uicontrol {Clean Steps}.
-
-    \image qtcreator-cmake-clean-steps.png
-
-    The build errors and warnings are parsed and displayed in the
-    \uicontrol Issues output pane.
-
-    \section1 Running CMake Projects
-
-    \QC automatically adds \uicontrol {Run Configurations} for all targets
-    specified in the CMake project file.
-
-    \image qtcreator-cmake-run-settings.png
-
-    To run CMake projects, select \uicontrol Run or press \key Ctrl+R (or
-    \key Cmd+R on \macos).
+//! [cmake deploying embedded]
 
     \section1 Deploying CMake Projects to Embedded Linux Devices
 
@@ -288,20 +99,5 @@
 
     \endlist
 
-    \section1 Adding External Libraries to CMake Projects
-
-    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()}
-    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 {FindFoo.cmake} file. For more information, see
-    \l{http://vtk.org/Wiki/CMake_FAQ#Writing_FindXXX.cmake_files}{CMake FAQ}.
-
-    Syntax completion and highlighting work once your project successfully
-    builds and links against the external library.
-
+//! [cmake deploying embedded]
 */

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

+/****************************************************************************
+**
+** Copyright (C) 2017 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the Qt Creator documentation.
+**
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+**
+****************************************************************************/
+
+// **********************************************************************
+// NOTE: the sections are not ordered by their logical order to avoid
+// reshuffling the file each time the index order changes (i.e., often).
+// Run the fixnavi.pl script to adjust the links to the index order.
+// **********************************************************************
+
+/*!
+    \contentspage {Qt Creator Manual}
+    \previouspage creator-building-targets.html
+    \page creator-project-cmake.html
+    \nextpage creator-project-qbs.html
+
+    \title Setting Up CMake
+
+    CMake automates the configuration of build systems. It controls the software
+    compilation process by using simple
+    configuration files, called \c {CMakeLists.txt} files. CMake generates
+    native build configurations and workspaces that you can use in the compiler
+    environment of your choice.
+
+    \QC automatically detects the CMake executable specified in the \c PATH.
+    You can add paths to other CMake executables and use them in different
+    build and run \l{glossary-buildandrun-kit}{kits}.
+
+    \QC automatically runs CMake to refresh project information when you edit
+    a \c CMakeLists.txt configuration file in a project. Project information is
+    also automatically refreshed when you build the project.
+
+    \section1 Adding CMake Tools
+
+    \QC supports CMake version 3.0, or later. For best results you should use
+    CMake version 3.7.2 with server-mode support, or later. Earlier versions
+    provide less information to the code model, which will then fail to resolve
+    includes and defines.
+
+    To specify paths to CMake executables:
+
+    \list 1
+
+        \li Select \uicontrol Tools > \uicontrol Options >
+            \uicontrol {Build & Run} > \uicontrol CMake > \uicontrol Add.
+
+            \image qtcreator-cmakeexecutable.png
+
+        \li In the \uicontrol Name field, specify a name for the tool.
+
+        \li In the \uicontrol Path field, specify the path to the CMake
+            executable.
+
+        \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.
+
+    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:
+
+    \image qtcreator-kits.png
+
+    For more information, see \l {Adding Kits}.
+
+    \section1 Editing CMake Configuration Files
+
+    To open a CMakeLists.txt file for editing, right-click it in the
+    \uicontrol Projects view and select \uicontrol {Open with} >
+    \uicontrol {CMake Editor}.
+
+    The following features are supported:
+
+    \list
+
+        \li Pressing \key F2 when the cursor is on a filename to open the file
+
+        \li Keyword completion
+
+        \li Code completion
+
+        \li Auto-indentation
+
+        \li Matching parentheses and quotes
+
+    \endlist
+
+   \section1 Adding External Libraries to CMake Projects
+
+    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()}
+    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 {FindFoo.cmake} file. For more information, see
+    \l{http://vtk.org/Wiki/CMake_FAQ#Writing_FindXXX.cmake_files}{CMake FAQ}.
+
+    Syntax completion and highlighting work once your project successfully
+    builds and links against the external library.
+
+    \section1 Related Topics
+
+    \list
+        \li \l {Opening Projects}
+        \li \l {Specifying Build Settings}
+        \li \l {Specifying Run Settings}
+        \li \l {Deploying CMake Projects to Embedded Linux Devices}
+    \endlist
+*/

doc/src/linux-mobile/creator-deployment-embedded-linux.qdoc

 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2017 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the Qt Creator documentation.
@@ -101,4 +101,6 @@
     support will crash when an SFTP upload is being attempted. This is not a bug
     in \QC.
 
+    \include creator-projects-cmake-deploying.qdocinc cmake deploying embedded
+
 */

doc/src/projects/creator-projects-opening.qdoc

+
 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2017 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the Qt Creator documentation.
@@ -76,8 +77,10 @@
     \list 1
 
         \li Select \uicontrol File > \uicontrol {Open File or Project}
-            (\key Ctrl+O or \key Cmd+O on \macos) and select the project to
-            open.
+            (\key Ctrl+O or \key Cmd+O on \macos) and select the project file
+            for the project to open: \e {.pro} (qmake), \e {CMakeLists.txt}
+            (CMake), \e {.qbs} (Qbs), or \e {Makefile.am} (Autotools,
+            experimental).
 
         \li In the \uicontrol {Configure Project} tab, select kits for building and running your
             project, and click \uicontrol {Configure Project}.

doc/src/projects/creator-projects-other.qdoc

 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2017 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the Qt Creator documentation.
@@ -37,14 +37,14 @@
 
     \title Using Other Build Systems
 
-    Most \QC project wizards create projects that are configured to use qmake. Most
-    of the instructions in this manual apply to using qmake. However, \QC is
-    also integrated to other build systems, as described in the the following
-    sections:
+    Most \QC project wizards enable you to choose the build system to use for
+    building the project: qmake, CMake, or Qbs. qmake is installed and
+    configured when you install Qt. To use one of the other supported build
+    systems, you need to set it up, as described in the the following sections:
 
     \list
 
-        \li \l{Setting Up a CMake Project}
+        \li \l{Setting Up CMake}
 
             CMake is an alternative to qmake for automating the generation of
             build configurations.

doc/src/projects/creator-projects-settings-build.qdoc

 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2017 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the Qt Creator documentation.
@@ -59,6 +59,8 @@
     Select the build configuration to edit in the
     \uicontrol {Edit build configuration} field.
 
+    \section2 qmake Build Configuration
+
     \image qtcreator-projectpane.png
 
     By default, \QC builds projects in a separate directory from the source
@@ -73,6 +75,8 @@
     \uicontrol General, and enter a period (.) in the
     \uicontrol {Default build directory} field.
 
+    \include creator-projects-cmake-building.qdocinc cmake build configuration
+
     \section1 Starting External Processes
 
     \QC executes external processes to accomplish tasks such as building
@@ -140,8 +144,12 @@
 
     \section1 Build Steps
 
-    The build system of \QC is built on qmake and make. In \uicontrol{Build Steps} you
-    can change the settings for qmake and make. \QC runs the make command using
+    In \uicontrol{Build Steps} you can change the settings for the build system
+    selected for building the project: qmake, CMake, or Qbs.
+
+    \section2 qmake Build Steps
+
+    \QC builds qmake projects by running the \c make or \c nmake command from
     the Qt version defined for the current build configuration.
 
     \image qtcreator-build-steps.png "Build steps"
@@ -165,6 +173,7 @@
 
     \note For more information about the build steps when using Qbs, see
     \l{Building Applications with Qbs}.
+    \include creator-projects-cmake-building.qdocinc cmake build steps
 
     \section2 Adding Custom Build Steps
 
@@ -191,7 +200,7 @@
 
     \image qtcreator-clean-steps.png "Clean steps"
 
-    You can define the cleaning steps for your builds in the \uicontrol{Clean Steps}:
+    You can define the cleaning steps for your builds in the \uicontrol{Clean Steps}.
 
     \list
 
@@ -210,6 +219,7 @@
 
     \note For more information about the cleaning steps when using Qbs, see
     \l{Building Applications with Qbs}.
+    \include creator-projects-cmake-building.qdocinc cmake clean steps
 
     \section1 Build Environment
 

doc/src/projects/creator-projects-settings-run.qdoc

 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2017 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the Qt Creator documentation.
@@ -46,12 +46,13 @@
     Click \uicontrol Add to add run settings for a project and \uicontrol Remove to remove
     the current settings.
 
-    \section1 Specifying Run Settings for qmake Projects
-
     The run configurations for qmake projects derive their executable from the
     parsed .pro files. For more information on how the commands are constructed,
     see \l{Starting External Processes}.
 
+    \QC automatically adds run configurations for all targets specified in the
+    CMake project file, \c {CMakeLists.txt}.
+
     \section2 Creating Run Configurations for Subprojects
 
     To prevent \QC from automatically creating run configurations for SUBDIRS