Qt Configure Options

configure must be called in a working build environment where CMake, compilers, and required build tools are readily available. 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:

~/qt-source/configure
cmake --build . --parallel
cmake --install .

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.

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 build system files, 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's 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/Qt6

Configuring with the -prefix option means that the Qt binaries and libraries are installed into another directory, which is /opt/Qt6 in this case.

By default, configure only configures Qt's libraries and tools. You can use -make examples or -make tests to also build the examples or tests that come with Qt:

~/qt-source/configure -make examples -make tests

You can also configure Qt such that examples, tests, and tools are configured, but not built by default. If you set the CMake variables QT_BUILD_EXAMPLES_BY_DEFAULT, QT_BUILD_TESTS_BY_DEFAULT, and QT_BUILD_TOOLS_BY_DEFAULT to OFF, the respective parts will not be built by "cmake –build .". Instead, CMake will generate individual targets that you can then build individually.

Here we build Qt libraries and tools, but also the NotePad Example:

~/qt-source/configure -make examples -- -D QT_NO_MAKE_EXAMPLES=ON
cmake --build . --parallel
cmake --build . --parallel --target notepad

You can build Qt libraries and tools in various variants, each of them optimized for a different use case.

Debug and Release Builds▲

Static and Shared Builds▲

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 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.

Qt consists of different 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.

Excluding Qt Modules▲

~/qt-source/configure -skip qtwayland

Including or Excluding Features▲

~/qt-source/configure -no-feature-accessibility

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 some third-party options:

It's also possible to disable support for these libraries by using -no instead of -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 CMAKE_PREFIX_PATH variable.

For a full list of options, consult the help with configure -help.

SSL▲

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 Supported Platforms.

Common options are:

• -external-hostbindir - Path to Qt tools built for this machine.

• -device - Select devices/mkspec for the qmake companion files.

• -device-option - sets additional qmake variables.

The -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.

The following pages provide guidelines on how to configure Qt for specific platform development:

• Building Qt for QNX

• Configure an Embedded Linux Device

• Qt for Android - Building from Source

• Qt for Linux/X11 - Building from Source

• Qt for Windows - Building from Source

• Qt for macOS - Building from Source

• Qt for INTEGRITY - Monolith Project Tutorial

• Qt for iOS - Building from Source

• Qt for WebAssembly - Building from Source