1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
|
/****************************************************************************
**
** Copyright (C) 2016 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-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
OS X).
\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 OS X).
\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 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 OS X).
\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 OS X).
\section1 Deploying CMake Projects to Embedded Linux Devices
\QC cannot extract files to be installed from a CMake project, and
therefore, only executable targets are automatically added to deployment
files. You must specify all other files in the \c {QtCreatorDeployment.txt}
file that you create and place in either the root directory of the CMake
project or the build directory of the active build configuration.
Currently, \QC first checks the root directory and only if no
\c {QtCreatorDeployment.txt} exists it checks the active build directory.
Use the following syntax in the file:
\code
<deployment/prefix>
<relative/source/file1>:<relative/destination/dir1>
...
<relative/source/filen>:<relative/destination/dirn>
\endcode
Where:
\list
\li \c {<deployment/prefix>} is the (absolute) path prefix to where
files are copied on the remote machine.
\li \c {<relative/source/file>} is the file path relative to the CMake
project root. No directories or wildcards are allowed in this
value.
\li \c {<relative/destination/dir>} is the destination directory path
relative to \c {deployment/prefix}.
\endlist
To automate the creation of \c {QtCreatorDeployment.txt} file:
\list 1
\li Define the following macros in the top level \c {CMakeLists.txt}
file:
\code
file(WRITE "${CMAKE_SOURCE_DIR}/QtCreatorDeployment.txt" "<deployment/prefix>\n")
macro(add_deployment_file SRC DEST)
file(RELATIVE_PATH path ${CMAKE_SOURCE_DIR} ${CMAKE_CURRENT_SOURCE_DIR})
file(APPEND "${CMAKE_SOURCE_DIR}/QtCreatorDeployment.txt" "${path}/${SRC}:${DEST}\n")
endmacro()
macro(add_deployment_directory SRC DEST)
file(GLOB_RECURSE files RELATIVE "${CMAKE_CURRENT_SOURCE_DIR}" "${SRC}/*")
foreach(filename ${files})
get_filename_component(path ${filename} PATH)
add_deployment_file("${filename}" "${DEST}/${path}")
endforeach(filename)
endmacro()
\endcode
\li Use \c {add_deployment_file(<file/name>)} to add files and
\c {add_deployment_directory(<folder/name>)} to add directories
(including subdirectories) to the \c QtCreatorDeployment.txt file.
\li Re-run \c cmake after you add or remove files using the macros.
\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.
*/
|
