Modernizing QML Modules | Qt Qml | Qt 6.11.0
Description: Modernize your QML modules.

- Qt 6.11
- Qt Qml
- The QML Reference
- QML Modules
- Modernizing QML Modules
- Qt 6.11.0 Reference Documentation

Tying it all together with CMake ◦ Fine Tuning QML Modules

# Modernizing QML Modules

QML modules have become more powerful and easier to use in Qt 6. The following sections describe how to modernize QML modules that already use qt_add_qml_module.

See also Port QML modules to CMake on how to port a QML module to the qt_add_qml_module CMake API.

## Use qt_standard_project_setup

qt_standard_project_setup sets up Qt CMake policies needed for modern QML modules, among other things. To modernize your QML module and follow best practices, call qt_standard_project_setup in the project's top-level `CMakeLists.txt` file before any qt_add_qml_module call:

     qt_standard_project_setup(REQUIRES 6.8)

## Use the new standard resource path prefix

The standard resource path for QML modules moved from `:/` to `:/qt/qml` with QTP0001. Don't use custom resource prefixes nor extend import paths in the engine. Remove all `RESOURCE_PREFIX` arguments from all qt_add_qml_module calls, as well as all calls to QQmlEngine::addImportPath or similar. Change all qrc paths in your C++ and QML code to use the new resource path prefix:

     // C++ usages like:
     QUrl someUrl("qrc:/MyQmlModule/MyResource1.png");
     // need to be changed to
     QUrl someUrl("qrc:/qt/qml/MyQmlModule/MyResource1.png");

     // QML usages like:
     ":/MyQmlModule/MyResource1.png"
     // need to be changed to
     ":/qt/qml/MyQmlModule/MyResource1.png"

See also Using the Qt Resource System with QML.

## Use loadFromModule to load your QML files

With the default import path, you can use the `loadFromModule` methods, like QQmlApplicationEngine::loadFromModule, QQuickView::loadFromModule, or QQmlComponent::loadFromModule, for example.

Use `loadFromModule` to load your QML file, for example:

     engine.load(QUrl(QStringLiteral("qrc:/MyQmlModule/Main.qml")));
     // becomes
     engine.loadFromModule("MyQmlModule", "Main");

## Replace OUTPUT_DIRECTORY and IMPORT_PATH with DEPENDENCIES TARGET

Avoid setting an `IMPORT_PATH` in the qt_add_qml_module. Instead, use `DEPENDENCIES TARGET` to declare dependencies to other QML modules that can't be found in the current import path.

Using `DEPENDENCIES TARGET` also eliminates the need for the `QT_QML_OUTPUT_DIRECTORY` CMake variable and the `OUTPUT_DIRECTORY` argument to qt_add_qml_module, so remove their definitions and usages.

For example:

     ### in the CMakeLists.txt file defining the dependent QML module:
     # don't set QT_QML_OUTPUT_DIRECTORY and remove lines like these:
     set(QT_QML_OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/qml)

     qt_add_qml_module(MyThirdPartyQmlLibraryDependency
         URI MyThirdPartyQmlLibraryDependency
         ....
         # custom output paths are obsolete due to DEPENDENCIES TARGET below, so remove:
         OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/qml
     }

     ### in the CMakeLists.txt file defining the QML module that uses the dependency:
     qt_add_qml_module(MyQmlLibrary
         URI MyQmlModule
         ...
         # replace import paths like these:
         IMPORT_PATH ${CMAKE_CURRENT_BINARY_DIR}/thirdparty/qml
         # with:
         DEPENDENCIES TARGET MyThirdPartyQmlLibraryDependency
     }

Note: You might need to call `add_subdirectory()` before calling qt_add_qml_module in your CMakeLists.txt for `DEPENDENCIES TARGET` to find the target.

For more information on how to declare module dependencies, see Declaring module dependencies.

See also Changes to Qt QML and Port QML modules to CMake.

Tying it all together with CMake ◦ Fine Tuning QML Modules