- Qt 6.12
- Qt Qml
- CMake Integration for QML
- CMake Policies for QML
- QTP0005
- Qt 6.12.0 Reference Documentation

QTP0004 ◦ Advanced QML Topics

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

When the module target is an executable and `TARGET` dependencies are used, qt_add_qml_module() automatically generates a `qt.conf` file next to the executable in the build directory. This file configures the QML Import Path so that QML modules specified as `TARGET` dependencies can be found at run time. Use `NO_GENERATE_QTCONF` to suppress this behavior.

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

Note: The `OLD` behavior of a policy is deprecated, and may be removed in the future.

See also qt_policy, qt_standard_project_setup(), qt_cmake_policies, and qt_add_qml_module.

QTP0004 ◦ Advanced QML Topics