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.

At the moment, there's not much here. We plan to extend this in the future. There's some information from the times of the initial CMake port. See below.

Configuration at CMake level

This is supposed to be a reference of Qt-specific CMake functions one can use in configure.cmake files. Since the port currently is still evolving quite rapidly, things may change. The ultimate reference is the code in qtbase/cmake/.

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.

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

In principle, we could cram everything into one file.

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