QTP0005

qt_add_qml_module dependency keywords accept CMake targets

This policy was introduced in Qt 6.8. It allows passing CMake targets to qt_add_qml_module() via the DEPENDENCIES, IMPORTS, OPTIONAL_IMPORTS, and DEFAULT_IMPORTS keywords.

Enabling this policy means that arguments passed to those keywords can be prefixed with TARGET, and are then treated as a CMake target name. The QML module URI and import path are derived automatically from the target.

The OLD behavior of this policy is that the token sequence TARGET name is treated as two separate URIs, TARGET and name.

The NEW behavior of this policy is that TARGET is a keyword. The URI is extracted from the QML module target that follows. It is a hard error if the name following TARGET does not refer to an existing target, or if that target does not correspond to a QML module.

In both the NEW and the OLD behavior it is possible to specify a module version by appending a slash and the version. See Declaring module dependencies for more details.

Background

Before this policy, QML module dependencies had to be declared by their string URI, for example QtQuick or com.example.mymodule. This meant that the URI and, when needed, the import path of the dependency had to be kept consistent with the CMake target that provides the module.

With the NEW behavior, you can refer to a dependency by its CMake target name instead. The build system then determines the correct URI and import path from the target automatically. This removes the need to manually specify IMPORT_PATH entries for dependencies outside the default QML import path, reduces redundancy, and eliminates a class of copy-paste mistakes.

Example

Consider a module that depends on another module defined in the same project. With the OLD behavior (or before Qt 6.8), the URI must be spelled out explicitly:

qt_add_qml_module(my_module
    URI MyModule
    VERSION 1.0
    DEPENDENCIES
        OtherModule
)

With the NEW behavior (policy QTP0005 set to NEW), you can refer to the dependency by its CMake target name:

qt_policy(SET QTP0005 NEW)

qt_add_qml_module(other_module
    URI OtherModule
    VERSION 1.0
)

qt_add_qml_module(my_module
    URI MyModule
    VERSION 1.0
    DEPENDENCIES
        TARGET other_module
)

The same TARGET syntax is available for IMPORTS, OPTIONAL_IMPORTS, and DEFAULT_IMPORTS.

As shown above, you can set the policy explicitly with qt_policy(SET QTP0005 NEW) before calling qt_add_qml_module(). Alternatively, call qt_standard_project_setup() with a REQUIRES version of 6.8 or later to enable all policies up to that version.

Qt 6.8 issues a deprecation warning if you use TARGET as a token in DEPENDENCIES, IMPORTS, OPTIONAL_IMPORTS, or DEFAULT_IMPORTS while the policy is set to OLD. Use the qt_policy command to suppress the warning by explicitly setting the policy to OLD or NEW.