Qt Configure Options
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 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 PATH
and directory structure are different, therefore the commands will vary. Also, on Windows systems, the configure script is called configure.bat.
After running configure
, build the sources with the make
tool belonging to the chosen toolchain.
Source, Build, and Install Directories
The source directory contains the source code that is obtained from the source package or git repository. The build directory is where the build-related files such as Makefiles, object files, and other intermediate files are stored. The 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 -prefix
option. This enables you to keep the Qt 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:
mkdir ~/qt-build cd ~/qt-build ~/qt-source/configure -prefix /opt/Qt5.6 qmake
Configuring with the -prefix
option means that the Qt binaries and libraries are installed into another directory, which is /opt/Qt5.6
in this case. Running qmake
generates the Makefiles in the ~/qt-build directory and not in the source directory. After the Makefiles are in place, run the following commands to build the Qt binaries and libraries, and install them:
make make install
Note: The 'make install' step is required only if Qt is configured with a -prefix, which is the default on Unix-based platforms unless the -developer-build configure option is used. On Windows, Qt is configured as a non-prefix build by default.
Note: The -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.
Including and Excluding Qt Modules
With configure, it is possible to include or exclude particular Qt modules in a Qt build. However, keep in mind that many modules depend on other modules, therefore, dependency issues can arise with some build configurations.
Excluding a Qt Submodule
Configure's -skip
option allows certain Qt submodules to be excluded from the Qt build. These submodules correspond to the Git submodules in the standard Qt 5 repository. Note that many packages contain multiple Qt modules. For example, to exclude Qt NFC and Qt Bluetooth from the Qt build, provide -skip qtconnectivity
as the argument to configure.
./configure -skip qtconnectivity
Including or Excluding Features
The -feature-
<feature> and -no-feature-
<feature> options include and exclude specific features, respectively, where <feature> is listed in the file qtbase/src/corelib/global/qfeatures.txt.
For example, to disable Accessibility, provide -no-feature-accessibility
as the argument:
./configure -no-feature-accessibility
Note: Features outside of qtbase are not included in the features list.
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 -system
or -qt
before the name of the library to configure.
The table below summarizes the third-party options:
Library Name | Bundled in Qt | Installed in System |
---|---|---|
zlib | -qt-zlib | -system-zlib |
libjpeg | -qt-libjpeg | -system-libjpeg |
libpng | -qt-libpng | -system-libpng |
xcb | -qt-xcb | -system-xcb |
xkbcommon | -qt-xkbcommon | -system-xkbcommon |
freetype | -qt-freetype | -system-freetype |
PCRE | -qt-pcre | -system-pcre |
HarfBuzz-NG | -qt-harfbuzz | -system-harfbuzz |
It is also possible to disable support for these libraries by using -no
instead of -qt
. For example, to use the system's xcb library and disable zlib support, enter the following:
./configure -no-zlib -qt-libjpeg -qt-libpng -system-xcb
For a full list of options, consult the help with configure -help
.
Compiler Options
The -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 supported platforms page while the full list is available in qtbase/mkspecs directory.
For example, on Ubuntu Linux systems, Qt can be compiled by several compilers such as clang or g++:
./configure -platform linux-clang ./configure -platform linux-g++ ./configure -platform linux-g++-32
For Windows machines, either MinGW or Visual Studio toolchains can be used to compile Qt.
configure.bat -platform win32-g++ configure.bat -platform win32-msvc2010
Afterwards, the generated Makefiles will use the appropriate compiler commands.
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 Supported Platforms.
Common options are:
-xplatform
- the target platform. Valid xplatform options are the same as the-platform
options which are found in qtbase/mkspecs.-device
- a specific device or chipsets. The list of devices that configure is compatible with are found in qtbase/mkspecs/devices. For more information, visit the Devices Wiki page.-device-option
- sets additional qmake variables. For example,-device-option CROSS_COMPILE=
<path-to-toolchain> provides the environment variable,CROSS_COMPILE
, as needed by certain devices.
Note: Toolchains for non-desktop targets often come with a so-called sysroot which Qt needs to be configured against.
Specific Options for Platforms
The following pages provide guidelines on how to configure Qt for specific platform development:
- Building Qt 5 for Android Wiki page
- Qt for iOS - Building from Source
- Qt for WinRT - Building from Source
- Qt for Embedded Linux - Building from Source
- Qt for Raspberry Pi - a community-driven site for Raspberry devices
- Devices - a list of other devices and chipsets
OpenGL Options for Windows
On Windows, Qt can be configured with the system OpenGL or with ANGLE. By default, Qt is configured to use ANGLE, which is bundled with Qt and depends on the DirectX SDK. ANGLE enables running Qt applications that depend on OpenGL, without installing the latest OpenGL libraries.
The -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.
configure.bat -opengl desktop
With the desktop
option, Qt uses the OpenGL installed on Windows, requiring that the OpenGL in the target Windows machine is compatible with the application. The -opengl
option accepts two versions of OpenGL ES, es2
for OpenGL ES 2.0 or es1
for OpenGL ES Common Profile.
configure.bat -opengl es2
You can also use -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 Graphics Drivers.
© 2017 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.