Qt Configure Options | Qt 6.11
Description: Configuring Qt's compile options.

- Qt 6.11
- Getting Started with Qt
- Get and Install Qt
- Building Qt Sources
- Qt Configure Options
- Qt 6.11.0 Reference Documentation

Getting Qt Sources from the Git repository ◦ Building Optimized Qt

# Qt Configure Options

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

## Configure Workflow

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.

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

## Examples, Tests, and Tools

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_BUILD_EXAMPLES_BY_DEFAULT=OFF
     cmake --build . --parallel
     cmake --build . --parallel --target notepad

Note: The `-developer-build` option builds tests by default. See also Developer Builds below.

## Build Configurations

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

### Debug and Release Builds

`-release` tells the compiler to optimize the code, and not provide additional debug symbols alongside Qt and its tools.

`-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, `-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:

- `-force-debug-info`: Creates a release build with debug information.
- `-separate-debug-info`: Extracts the debug information into a separate file.
- `-optimize-size`: Optimizes release builds for size instead of speed.

### 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 shared build and is the default configuration on most platforms. The matching configure option is `-shared`.

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 static build and can be selected when configuring with the `-static` option.

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

## Modules and Features

The Qt source code is organized in several top-level directories called submodules, for example, `qtbase`, `qtdeclarative` or `qtmultimedia`. Inside these submodules, you find the source code for the different Qt Modules. Qt Core, Qt Quick, and Qt Multimedia are examples of such Qt modules.

Note: Many submodules (top-level source directories) have the same name as the Qt Modules they implement, but this is not always the case. For instance, `qtdeclarative` contains Qt Quick and 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.

### Including and Excluding Qt Submodules

configure's `-skip` option is used to exclude submodules (top-level source directories) from the Qt build. Excluding a submodule excludes all Qt Modules inside that submodule. The `qtwayland` submodule contains both the Qt Wayland Compositor and the Qt Wayland QPA plugin. Specifying `-skip qtwayland` as a configure option will therefore exclude both Qt Modules.

     ~/qt-source/configure -skip qtwayland

configure's `-submodules` option can be used to configure a build that only builds the listed submodules and their dependencies. For example, by specifying the `qtmultimedia` submodule, Qt Multimedia and all its dependencies will be included in the build. Multiple submodules can be separated by commas.

     ~/qt-source/configure -submodules qtmultimedia,qtactiveqt

### Including or Excluding Features

The `-feature-`<feature> and `-no-feature-`<feature> options include and exclude specific features, respectively.

For example, you can use the `-no-feature-accessibility` configure option to disable Accessibility support in Qt:

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

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

## 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 some 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`
freetype | `-qt-freetype` | `-system-freetype`
PCRE | `-qt-pcre` | `-system-pcre`
HarfBuzz-NG | `-qt-harfbuzz` | `-system-harfbuzz`

It's also possible to disable support for most of 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

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 `-schannel`). On macOS and iOS, Qt can be configured to use the SecureTransport API (configure option `-securetransport`).

The most feature-complete support that also works on almost all target platforms is provided by the OpenSSL Toolkit (option `-openssl`). Qt does require OpenSSL 1.1.1 or later.

Qt can be configured to use OpenSSL in three ways:

- 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 `-openssl-runtime`.
- 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 `-openssl-linked`.
- 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 `openssl-linked` and setting the `OPENSSL_USE_STATIC_LIBS` variable to `ON`.

Set the CMake variable `OPENSSL_ROOT_DIR` if OpenSSL is not installed in a standard location, and therefore not found by configure.

See Secure Sockets Layer (SSL) Classes for further instructions on Qt with SSL support.

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

Note: Toolchains for non-desktop targets often come with a so-called sysroot that Qt needs to be configured against.

## Developer Builds

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.

## 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 `-redo` option to configure. That will remove the build's CMakeCache.txt file, ensuring a relatively safe state for reconfiguration. The initial configure flags will still apply to the reconfigured build.

## Installing Configure Summary and Options

Since Qt 6.9, the configure summary files, as well as the options passed to `configure`, can be automatically included as part of the installation.

This feature is enabled by setting the CMake variable `QT_INSTALL_CONFIG_INFO_FILES` to `ON`:

     ~/qt-source/configure -prefix /opt/Qt6 -- -D QT_INSTALL_CONFIG_INFO_FILES=ON

During installation, text files for configure summary and options (for each repository part of the build) are copied to the architecture-independent Qt data directory.

For example,

     /opt/Qt6/config_qtbase.opt
     /opt/Qt6/config_qtbase.summary
     /opt/Qt6/config_qtdeclarative.opt
     /opt/Qt6/config_qtdeclarative.summary
     ...

## Specific Options for Platforms

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

- Building Qt for QNX
- Building Qt for VxWorks
- 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

Getting Qt Sources from the Git repository ◦ Building Optimized Qt