QmlModule

QML extension module consisting of a plugin library and QML files. More...

• List of all members, including inherited members
• QmlModule is part of List of All Items.

Properties

• modulesInstallDir : string
• uri : string

Detailed Description

A QmlModule is a convenience item that mirrors the functionality of CMake's qt_add_qml_module() command. It combines a plugin library with automatic QML type registration, qmldir generation, and resource embedding, so that the module can be imported from QML using the module-based import syntax (rather than file or directory imports).

What QmlModule Does Automatically

• Runs qmltyperegistrar on C++ files decorated with QML_ELEMENT or similar macros and produces a plugins.qmltypes file.
• Generates a qmldir file listing all QML files and, if Qt.qml.loadedAtRuntime is true, a plugin line for dynamic loading.
• Embeds all QML files, JavaScript files, and the qmldir into the plugin's resources at :/qt/qml/<URI>/, enabling the prefer :/qt/qml/<URI>/ directive so the QML engine uses embedded resources rather than files on disk.
• Installs qmldir, plugins.qmltypes, as well as QML and JavaScript files to modulesInstallDir. When the plugin is loaded at runtime (Qt.qml.loadedAtRuntime is true), the library binary is installed there too.

Usage

Dynamic Plugin — Linked Directly by the Application

The application lists the module as a dependency, which links the plugin at build time. The QML engine finds module types through the pre-registered module without loading a plugin file at runtime. Because Qt.qml.loadedAtRuntime defaults to true for dynamic libraries, set it to false to suppress the plugin line in the generated qmldir.

// mymodule/mymodule.qbs
QmlModule {
    name: "mymoduleplugin"
    uri: "com.example.MyModule"
    Qt.qml.loadedAtRuntime: false
    files: ["MyItem.qml", "mytype.h", "mytype.cpp"]
}

// app/app.qbs
CppApplication {
    Depends { name: "mymoduleplugin" }
    // ...
}

Dynamic Plugin — Loaded at Runtime via Import Path

In this mode the plugin .so is not linked by the application. Instead, the QML engine discovers and loads it at runtime through the QML import path. Qt.qml.loadedAtRuntime defaults to true for dynamic libraries, so no override is needed:

QmlModule {
    name: "mymoduleplugin"
    uri: "com.example.MyModule"
    files: [...]
}

However, you need to point the QML engine to the install location via QML_IMPORT_PATH or QQmlEngine::addImportPath().

Static Plugin

For platforms that require static linking (iOS, tvOS, watchOS), the type is automatically set to staticlibrary. On other platforms, override type directly. Qt.qml.loadedAtRuntime defaults to false for static libraries, so no override is needed there either.

QmlModule {
    name: "mymoduleplugin"
    uri: "com.example.MyModule"
    type: ["staticlibrary"]
    files: [...]
}

CppApplication {
    Depends { name: "mymoduleplugin" }
    // ...
}

Property Documentation

Plugin QtApplication