Qt6 Build System

This is a description of the Qt6 CMake-based build system.

For Qt5, see Qt5 Build System.

For a description of terms used here, please see the Qt Build System Glossary.

When writing CMake code, beware of the CMake Language Pitfalls.

There is some historical information at CMake Port.

Configuration at CMake level

Qt6 uses CMake, and you can use plain CMake to configure Qt. For a more convenient way to configure Qt, use the configure script, which internals are described further down on this page.

The configure.cmake files

How Qt can be configure is defined in configure.cmake files. There can be multiple configure.cmake files in a repository:

• configure.cmake at the top level of the repository
• src/mymodule/configure.cmake in the subdirectory of a Qt module

TBD: anatomy of configure.cmake files

Commands in configure.cmake

qt_feature("<feature>" ...)

Defines a feature called <feature>. Whether a feature is enabled can be then elsewhere be checked by QT_FEATURE_<name>.

qt_feature("<feature>" [PUBLIC] [PRIVATE]
                [LABEL "<label>"]
                [PURPOSE "<purpose>"]
                [SECTION "<selection>"]
                [AUTODETECT <condition>]
                [CONDITION <condition>]
                [ENABLE <condition>]
                [DISABLE <condition>]
                [EMIT_IF <condition>])

PUBLIC or PRIVATE defines whether the feature is available within the Qt module, or also in other Qt modules.

qt_feature_definition("<feature>" "<name>" ...)

Makes a C++ define <name> available.

qt_feature_definition("<feature>" "<name>" [NEGATE] [VALUE "<value>"])

If <value> is set, the define will have this as value.

If NEGATE is given, the define is set only if the feature is disabled. Otherwise it is set only if it is enabled.

Common tasks

Defining a simple boolean feature

TBD

Calling functions that the configure script doesn't know about

TBD

Qt's configure script

Qt's configure script is a convenience interface that translates its command line options to CMake arguments.

Where configure's logic is implemented

Most of configure's logic is implemented in qtbase/cmake/QtProcessConfigureArgs.cmake. This is a CMake script that is run via cmake -P by configure/configure.bat.

Only very special configure options need to be implemented here. Most should be doable with the qt_cmdline.cmake configuration files.

qt_cmdline.cmake files

Most configure options are defined in qt_cmdline.cmake files throughout the repositories. Each Qt repository can have a top-level qt_cmdline.cmake file and several lower-level ones. For example, qtbase has the following files (at the time of writing):

qt_cmdline.cmake
src/corelib/qt_cmdline.cmake
src/gui/qt_cmdline.cmake
src/network/qt_cmdline.cmake
src/plugins/sqldrivers/qt_cmdline.cmake
src/printsupport/qt_cmdline.cmake
src/sql/qt_cmdline.cmake
src/testlib/qt_cmdline.cmake
src/widgets/qt_cmdline.cmake
src/xml/qt_cmdline.cmake

The top-level file must reference the lower-level files. This is similar to include statements or CMake's add_subdirectory calls.

qt_commandline_subconfig(src/corelib)
qt_commandline_subconfig(src/network)
qt_commandline_subconfig(src/gui)
qt_commandline_subconfig(src/sql)
qt_commandline_subconfig(src/xml)
qt_commandline_subconfig(src/widgets)
...

This is also necessary to let configure pick up the configure.cmake files in the subdirectories. The configure script needs to be aware of the features defined in those configure.cmake files.

What effect can configure options have?

Configure options can affect three things:

• -foo could be directly translated to a CMake variable that is passed as -DNAME=value.
• -foo and -no-foo could control the feature "foo".
• --foo bar could set the variable INPUT_foo that can be used in configure.cmake or regular CMake files.

Commands available in qt_cmdline.cmake

qt_commandline_subconfig

qt_commandline_subconfig(path)

As outlined above, this is something like an include statement that pulls further qt_cmdline.cmake files. The parameter path is the path of a subdirectory where another qt_cmdline.cmake is located.

qt_commandline_option

qt_commandline_option(name
    TYPE type_name
    [NAME variable_name]
    [VALUE value]
    [VALUES value1 [value2 ...]]
    [MAPPING from1 to1 [from2 to2 ...]]
    [CONTROLS_FEATURE]
)

qt_commandline_custom

qt_commandline_custom(handler)

Registers a custom handler function. This was once used to handle QMAKE_xxx=yyy assignments. You really must do internal stuff in there.

This functionality should probably be removed.

qt_commandline_prefix

qt_commandline_prefix(D defines)

Add a configure option -D that sets the variable INPUT_defines. The user may pass multiple prefix arguments to configure. The values accumulate in INPUT_defines.

QtProcessConfigureArgs.cmake has special handling for all prefixes in qtbase.

Common tasks

How to add a command line option that controls a feature?

TBD

How to add a command line option that sets a CMake variable?

TBD