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) 2024 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page creator-build-settings-cmake.html
\previouspage creator-reference.html
\ingroup creator-reference-build-configurations
\title CMake Build Configuration
\brief Settings for building applications with CMake.
Specify build settings for the selected \l{glossary-buildandrun-kit}{kit} in
\uicontrol Projects > \uicontrol {Build & Run} > \uicontrol Build >
\uicontrol {Build Settings}.
Configuring medium-sized to large CMake projects in \QC can be a
challenge due to the number of variables that you need to pass to
CMake to configure the project correctly. To make this easier,
\QC creates an initial configuration for you based on the kit
settings and displays it in \uicontrol {Initial Configuration} in
the \uicontrol {Build Settings} of the project.
Or, you can use CMake presets to configure CMake.
The \uicontrol Configure field displays the effective CMake call that
\QC constructs using the values of the \uicontrol {Build directory} and
\uicontrol {Build type} fields.
\image qtcreator-build-settings-cmake-configure.webp {CMake configure command}
You can specify additional CMake options, such as \c {--find-debug},
\c {--trace-expand}, or \c {--warn-uninitialized}, in
\uicontrol {Additional CMake options}. For more information about
the options, click the link in the field name or see \l{CMake: cmake(1)}.
Select \uicontrol {Kit Configuration} to edit the CMake settings for the
build and run kit selected for the project.
You can use \l{CMake Presets}{CMake presets} files to specify common
configure, build, and test options and share them with others.
\section1 Initial Configuration
\image qtcreator-build-settings-cmake-initial.webp {Initial CMake configuration}
\uicontrol {Initial Configuration} lists the variables that \QC uses to
configure the CMake project for the first time. It shows the default values
that come from the kit's CMake configuration in italics. \QC saves the
initial configuration list of variables in the project's source
directory as the \e CMakeLists.txt.user file.
\section1 Current Configuration
\image qtcreator-build-settings-cmake-current.webp {Current CMake configuration}
\uicontrol {Current Configuration} lists the CMake variables in the
\c cmake-file-api JSON export in the \c {.cmake/api/v1/reply} directory.
It shows the variables that come from the initial configuration in italics
and mismatched values in red.
After selecting the \uicontrol {Run CMake} button, you can view and
change the actual values of the variables that \QC passes to CMake.
The \uicontrol Key column lists variable names, and the \uicontrol Value
column lists their current values. For more information about the variables,
select \uicontrol Help in the context menu or see
\l{CMake: cmake-variables(7)}. For more information about Qt-specific
variables, see \l{CMake Variable Reference}.
\section1 Multi-Config Support
\QC supports
\l{https://cmake.org/cmake/help/latest/prop_gbl/GENERATOR_IS_MULTI_CONFIG.html}
{Multi-config generators}, such as Xcode, Visual Studio, and Ninja
Multi-Config. This means that you need to configure CMake only once, have
only one build directory, and can switch between build types faster.
However, this means that \QC can no longer simply parse the first CMake
file-api JSON export. Therefore, the value of the \uicontrol {Build type}
field must match that of the \c CMAKE_BUILD_TYPE variable for the single
configuration generators (Ninja, Makefile) to determine, which generator
to use.
When developing with Qt 6 for iOS, only the Xcode generator is supported.
\section1 Modifying Variable Values
You can view and edit the actual values of the variables that
are passed to CMake in \uicontrol {Initial Configuration} or
\uicontrol {Current Configuration}.
\image qtcreator-build-settings-cmake-current.webp {Current CMake configuration}
You can select several variables and apply an action to them. To clear
the selection, click anywhere in the view.
To batch edit variable values, select \uicontrol {Batch Edit}.
\image qtcreator-edit-cmake-configuration.webp {Edit CMake Configuration dialog}
To build using the current configuration, select \uicontrol {Run CMake}.
While building, the button text changes to \uicontrol {Stop CMake}. Select
the button to cancel the current build.
\section2 Adding Variables
To add variables, select \uicontrol Add, and then select the type of
the variable that you are adding: \uicontrol Boolean, \uicontrol String,
\uicontrol Directory, or \uicontrol File.
To change the type of the selected variable, right-click the
variable name in the \uicontrol Key column, and then select
\uicontrol {Force to bool}, \uicontrol {Force to file},
\uicontrol {Force to directory}, or \uicontrol {Force to string}
in the context menu.
To copy the name or value of the selected variable to the clipboard,
select \uicontrol Copy in the context menu.
\section2 Changing Variable Values
To change the value of a variable, double-click it, or select it,
and then select \uicontrol Edit. If the initial, current, and kit
configuration get out of sync, select \uicontrol {Apply Kit Value} or
\uicontrol {Apply Initial Configuration Value} in the context menu in
\uicontrol {Initial Configuration} or \uicontrol {Current Configuration}.
To reset all the changes that you made, select \uicontrol Reset.
The variable 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 variables that are
not part of the initial CMake configuration are also removed.
To reconfigure a project using the changed variable values,
select \uicontrol Build > \uicontrol {Clear CMake Configuration}, which
removes the CMakeCache.txt file. This enables you to do a full rebuild.
\section2 Removing Variables
To remove the selected variables, select \uicontrol Unset. To undo
the removal, select \uicontrol Set.
\section2 Viewing Advanced Variables
To view all variables, select the \uicontrol Advanced check box.
To view all variables by default, go to \preferences > \uicontrol CMake >
\uicontrol General and select \uicontrol {Show advanced options by default}.
\image qtcreator-preferences-cmake-general.webp "General tab in CMake Preferences"
\section1 Re-configuring with Initial Variables
To reset CMake variables to the initial ones, select
\uicontrol {Re-configure with Initial Variables} in
\uicontrol {Initial Configuration}. \QC deletes the current CMake
configuration and runs CMake. The initial configuration values are
stored in the CMakeLists.txt.user file, so deleting a build directory
does not delete the initial configuration.
To be asked before \QC resets the changes, go to \preferences >
\uicontrol CMake > \uicontrol General and select
\uicontrol {Ask before re-configuring with initial parameters}.
\section1 Viewing CMake Output
Output from CMake is displayed next to the \uicontrol {Build Settings} and
\uicontrol {Run Settings} panes in the \uicontrol Projects mode.
\image qtcreator-build-cmake-output.png {CMake output in Projects mode}
To clear the search results, select the \inlineimage icons/clean_pane_small.png
(\uicontrol Clear) button.
You can enter a string in the \uicontrol Filter field to filter output.
To specify filtering options, select the
\inlineimage icons/magnifier.png {Filtering options menu}
button. You can filter output by using regular expressions or
case-sensitivity. Select \uicontrol {Show Non-matching Lines} to
hide the lines that match the filter.
Press \key {Ctrl+F} to \l{Search in current file}{search} for a string in
the output.
To increase or decrease the output text size, select \inlineimage icons/plus.png
(\uicontrol {Zoom In}) or \inlineimage icons/minus.png
(\uicontrol {Zoom Out}), or press \key Ctrl++ or \key Ctrl+-.
To hide the output, select the \inlineimage icons/rightsidebaricon.png
(\uicontrol {Hide Right Sidebar}) button or press \key {Alt+Shift+0}.
\section1 CLICOLOR_FORCE Environment Variable
\QC sets the environment variable \c CLICOLOR_FORCE to \e 1 to show
ANSI-colored output for CMake. This might affect the process output.
If the output looks incorrect or different from earlier \QC versions, try
setting \c CLICOLOR_FORCE to \e 0 in \uicontrol {Use Build Environment}.
\image qtcreator-build-configuration-set-clicolor-force.webp {Build Environment with CLICOLOR_FORCE set}
\section1 Using Junction Points on Windows
To overcome issues with long paths on Windows, create and use
\l{https://learn.microsoft.com/en-us/sysinternals/downloads/junction}
{junction points} for the source and build directories. At a junction point,
a directory serves as an alias to another directory on the computer.
To use the junction points for CMake configure, build, and install
operations, go to \preferences > \uicontrol CMake > \uicontrol General and
select \uicontrol {Use junctions for CMake configuration and build operations}.
\image qtcreator-preferences-cmake-general.webp {CMake General preferences}
\QC stores junction points in \c {C:\ProgramData\QtCreator\Links}. To use
another path, set it as the value of the \c QTC_CMAKE_JUNCTIONS_DIR
environment variable.
Set the \c QTC_CMAKE_JUNCTIONS_HASH_LENGTH environment variable to shorten
the MD5 hash key length from the default length value of 32.
\section1 CMake Build Steps
\QC builds CMake projects by running \c {cmake . --build}, which then runs
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. Multi-config generators are also supported.
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.webp {CMake build steps}
\note While the other CMake generators are installed together with Qt,
you usually need to install Ninja yourself.
To install the application to a staging directory when cross-compiling,
select the \uicontrol {Stage for installation} check box and specify
the path to a directory in the \uicontrol {Staging directory} field.
The packaging tool constructs the package from the contents of the
directory.
\section1 Using Ninja as a CMake Generator
To use \l {https://ninja-build.org/}{Ninja} with CMake, you must install it
and select it as the CMake generator in the build and run kit:
\list 1
\li Install Ninja.
\li Add the path to the Ninja executable to the value of the PATH system
variable.
\li In \uicontrol Projects > \uicontrol {Build & Run} > \uicontrol Build
> \uicontrol {Build Settings}, select \uicontrol {Kit Configuration}.
\image qtcreator-cmake-kit-configuration.png {Kit CMake Configuration dialog}
\li Select \uicontrol Change next to the \uicontrol {CMake generator}
field to open the \uicontrol {CMake Generator} dialog.
\image qtcreator-cmake-generator.webp {CMake Generator dialog}
\li In \uicontrol Generator, select \uicontrol Ninja.
\li Select \uicontrol OK to save your changes and close the dialog.
\li Select \uicontrol Close to close the
\uicontrol {Kit CMake Configuration} dialog
and return to \uicontrol {Build Settings}.
\endlist
\note To make sure that old build artifacts don't get in the way
the first time you build the project after the change, select
\uicontrol Build > \uicontrol {Rebuild Project}. This cleans up the
build directory and performs a new build.
\section1 Using CMake with Package Managers
To automatically set up the \l {Conan Package Manager}{Conan} or
\l {vcpkg Package Manager}{vcpkg} package manager for use with CMake:
\list 1
\li Create a CMake script file that installs dependencies from a
\c conanfile.txt, \c conanfile.py, or \c vcpkg.json file in
the project source directory.
\li Set the path to the script as the value of the
\c CMAKE_PROJECT_INCLUDE_BEFORE variable.
\li Go to \preferences > \uicontrol CMake > \uicontrol General and select
\uicontrol {Package manager auto setup}.
\endlist
\section1 QTC_RUN Environment Variable
\QC sets the environment variable \c QTC_RUN to \c 1 when executing
the \c cmake process.
This enables the CMake code to detect if it's being executed from \QC.
\section1 CMake 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.webp {CMake clean steps}
The build errors and warnings are parsed and displayed in \l Issues.
\sa {Activate kits for a project}, {Add custom output parsers},
{Configure projects for building}, {Configure projects for running},
{Open projects}, {CMake}
*/
|
