ECMQmlModule — Extra CMake Modules 5.106.0 documentation

# ECMQmlModule

This file contains helper functions to make it easier to create QML modules. It takes care of a number of things that often need to be repeated. It also takes care of special handling of QML modules between shared and static builds. When building a static version of a QML module, the relevant QML source files are bundled into the static library. When using a shared build, the QML plugin and relevant QML files are copied to the target’s `RUNTIME_OUTPUT_DIRECTORY` to make it easier to run things directly from the build directory.

Example usage:

    ecm_add_qml_module(ExampleModule URI "org.example.Example" VERSION 1.4)

    target_sources(ExampleModule PRIVATE ExamplePlugin.cpp)
    target_link_libraries(ExampleModule PRIVATE Qt::Quick)

    ecm_target_qml_sources(ExampleModule SOURCES ExampleItem.qml)
    ecm_target_qml_sources(ExampleModule SOURCES AnotherExampleItem.qml VERSION 1.5)

    ecm_finalize_qml_module(ExampleModule DESTINATION ${KDE_INSTALL_QMLDIR})

    ecm_add_qml_module(<target name> URI <module uri> [VERSION <module version>] [NO_PLUGIN] [CLASSNAME <class name>])

This will declare a new CMake target called `<target name>`. The `URI` argument is required and should be a proper QML module URI. The `URI` is used, among others, to generate a subdirectory where the module will be installed to.

If the `VERSION` argument is specified, it is used to initialize the default version that is used by `ecm_target_qml_sources` when adding QML files. If it is not specified, a default of 1.0 is used. Additionally, if a version greater than or equal to 2.0 is specified, the major version is appended to the installation path of the module.

If the option `NO_PLUGIN` is set, a target is declared that is not expected to contain any C++ QML plugin.

If the optional `CLASSNAME` argument is supplied, it will be used as class name in the generated QMLDIR file. If it is not specified, the target name will be used instead.

You can add C++ and QML source files to the target using `target_sources` and `ecm_target_qml_sources`, respectively.

Since 5.91.0

    ecm_add_qml_module_dependencies(<target> DEPENDS <module string> [<module string> ...])

Add the list of dependencies specified by the `DEPENDS` argument to be listed as dependencies in the generated QMLDIR file of `<target>`.

Since 5.91.0

    ecm_target_qml_sources(<target> SOURCES <source.qml> [<source.qml> ...] [VERSION <version>] [PATH <path>] [PRIVATE])

Add the list of QML files specified by the `SOURCES` argument as source files to the QML module target `<target>`.

If the optional `VERSION` argument is specified, all QML files will be added with the specified version. If it is not specified, they will use the version of the QML module target.

If the optional `PRIVATE` argument is specified, the QML files will be included in the target but not in the generated qmldir file. Any version argument will be ignored.

The optional `PATH` argument declares a subdirectory of the module where the files should be copied to. By default, files will be copied to the module root.

This function will fail if `<target>` is not a QML module target or any of the specified files do not exist.

Since 5.91.0

    ecm_finalize_qml_module(<target> DESTINATION <QML install destination>)

Finalize the specified QML module target. This must be called after all other setup (like adding sources) on the target has been done. It will perform a number of tasks:

- It will generate a qmldir file from the QML files added to the target. If the module has a C++ plugin, this will also be included in the qmldir file.

- If `BUILD_SHARED_LIBS` is off, a QRC file is generated from the QML files added to the target. This QRC file will be included when compiling the C++ QML module. The built static library will be installed in a subdirection of `DESTINATION` based on the QML module’s uri. Note that if `NO_PLUGIN` is set, a C++ QML plugin will be generated to include the QRC files.

- If `BUILD_SHARED_LIBS` in on, all generated files, QML sources and the C++ plugin will be installed in a subdirectory of `DESTINATION` based upon the QML module’s uri. In addition, these files will also be copied to the target’s `RUNTIME_OUTPUT_DIRECTORY` in a similar subdirectory.

This function will fail if `<target>` is not a QML module target.

Since 5.91.0