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
|
/****************************************************************************
**
** Copyright (C) 2017 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** 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.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page configure-options.html
\title Qt Configure Options
\brief Configuring Qt's compile options
\c configure is a command-line tool which determines how to build Qt for a
particular platform. Configure can exclude a feature in Qt as well
as determine how Qt builds and deploys applications onto host platforms.
This page discusses some of the configure options, but for
the full list of options, enter the command \c{configure -h}. Configure
should be run from the main Qt source directory.
Unless stated otherwise, the commands in this page are for the Linux
platforms. On \macos and on Windows, the \c PATH and directory structure
are different, therefore the commands will vary. Also, on Windows systems,
the configure script is called \e configure.bat.
After running \c configure, build the sources with the \c make tool
belonging to the chosen toolchain.
\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 Makefiles, 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 is recommended to keep these directories separate by shadow-building and
using the \c -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 \c configure from a separate directory:
\badcode
mkdir ~/qt-build
cd ~/qt-build
~/qt-source/configure -prefix /opt/Qt5.9
qmake
\endcode
Configuring with the \c -prefix option means that the Qt binaries and
libraries are installed into another directory, which is \c /opt/Qt5.9 in
this case. Running \c qmake generates the Makefiles in the \e ~/qt-build
directory and not in the \e source directory. After the Makefiles are in
place, run the following commands to build the Qt binaries and libraries,
and install them:
\badcode
make
make install
\endcode
\note The 'make install' step is required only if Qt is configured with a
\e -prefix, which is the default on Unix-based platforms unless the
\e -developer-build configure option is used. On Windows, Qt is configured
as a non-prefix build by default.
\note The \c -developer-build is meant for developing Qt and not for
shipping applications. Such a build contains more exported symbols than
a standard build and compiles with a higher warning level.
\section1 Modules and Features
Qt consists of different \l{All Modules}{modules} whose sources can be
found in different directories inside the top-level source directory.
Users can explicitly exclude specific top-level directories to limit build
times. Furthermore, each Qt module might have features that can also be
explicitly enabled or disabled.
\section2 Excluding Qt Modules
Configure's \c -skip option allows top-level source directories to be
excluded from the Qt build. Note that many directories contain multiple Qt
modules. For example, to exclude Qt NFC and Qt Bluetooth from the Qt build,
provide \c{-skip qtconnectivity} as the argument to configure.
\code
./configure -skip qtconnectivity
\endcode
\section2 Including or Excluding Features
The \c{-feature-}\e{<feature>} and \c{-no-feature-}\e{<feature>} options
include and exclude specific features, respectively.
For example, to disable \l Accessibility, provide
\c -no-feature-accessibility as the argument:
\code
./configure -no-feature-accessibility
\endcode
Use \c{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.
The \l{Qt Configuration Tool} that is part of \l{Qt for Device Creation}
allows the tweaking of features and dependencies through a convenient user
interface.
\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 \c -system or \c -qt before the name of the library to
configure.
The table below summarizes the third-party options:
\table
\header
\li Library Name
\li Bundled in Qt
\li Installed in System
\row
\li zlib
\li \c -qt-zlib
\li \c -system-zlib
\row
\li libjpeg
\li \c -qt-libjpeg
\li \c -system-libjpeg
\row
\li libpng
\li \c -qt-libpng
\li \c -system-libpng
\row
\li xcb
\li \c -qt-xcb
\li \c -system-xcb
\row
\li xkbcommon
\li \c -qt-xkbcommon
\li \c -system-xkbcommon
\row
\li freetype
\li \c -qt-freetype
\li \c -system-freetype
\row
\li PCRE
\li \c -qt-pcre
\li \c -system-pcre
\row
\li HarfBuzz-NG
\li \c -qt-harfbuzz
\li \c -system-harfbuzz
\endtable
It is also possible to disable support for these libraries by using
\c -no instead of \c{-qt}. For example, to use the system's xcb library
and disable zlib support, enter the following:
\code
./configure -no-zlib -qt-libjpeg -qt-libpng -system-xcb
\endcode
For a full list of options, consult the help with \c {configure -help}.
\section1 Compiler Options
The \c -platform option sets the host platform and the compiler for building
the Qt sources. The list of supported platforms and compilers is found in
the \l{Community Supported Platforms}{supported platforms} page while the
full list is available in \e{qtbase/mkspecs} directory.
For example, on Ubuntu Linux systems, Qt can be compiled by several
compilers such as clang or g++:
\code
./configure -platform linux-clang
./configure -platform linux-g++
./configure -platform linux-g++-32
\endcode
For \l{Qt for Windows}{Windows} machines, either MinGW or Visual Studio
toolchains can be used to compile Qt.
\code
configure.bat -platform win32-g++
configure.bat -platform win32-msvc
\endcode
Afterwards, the generated Makefiles will use the appropriate compiler
commands.
\section1 Cross-Compilation Options
To configure Qt for cross-platform development and deployment, 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 \c -xplatform - the target platform. Valid xplatform options are the same
as the \c -platform options which are found in \e{qtbase/mkspecs}.
\li \c -device - a specific device or chipsets. The list of devices that configure is compatible with are
found in \e{qtbase/mkspecs/devices}. For more information, visit the \l{http://wiki.qt.io/Category:Devices}{Devices}
Wiki page.
\li \c -device-option - sets additional qmake variables. For example, \c{-device-option CROSS_COMPILE=}\e{<path-to-toolchain>} provides
the environment variable, \c{CROSS_COMPILE}, as needed by certain devices.
\endlist
\note Toolchains for non-desktop targets often come with a so-called \e
sysroot which Qt needs to be configured against.
\section2 Specific Options for Platforms
The following pages provide guidelines on how to configure Qt for specific
platform development:
\list
\li \l{Building Qt 5 for Android} Wiki page
\li \l{Qt for iOS - Building from Source}
\li \l{Qt for WinRT#Building from source}{Qt for WinRT - Building from Source}
\li \l{Qt for Embedded Linux#Configuring a Specific Device}{Qt for Embedded Linux - Building from Source}
\li \l{http://wiki.qt.io/Qt_RaspberryPi}{Qt for Raspberry Pi} - a community-driven site for
Raspberry devices
\li \l{http://wiki.qt.io/Category:Devices}{Devices} - a list of other devices and chipsets
\endlist
\section1 OpenGL Options for Windows
On Windows, Qt can be configured with the system OpenGL or with \l{ANGLE}.
By default, Qt is configured to use dynamic OpenGL. This means that it tries
to use system OpenGL and falls back to ANGLE, which is bundled with Qt and
depends on the DirectX SDK, if native OpenGL does not work. ANGLE enables
running Qt applications that depend on OpenGL, without installing the latest
OpenGL drivers. If ANGLE also fails, Qt will fall back to software rendering,
which is the slowest but most safe of the rendering methods.
The \c -opengl option can be used to configure Qt to use
the OpenGL in the target system, a different version of OpenGL ES (with or
without ANGLE), or dynamically switch between the available OpenGL
implementations.
\code
configure.bat -opengl dynamic
\endcode
With the \c dynamic option, Qt will try to use native OpenGL first. If that
fails, it will fall back to ANGLE and finally to software rendering in case
of ANGLE failing as well.
\code
configure.bat -opengl desktop
\endcode
With the \c desktop option, Qt uses the OpenGL installed on Windows,
requiring that the OpenGL in the target Windows machine is compatible with
the application. The \c -opengl option accepts two versions of OpenGL ES, \c
es2 for OpenGL ES 2.0 or \c es1 for OpenGL ES Common Profile.
\code
configure.bat -opengl es2
\endcode
You can also use \c{-opengl dynamic}, which enable applications to
dynamically switch between the available options at runtime. For more
details about the benefits of using dynamic GL-switching, see
\l{Graphics Drivers}.
*/
|
