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 is located in qtbase but is also available from the main Qt source directory.
Unless stated otherwise, the commands in this page are for the Linux platforms. On Mac OS X 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.
Paths, Prefixes, and Shadow-Building
Qt's default installation directory depends on the platform but can be set with the -prefix option. Configure always prints the installation directory when it finishes.
./configure -prefix ~/home/user/Qt-5.1
Shadow building is when the Makefiles and libraries are not built in the same directory as the source directory. Shadow building keeps the source directory contents free of generated Makefiles and other intermediate compilation files. Note that the default installation directory is not modified when shadow building. To shadow build, run configure in a clean directory.
mkdir ~/Qt-builds cd ~/Qt-builds ~/qt-source/configure
Setting both the shadow build and prefix to a directory outside of the Qt sources allows multiple Qt configurations to exist. For example, one installation can contain a statically-linked Qt while another installation contains a dynamically-linked Qt.
cd ~/Qt-static ~/qt/configure -prefix $PWD/qtbase -static cd ~/Qt-dynamic ~/qt/configure -prefix $PWD/qtbase -shared
It is also possible to set the shadow build directory and the installation directory (set by the prefix option) to separate directories. This setup will build Qt in a separate directory and install it into a different directory.
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 (experimental) | -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 listed in qtbase/mkspecs.
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
- iOS
- Qt for BlackBerry - a community-driven site for BlackBerry and QNX devices
- 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, configure uses ANGLE, which is bundled with the Qt sources, but requires the DirectX SDK. Through ANGLE, OpenGL ES 2.0 is mapped to DirectX APIs. OpenGL applications can then be deployed to Windows computers with older OpenGL APIs, without requiring that the latest OpenGL version be installed in the system.
The -opengl option configures Qt to use the OpenGL in the target system or a different version of OpenGL ES.
configure.bat -opengl desktop
With the desktop option, Qt uses the OpenGL installed in 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