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
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
|
// Copyright (C) 2020 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page configure-options.html
\title Qt Configure Options
\brief Configuring Qt's compile options.
\b configure is a command-line tool that supports you in building a custom
version of Qt from source. It's part of the main Qt source directory.
Since Qt 6, configure is a wrapper around \b{cmake}. CMake can also
be invoked directly. configure provides additional error checking and
compatibility with Qt 5.
This page discusses some of the configure options. For the full list of
options, enter the command \b{configure -h}.
\note Unless stated otherwise, the commands on this page are for the Linux
platforms. On \macos and Windows, the PATH and directory structure
are different, therefore the commands will vary. Also, on Windows systems,
the configure script is called configure.bat.
\section1 Configure Workflow
configure must be called in a working build environment where
CMake, compilers, and required build tools are readily available.
\l{Building Qt Sources} lists such dependencies per platform.
After setting up such an environment, the typical workflow is to create
a separate build directory, and then first run configure,
then build Qt, and then install Qt:
\badcode
~/qt-source/configure
cmake --build . --parallel
cmake --install .
\endcode
You might want to experiment with different configure flags, and therefore
run configure multiple times. Note that CMake caches configure options
and information about the environment in a file called CMakeCache.txt.
Delete this file when you want to start over without cached information.
\section1 Source, Build, and Install Directories
The \e source directory contains the source code that is obtained from
the source package or git repository. The \e build directory is where the
build-related files, such as build system files, object files, and other
intermediate files are stored. The \e install directory is where the
binaries and libraries are installed, for use either by the system or by
the application.
It's recommended to keep these directories separate by shadow-building and
using the \b -prefix option. This enables you to keep the Qt \e source tree
clean from the build artifacts and binaries, which are stored in a separate
directory. This method is very convenient if you want to have multiple
builds from the same source tree, but for different configurations. To
shadow-build, run configure from a separate directory:
\badcode
mkdir ~/qt-build
cd ~/qt-build
~/qt-source/configure -prefix /opt/Qt6
\endcode
Configuring with the -prefix option means that the Qt binaries and
libraries are installed into another directory, which is /opt/Qt6 in
this case.
\section1 Examples, Tests, and Tools
By default, configure only configures Qt's libraries and tools.
You can use \b{-make examples} or \b{-make tests} to also build
the examples or tests that come with Qt:
\badcode
~/qt-source/configure -make examples -make tests
\endcode
You can also configure Qt such that examples, tests, and tools are
configured, but not built by default. If you set the CMake variables
\b{QT_BUILD_EXAMPLES_BY_DEFAULT}, \b{QT_BUILD_TESTS_BY_DEFAULT}, and
\b{QT_BUILD_TOOLS_BY_DEFAULT} to OFF, the respective parts will not be
built by \c{cmake --build .}. Instead, CMake will generate individual targets
that you can then build individually.
Here we build Qt libraries and tools, but also the
\l{Getting Started Programming with Qt Widgets}{NotePad Example}:
\badcode
~/qt-source/configure -make examples -- -D QT_BUILD_EXAMPLES_BY_DEFAULT=OFF
cmake --build . --parallel
cmake --build . --parallel --target notepad
\endcode
\note The -developer-build option builds tests by default.
See also \l{Developer Builds} below.
\section1 Build Configurations
You can build Qt libraries and tools in various variants, each of them
optimized for a different use case.
\section2 Debug and Release Builds
\b{-release} tells the compiler to optimize the code, and not provide
additional debug symbols alongside Qt and its tools.
\b{-debug} skips some optimizations to make it easier to debug Qt
and its tools. This option also enables the generation of debug symbols that
let you inspect the code and state of the built libraries in a debugger.
Finally, \b{-debug-and-release} lets you build both a debug and release
variant of Qt libraries in one go. This is only supported if you configure
a build for Windows.
There are further options to tweak the configurations:
\list
\li \b{-force-debug-info}: Creates a release build with debug information.
\li \b{-separate-debug-info}: Extracts the debug information into a separate
file.
\li \b{-optimize-size}: Optimizes release builds for size instead of speed.
\endlist
\section2 Static and Shared Builds
Qt Modules can be built as separate libraries that an executable
links to and loads at start time (for Qt libraries), or runtime
(for Qt plugins). This is called a \e shared build and is the default
configuration on most platforms. The matching configure option is
\b{-dynamic}.
You can also build Qt such that an executable binary will include all Qt
modules it links to and all Qt plugins it needs. This is called a
\e static build and can be selected when configuring with the \b{-static}
option.
\section1 CMake Generators
When configuring, you can select a CMake generator. Note that CMake supports
generators that cannot be used with Qt. Therefore, configure
automatically selects a generator for you.
configure always uses the \b Ninja generator and build tool if a ninja
executable is available. Ninja is both cross-platform, feature-rich,
and performant, and recommended on all platforms. Use of other generators
might work, but is not officially supported.
\section1 Modules and Features
The Qt source code is organized in several top-level directories
called submodules, for example, \c{qtbase}, \c{qtdeclarative} or
\c{qtmultimedia}. Inside these submodules, you find the source code
for the different \l{All Modules}{Qt Modules}. \l{Qt Core}, \l{Qt
Quick}, and \l{Qt Multimedia} are examples of such Qt modules.
\note Many submodules (top-level source directories) have the same
name as the \l{All Modules}{Qt Modules} they implement, but this is
not always the case. For instance, \c{qtdeclarative} contains \l{Qt
Quick} and \l{Qt Qml}, and various related modules. Consult the
README.md file in the respective directories to get an overview.
Submodules can be explicitly included or excluded to limit build
times. Furthermore, each Qt module might have features that can also
be explicitly enabled or disabled.
\section2 Including and Excluding Qt Submodules
\c configure's \b -skip option is used to exclude submodules
(top-level source directories) from the Qt build. Excluding a
submodule excludes all \l{All Modules}{Qt Modules} inside that
submodule. The \c{qtwayland} submodule contains both the \l{Qt
Wayland Compositor} and the Qt Wayland QPA plugin. Specifying
\c{-skip qtwayland} as a configure option will therefore exclude
both \l{All Modules}{Qt Modules}.
\badcode
~/qt-source/configure -skip qtwayland
\endcode
\c configure's \b -submodules option can be used to configure a
build that only builds the listed submodules and their dependencies.
For example, by specifying the \c{qtmultimedia} submodule,
\l{Qt Multimedia} and all its dependencies will be included in the
build. Multiple submodules can be separated by commas.
\badcode
~/qt-source/configure -submodules qtmultimedia,qtactiveqt
\endcode
\section2 Including or Excluding Features
The \b{-feature-}\e{<feature>} and \b{-no-feature-}\e{<feature>} options
include and exclude specific features, respectively.
For example, you can use the \b -no-feature-accessibility configure option
to disable \l Accessibility support in Qt:
\badcode
~/qt-source/configure -no-feature-accessibility
\endcode
Use \b{configure -list-features} to show a list of all available features
on the command line. Note that features can depend on other features, so
disabling a feature might have side-effects on other features.
\section1 Third-Party Libraries
The Qt source packages include third-party libraries. To set whether Qt
should use the system's versions of the libraries or to use the bundled
version, pass either \b -system or \b -qt before the name of the library to
configure.
The table below summarizes some third-party options:
\table
\header
\li Library Name
\li Bundled in Qt
\li Installed in System
\row
\li zlib
\li \b -qt-zlib
\li \b -system-zlib
\row
\li libjpeg
\li \b -qt-libjpeg
\li \b -system-libjpeg
\row
\li libpng
\li \b -qt-libpng
\li \b -system-libpng
\row
\li freetype
\li \b -qt-freetype
\li \b -system-freetype
\row
\li PCRE
\li \b -qt-pcre
\li \b -system-pcre
\row
\li HarfBuzz-NG
\li \b -qt-harfbuzz
\li \b -system-harfbuzz
\endtable
It's also possible to disable support for most of these libraries by using
\b -no instead of \b{-qt}.
configure in Qt 6 relies on CMake to locate third-party libraries.
It does so by checking various system paths. If you installed libraries
somewhere else, you can let CMake know this by setting or extending the
\b CMAKE_PREFIX_PATH variable.
For a full list of options, consult the help with \b{configure -help}.
\section2 SSL
Qt Network can be configured to support communication for Secure Sockets
Layer (SSL) but does not implement the actual algorithms itself. It needs
to leverage other libraries instead.
On Windows, Qt can use the system's Secure Channel library for this
purpose (configure option \b{-schannel}). On \macos and iOS, Qt can be
configured to use the SecureTransport API (configure option
\b{-securetransport}).
The most feature-complete support that also works on almost all target
platforms is provided by the \l {OpenSSL Toolkit} (option \b{-openssl}).
Qt does require OpenSSL 1.1.1 or later.
Qt can be configured to use OpenSSL in three ways:
\list
\li Qt Network loads OpenSSL libraries (DLLs) when first needed, at
runtime. If not found, the application continues to run but fails
to handle SSL communication. This is enabled by using the
configure option \b{-openssl-runtime}.
\li Qt Network links against the OpenSSL libraries. If they cannot be
found at load time, the application fails to start. This is enabled
by using the configure option \b{-openssl-linked}.
\li Qt Network compiles against a static version of the OpenSSL
libraries, and OpenSSL becomes part of the Qt Network library.
This is enabled by using the configure option \b{openssl-linked}
and setting the \b{OPENSSL_USE_STATIC_LIBS} variable to \b{ON}.
\endlist
Set the CMake variable \b{OPENSSL_ROOT_DIR} if OpenSSL is not installed in
a standard location, and therefore not found by configure.
See \l {Secure Sockets Layer (SSL) Classes} for further instructions on
Qt with SSL support.
\section1 Cross-Compilation Options
To configure Qt for cross-platform development and deployment, you need
to have a matching Qt version for the host machine first. Also, the
development toolchain for the target platform needs to be set up. This
set up varies among the \l{Supported Platforms}.
Common options are:
\list
\li \b -external-hostbindir - Path to Qt tools built for this machine.
\li \b -device - Select devices/mkspec for the qmake companion files.
\li \b -device-option - sets additional qmake variables.
\endlist
\note Toolchains for non-desktop targets often come with a so-called \e
sysroot that Qt needs to be configured against.
\section1 Developer Builds
The \b -developer-build configure option is a convenience option that
optimizes the build for developing Qt itself. It shouldn't be used for
building Qt variants that ship to customers.
Libraries in a developer build contain more exported symbols than a
standard build, and all Qt code compiles with a higher warning
level. It also changes the default prefix to the build directory, avoiding
the need to install Qt before testing things, and finally enables the
compilation of Qt's auto-tests by default.
\section1 Reconfiguring Existing Builds
The Qt build system has basic support for reconfiguring existing Qt builds
with a different set of configure options, but it is not very robust due
to the way CMake works internally.
The safest way to reconfigure an existing build is to pass the \b -redo
option to configure. That will remove the build's \b CMakeCache.txt file,
ensuring a relatively safe state for reconfiguration. The initial
configure flags will still apply to the reconfigured build.
\section1 Specific Options for Platforms
The following pages provide guidelines on how to configure Qt for specific
platform development:
\list
\li \l{Building Qt for QNX}
\li \l{Configure an Embedded Linux Device}
\li \l{Qt for Android - Building from Source}
\li \l{Qt for Linux/X11 - Building from Source}
\li \l{Qt for Windows - Building from Source}
\li \l{Qt for \macos - Building from Source}
\li \l{Qt for INTEGRITY - Monolith Project Tutorial}
\li \l{Qt for iOS - Building from Source}
\li \l{wasm-building-qt-from-source}{Qt for WebAssembly - Building from Source}
\endlist
*/
|