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's avatarTobias Hunger <tobias.hunger@qt.io>
parent 06d62e36
/****************************************************************************
**
** 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]
*/
/****************************************************************************
**
** 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]
*/
/****************************************************************************
**
** 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
*/
/****************************************************************************
**
** 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
*/
/****************************************************************************
**
** 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}.
......
/****************************************************************************
**
** 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.
......
/****************************************************************************
**
** 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
......
/****************************************************************************
**
** 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
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment