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
|
/****************************************************************************
**
** Copyright (C) 2018 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 index.html
\previouspage creator-debuggers.html
\page creator-build-settings.html
\nextpage creator-run-settings.html
\title Specifying Build Settings
Different build configurations allow you to quickly switch between
different build settings. By default, \QC creates \e debug, \e release, and
\e profile build configurations. A debug build contains additional
debug symbols that you need for debugging the application but that you
can leave out from the release version. Generally, you use the debug
configuration for testing and the release configuration for creating
the final installation file. A profile configuration is an optimized release
build that is delivered with separate debug information. It is best suited
for analyzing applications.
You specify build settings in the \uicontrol Projects mode.
To add a new build configuration, click \uicontrol Add and select the type of
configuration you would like to add. You can add as many build
configurations as you need.
To delete the build configuration currently selected, click \uicontrol Remove.
\section1 Editing Build Configurations
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
directory, as \l{glossary-shadow-build} {shadow builds}. This keeps the
files generated for each \l{glossary-buildandrun-kit}{build and run kit} separate.
If you only build and run with a single \l{glossary-buildandrun-kit}{kit},
you can deselect the \uicontrol {Shadow build}
checkbox.
To make in-source builds the default option for all projects, select
\uicontrol Tools > \uicontrol Options > \uicontrol {Build & Run} >
\uicontrol General, and enter a period (.) in the
\uicontrol {Default build directory} field.
You can create separate versions of project files to keep platform-dependent
code separate. You can use qmake \l{Adding Platform Specific Source Files}
{scopes} to select the file to process depending on which platform qmake is
run on.
\include creator-projects-cmake-building.qdocinc cmake build configuration
\section1 Starting External Processes
\QC executes external processes to accomplish tasks such as building
and running applications. To execute the processes, \QC uses shell
commands that are native to the system. It constructs the commands from
an executable name and optional command line arguments.
The executable name is specified in the executable fields: \uicontrol qmake,
\uicontrol Make, \uicontrol Command, or \uicontrol Executable. It is either derived from the
project or specified manually. When you specify executables manually, you
can reference environment variables and \QC variables. However, no
quoting rules
apply.
You can specify command-line arguments in the arguments fields:
\uicontrol {Additional arguments}, \uicontrol {Command arguments},
\uicontrol {Make arguments}, \uicontrol Arguments, \uicontrol {Default Arguments},
or \uicontrol {Extra arguments}. You can create shell command lines
that can contain redirection and other advanced constructs. However, some
more complex use cases, such as piping test data into the application being
tested or grouping commands, are not supported because the value of the
\uicontrol Executable field is always placed first when constructing the command.
\section2 Using Environment Variables
You can use any environment variables as values in the fields. For a list
of variable names, click \uicontrol {Build Environment > Details} in the
\uicontrol {Build Settings}. Environment variables are referenced using the native
syntax: $VARNAME or ${VARNAME} on Unix and %VARNAME% on Windows.
\section2 Using Qt Creator Variables
You can use \QC variables in arguments, executable paths, and working
directories. The variables take care of quoting their expansions, so you do
not need to put them in quotes. Select the \inlineimage replace.png
(\uicontrol {Variables}) button in a field to select from a list of variables that
are available in a particular context.
The following syntax enables you to use environment variables as \QC
variables: %{Env:VARNAME}.
\QC uses pattern substitution when expanding variable names. To replace the
first match of \e pattern within \e variable with \e replacement, use:
\badcode
%{variable/pattern/replacement}
\endcode
To replace all matches of \e pattern within \e variable with \e replacement,
use:
\badcode
%{variable//pattern/replacement}
\endcode
The pattern can be a regular expression and the replacement can contain
backreferences. For example, if \c %{variable} is \c my123var, then
\c %{variable/(..)(\d+)/\2\1} is expanded to \c {123myvar}.
Instead of the forward slash, you can also use the pound sign (\c #) as
the substitution character. This can be helpful if the value is supposed
to be a file path, in which case forward slashes might get translated
to backslashes on Windows hosts.
To use the default value if the variable is not set, use:
\badcode
%{variable:-default}
\endcode
\section1 Build Steps
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"
To override the shell command that \QC constructs by default, disable or remove
the build step and add a custom build step that specifies another shell
command.
By default, \QC uses all the CPU cores available to achieve maximum build
parallelization. On Linux and \macos, you can specify the number of parallel
jobs to use for building in the \uicontrol {Parallel jobs} field. Select the
\uicontrol {Override MAKEFLAGS} check box to override existing MAKEFLAGS
variables.
To generate debug symbols also for applications compiled in release mode,
select the \uicontrol {Generate separate debug info} check box. For more
information, see \l{Using the Performance Analyzer}.
\section3 Compiling QML
Since Qt 5.11, you can compile QML source code into the final binary. This
improves the startup time of the application and eliminates the need to
deploy QML files together with the application. For more information, see
\l{Compiling QML Ahead of Time}.
\QC new project wizards create Qt Quick projects that can be compiled,
because they are set up to use the Qt Resource System. To compile Qt Quick
projects, select the \uicontrol {Enable Qt Quick Compiler} check box.
\note In earlier Qt versions, this was a commercial feature. For more
information, see \l{http://doc.qt.io/QtQuickCompiler/}{Qt Quick Compiler}.
\include creator-projects-cmake-building.qdocinc cmake build steps
\include creator-projects-settings-build-qbs.qdocinc qbs build steps
\section2 Adding Custom Build Steps
To add custom steps to the build settings, select \uicontrol {Add Build Step >
Custom Process Step}.
By default, custom steps are enabled. To disable a custom step, select
the \inlineimage buildstepdisable.png
(\uicontrol Disable) button.
\image qtcreator-build-steps-custom.png "Custom Process Step"
\section2 Executing Custom Commands
To execute custom commands when building for embedded devices, select
\uicontrol {Add Build Step} > \uicontrol {Custom Remote Command
(via adb shell)} (commercial only) and enter the command to execute.
\section1 Clean Steps
You can use the cleaning process to remove intermediate files. This process
might help you to fix obscure issues during the process of building a
project.
\image qtcreator-clean-steps.png "Clean steps"
You can define the cleaning steps for your builds in the \uicontrol{Clean Steps}.
\list
\li To add a clean step using make or a custom process, click
\uicontrol{Add Clean Step} and select the type of step you want to add.
By default, custom steps are enabled. To disable a custom step,
select the \uicontrol Disable button.
\li To remove a clean step, click \uicontrol{Remove Item}.
\li To change the order of steps, click \inlineimage arrowup.png
(\uicontrol {Move Up}) and \inlineimage arrowdown.png
(\uicontrol {Move Down}).
\endlist
\include creator-projects-cmake-building.qdocinc cmake clean steps
\include creator-projects-settings-build-qbs.qdocinc qbs clean steps
\section1 Build Environment
You can specify the environment you want to use for building in the
\uicontrol {Build Environment} section. By default, the environment in which \QC
was started is used and modified to include the Qt version.
Depending on the selected Qt version, \QC automatically sets the
necessary environment variables. You can edit existing environment
variables or add, reset and unset new variables based on your project
requirements.
\image qtcreator-build-environment.png "Build Environment"
\note The changes are stored in the local project specific \c{.pro.user}
file. Therefore, they are not suitable for sharing between developers or
development PCs. To share settings, incorporate them into the build system.
For example, if you use qmake, make the changes in the \c{.pro} file.
\section2 Batch Editing
To modify environment variable values for build or run environments,
select \uicontrol {Batch Edit} in the build or run settings and enter environment
variables in the \uicontrol {Edit Environment} dialog.
To remove a variable value from the environment, enter the variable name.
For example, \c TEST sets the value of the \c TEST variable empty when
building or running the project.
To add a variable value to the environment, enter the variable name and
value, separated by the equals sign. For example, the following line
prepends the \c /opt/bin folder to the existing PATH:
\list
\li On Windows: \c {PATH=C:\opt\bin;${PATH}}
\li On Linux: \c {PATH=/opt/bin:${PATH}}
\endlist
To add or remove several variables, place them on separate lines. The order
is important. If you remove a value on a line, you cannot refer to it on the
following lines. However, you can remove a value after you have referred to
it on an earlier line.
To temporarily disable a variable, add a hash character (#) to the beginning
of the line.
\section2 Clearing the System Environment
To build with a clean system environment, select the \uicontrol {Clear system
environment} check box. \QC discards the current environment, and
populates a clean system environment with the environment variables that the
compilers and tools need. Therefore, the environment is never totally empty,
even after you clear it.
*/
|
