This command was introduced in Qt 6.2.
qt_add_qml_module(
target
URI uri
VERSION version
[PAST_MAJOR_VERSIONS ...]
[STATIC | SHARED]
[PLUGIN_TARGET plugin_target]
[OUTPUT_DIRECTORY output_dir]
[RESOURCE_PREFIX resource_prefix]
[CLASS_NAME class_name]
[TYPEINFO typeinfo]
[IMPORTS ...]
[OPTIONAL_IMPORTS ...]
[DEFAULT_IMPORTS ...]
[DEPENDENCIES ...]
[IMPORT_PATH ...]
[SOURCES ...]
[QML_FILES ...]
[RESOURCES ...]
[OUTPUT_TARGETS out_targets_var]
[DESIGNER_SUPPORTED]
[FOLLOW_FOREIGN_VERSIONING]
[NAMESPACE namespace]
[NO_PLUGIN_OPTIONAL]
[NO_CREATE_PLUGIN_TARGET]
[NO_GENERATE_PLUGIN_SOURCE]
[NO_GENERATE_QMLTYPES]
[NO_GENERATE_QMLDIR]
[NO_LINT]
[NO_CACHEGEN]
[NO_RESOURCE_TARGET_PATH]
[NO_IMPORT_SCAN]
[ENABLE_TYPE_COMPILER]
[TYPE_COMPILER_NAMESPACE namespace]
)
If versionless commands are disabled, use qt6_add_qml_module() instead. It supports the same set of arguments as this command.
See Building a QML application and Building a reusable QML module for examples that define QML modules.
This command defines a QML module that can consist of C++ sources, .qml files, or both. It ensures that essential module details are provided and that they are consistent. It also sets up and coordinates things
like cached compilation of .qml sources, resource embedding, linting checks, and auto-generation of some key module files.
A QML module can be structured in a few different ways. The following scenarios are the typical arrangements:
This is the recommended arrangement for most QML modules. All of the module's functionality is implemented in the backing target, which is given as the first command argument. C++ sources, .qml files, and
resources should all be added to the backing target. The backing target is a library that should be installed in the same location as any other library defined by the project.
The source directory structure under which the backing target is created should match the target path of the QML module (the target path is the module's URI with dots replaced by forward slashes). If the source directory
structure doesn't match the target path, qt_add_qml_module() will issue a warning.
The following example shows a suitable source directory structure for a QML module with a URI of MyThings.Panels. The call to qt_add_qml_module() would be in the CMakeLists.txt file
shown.
src
+-- MyThings
+-- Panels
+-- CMakeLists.txt
A separate plugin target is associated with the QML module. It is used at runtime to load the module dynamically when the application doesn't already link to the backing target. The plugin target will also be a library and is normally installed to the same directory as the module's qmldir file.
The plugin target should ideally contain nothing more than a trivial implementation of the plugin class. This allows the plugin to be designated as optional in the qmldir file. Other targets can then link
directly to the backing target and the plugin will not be needed at runtime, which can improve load-time performance. By default, a C++ source file that defines a minimal plugin class will be automatically generated and added
to the plugin target. For cases where the QML module needs a custom plugin class implementation, the NO_GENERATE_PLUGIN_SOURCE and usually the NO_PLUGIN_OPTIONAL options will be needed.
Note: When using static linking, it migt be necessary to use Q_IMPORT_QML_PLUGIN to ensure that the QML plugin is correctly linked.
A QML module can be defined with the plugin target serving as its own backing target. In this case, the module must be loaded dynamically at runtime and cannot be linked to directly by other targets. To create this
arrangement, the PLUGIN_TARGET keyword must be used, with the target repeated as the plugin target name. For example:
qt_add_qml_module(someTarget
PLUGIN_TARGET someTarget
...
)
While this arrangement may seem marginally simpler to deploy, a separate backing target should be preferred where possible due to the potentially better load-time performance.
An executable target can act as a backing target for a QML module. In this case, there will be no plugin library, since the QML module will always be loaded directly as part of the application. The
qt_add_qml_module() command will detect when an executable is used as the backing target and will automatically disable the creation of a separate plugin. Do not use any of the options with PLUGIN in
their name when using this arrangement.
When an executable is used as the backing target, the source directory structure is not expected to match the QML module's target path. See Caching compiled QML sources for additional target path differences for compiled-in resources.
qmldir and typeinfo filesBy default, a qmldir file and a typeinfo file will be auto-generated for the QML module being defined. The contents of those files are determined by the various arguments given to
this command, as well as the sources and .qml files added to the backing target. The OUTPUT_DIRECTORY argument determines where the qmldir and
typeinfo files will be written to. If the QML module has a plugin, that plugin will also be created in the same directory as the qmldir file.
If using a statically built Qt, the backing target's .qml files will be scanned during the CMake configure run to determine the imports used by the module and to set up linking relationships (the
NO_IMPORT_SCAN keyword can be given to disable this). When a .qml file is added to or removed from the module, CMake will normally re-run automatically and the relevant files will be re-scanned, since
a CMakeLists.txt file will have been modified. During the course of development, an existing .qml file may add or remove an import or a type. On its own, this would not cause CMake to re-run
automatically, so you should explicitly re-run CMake to force the qmldir file to be regenerated and any linking relationships to be updated.
The backing target's C++ sources are scanned at build time to generate a typeinfo file and a C++ file to register the associated types. The generated C++ file is automatically added to the backing target as a source. This
requires AUTOMOC to be enabled on the target. The project is responsible for ensuring this, usually by setting the CMAKE_AUTOMOC variable to TRUE before calling
qt_add_qml_module(), or by passing in an existing target with the AUTOMOC target property already set to TRUE. It isn't an error to have AUTOMOC disabled on the target, but
the project is then responsible for handling the consequences. This may include having to manually generate the typeinfo file instead of allowing it to be auto-generated with missing details, and adding C++ code to register the
types.
Projects should prefer to use the auto-generated typeinfo and qmldir files where possible. They are easier to maintain and they don't suffer from the same susceptibility to errors that hand-written files do.
Nevertheless, for situations where the project needs to provide these files itself, the auto-generation can be disabled. The NO_GENERATE_QMLDIR option disables the qmldir auto-generation and the
NO_GENERATE_QMLTYPES option disables the typeinfo and C++ type registration auto-generation. If the auto-generated typeinfo file is acceptable, but the project wants to use a different name for that file, it can
override the default name with the TYPEINFO option (but this should not typically be needed).
All .qml, .js, and .mjs files added to the module via the QML_FILES argument will be compiled to bytecode and cached directly in the backing target. This improves load-time
performance of the module. The original uncompiled files are also stored in the backing target's resources, as these may still be needed in certain situations by the QML engine.
The resource path of each file is determined by its path relative to the current source directory (CMAKE_CURRENT_SOURCE_DIR). This resource path is appended to a prefix formed by concatenating the RESOURCE_PREFIX and the target path (but see NO_RESOURCE_TARGET_PATH for an exception to this). Ordinarily, the
project should aim to place .qml files in the same relative location as they would have in the resources. If the .qml file is in a different relative directory to its desired resource path, its
location in the resources needs to be explicitly specified. This is done by setting the QT_RESOURCE_ALIAS source file property, which must be set before the .qml file is added. For example:
set_source_files_properties(path/to/somewhere/MyFrame.qml PROPERTIES
QT_RESOURCE_ALIAS MyFrame.qml
)
qt_add_qml_module(someTarget
URI MyCo.Frames
RESOURCE_PREFIX /my.company.com/imports
QML_FILES
path/to/somewhere/MyFrame.qml
AnotherFrame.qml
)
In the above example, the target path will be MyCo/Frames. After taking into account the source file properties, the two .qml files will be found at the following resource paths:
/my.company.com/imports/MyCo/Frames/MyFrame.qml/my.company.com/imports/MyCo/Frames/AnotherFrame.qmlIn the rare case that you want to override the automatic selection of the qmlcachegen program to be used, you may set the QT_QMLCACHEGEN_EXECUTABLE target property on the module target. For example:
set_target_properties(someTarget PROPERTIES
QT_QMLCACHEGEN_EXECUTABLE qmlcachegen
)
This explicitly selects qmlcachegen as the program to be used, even if better alternatives are available.
Furthermore, you can pass extra arguments to qmlcachegen, by setting the QT_QMLCACHEGEN_ARGUMENTS option. In particular, the --only-bytecode option will turn off compilation of QML script code to
C++. For example:
set_target_properties(someTarget PROPERTIES
QT_QMLCACHEGEN_ARGUMENTS "--only-bytecode"
)
A separate linting target will be automatically created if any .qml files are added to the module via the QML_FILES keyword, or by a later call to qt_target_qml_sources(). The name of the linting target will be the target followed by _qmllint. An all_qmllint target which
depends on all the individual *_qmllint targets is also provided as a convenience.
.js filesJavaScript file names that are intended to be addressed as components should start with an uppercase letter.
Alternatively, you may use lowercase file names and set the source file property QT_QML_SOURCE_TYPE_NAME to the desired type name.
If a QML module has .qml files which provide singleton types, these files need to have their QT_QML_SINGLETON_TYPE source property set to TRUE, to ensure that the singleton
command is written into the qmldir file. This must be done in addition to the QML file containing the pragma Singleton statement.
See qt_target_qml_sources() for an example on how to set the QT_QML_SINGLETON_TYPE property.
If a QML module has .qml files, you can compile them to C++ using qmltc. Unlike bytecode compilation, you have to
explicitly enable qmltc via ENABLE_TYPE_COMPILER argument. In which case, .qml files specified under QML_FILES would be compiled. Files
ending with .js and .mjs are ignored as qmltc does not compile JavaScript code. Additionally, files marked with QT_QML_SKIP_TYPE_COMPILER source file property are also skipped.
By default, qmltc creates lower-case .h and .cpp files for a given .qml file. For example, Foo.qml ends up being compiled into foo.h and
foo.cpp.
The created C++ files are placed into a dedicated .qmltc/<target>/ sub-directory of the BINARY_DIR of the target. These files are then automatically added to the target sources
and compiled as Qt C++ code along with other source files.
While processing QML_FILES, the following source file properties are respected:
QT_QMLTC_FILE_BASENAME: use this source file property to specify a non-default .h and .cpp file name, which might be useful to e.g. resolve conflicting file names (imagine you have main.qml that is being
compiled, but main.h already exists, so #include "main.h" might not do what you expect it to do). QT_QMLTC_FILE_BASENAME is expected to be a file name (without extension), so any preceding directory is ignored. Unlike in the
case of default behavior, the QT_QMLTC_FILE_BASENAME is not lower-cased.QT_QML_SKIP_TYPE_COMPILER: use this source file property to specify that a QML file must be ignored by qmltc.The target specifies the name of the backing target for the QML module. By default, it is created as a shared library if Qt was built as shared libraries, or as a static library otherwise. This choice can be
explicitly overridden with the STATIC or SHARED options.
The plugin target associated with the QML module can be specified using the PLUGIN_TARGET argument. The PLUGIN_TARGET can be the same as the backing target, in which case there will be
no separate backing target. If PLUGIN_TARGET is not given, it defaults to target with plugin appended. For example, a backing target called mymodule would have a default
plugin name of mymoduleplugin. The plugin target's name will be used to populate a plugin line in the generated qmldir file. Therefore, you must not try to
change the plugin's output name by setting target properties like OUTPUT_NAME or any of its related properties.
The backing target and the plugin target (if different) will be created by the command, unless they already exist. Projects should generally let them be created by the command so that they are created as the
appropriate target type. If the backing target is a static library, the plugin will also be created as a static library. If the backing target is a shared library, the plugin will be created as a
module library. If an existing target is passed in and it is an executable target, there will be no plugin. If you intend to always link directly to the backing target and do not need a plugin, it can be disabled
by adding the NO_PLUGIN option. Specifying both NO_PLUGIN and PLUGIN_TARGET is an error.
In certain situations, the project may want to delay creating the plugin target until after the call. The NO_CREATE_PLUGIN_TARGET option can be given in that situation. The project is then expected to call
qt_add_qml_plugin() on the plugin target once it has been created. When NO_CREATE_PLUGIN_TARGET is given, PLUGIN_TARGET must also be provided
to explicitly name the plugin target.
Every QML module must define a URI. It should be specified in dotted URI notation, such as QtQuick.Layouts. It must not contain anything other than alphanumeric or dot characters. Other QML modules
may use this name in import statements to import the module. The URI will be used in the module line of the generated qmldir file. The URI is also used to form the target path by replacing dots with forward slashes.
A QML module must also define a VERSION in the form Major.Minor, where both Major and Minor must be integers. An additional .Patch component may be appended,
but will be ignored. A list of earlier major versions the module provides types for can also optionally be given after the PAST_MAJOR_VERSIONS keyword (see below). See Identified Modules for further in-depth discussion of the module URI and version numbering.
A list of additional major versions the module provides may be given using the PAST_MAJOR_VERSIONS keyword. For each of those versions and each QML file without a QT_QML_SOURCE_VERSIONS setting an
additional entry in the qmldir file will be generated to specify the extra version. Furthermore, the generated module registration code will register the past major versions using
qmlRegisterModule() on the C++ side. The module registration code is automatically generated for your QML module, unless you specify NO_GENERATE_QMLTYPES (but use
of this option is strongly discouraged). Usage of PAST_MAJOR_VERSIONS adds some overhead when your module is imported. You should increment the major version of your module as rarely as possible. Once you can rely
on all QML files importing this module to omit the version in their imports, you can safely omit PAST_MAJOR_VERSIONS. All the QML files will then import the latest version of your module. If you have to support
versioned imports, consider supporting only a limited number of past major versions.
RESOURCE_PREFIX is intended to encapsulate a namespace for the project and will often be the same for all QML modules that the project defines. It should be chosen to avoid clashing with the resource prefix of
anything else used by the project or likely to be used by any other project that might consume it. A good choice is to incorporate the domain name of the organization the project belongs to. A common convention is to append
/imports to the domain name to form the resource prefix. For example:
qt_add_qml_module(someTarget
RESOURCE_PREFIX /my.company.com/imports
...
)
When various files are added to the compiled-in resources, they are placed under a path formed by concatenating the RESOURCE_PREFIX and the target path. For the special case where the backing target is an
executable, it may be desirable to place the module's .qml files and other resources directly under the RESOURCE_PREFIX instead. This can be achieved by specifying the
NO_RESOURCE_TARGET_PATH option, which may only be used if the backing target is an executable.
OUTPUT_DIRECTORY specifies where the plugin library, qmldir and typeinfo files are generated. When this keyword is not given, the default value will be the target path (formed from the
URI) appended to the value of the QT_QML_OUTPUT_DIRECTORY variable. If that variable is not defined, the default depends on the type of backing target.
For executables, the value will be the target path appended to ${CMAKE_CURRENT_BINARY_DIR}, whereas for other targets it will be just ${CMAKE_CURRENT_BINARY_DIR}. When the structure of the source tree
matches the structure of QML module target paths (which is highly recommended), QT_QML_OUTPUT_DIRECTORY often isn't needed. In order to match the structure of the
target paths, you have to call your directories exactly like the segments of your module URI. For example, if your module URI is MyUpperCaseThing.mylowercasething, you need to put this in a directory called
MyUpperCaseThing/mylowercasething/.
The need for specifying the OUTPUT_DIRECTORY keyword should be rare, but if it is used, it is likely that the caller will also need to add to the IMPORT_PATH
to ensure that linting, cached compilation of qml sources, automatic importing of plugins in static builds, and deploying imported QML modules for non-static builds all work
correctly.
By default, qt_add_qml_module() will auto-generate a .cpp file that implements the plugin class named by the CLASS_NAME argument. The generated .cpp file will be
automatically added to the plugin target as a source file to be compiled. If the project wants to provide its own implementation of the plugin class, the NO_GENERATE_PLUGIN_SOURCE option should be given. Where no
CLASS_NAME is provided, it defaults to the URI with dots replaced by underscores, then Plugin appended. Unless the QML module has no plugin, the class name will be recorded as a
classname line in the generated qmldir file.
If the NO_PLUGIN_OPTIONAL keyword is given, then the plugin is recorded in the generated qmldir file as non-optional. If all of a QML module's functionality is implemented in its backing target and
the plugin target is separate, then the plugin can be optional, which is the default and recommended arrangement. The auto-generated plugin source file satisfies this requirement. Where a project provides its own
.cpp implementation for the plugin, that would normally mean the NO_PLUGIN_OPTIONAL keyword is also needed because the plugin will almost certainly contain functionality that the QML module
requires.
Type registration is automatically performed for the backing target's C++ sources that are processed by AUTOMOC. This will generate a typeinfo file in the output
directory, the file name being the target name with .qmltypes appended. This file name can be changed using the TYPEINFO option if desired, but this should not normally be necessary.
The file name is also recorded as a typeinfo entry in the generated qmldir file. Automatic type registration can be disabled using the NO_GENERATE_QMLTYPES
option, in which case no typeinfo file will be generated, but the project will still be expected to generate a typeinfo file and place it in the same directory as the generated qmldir file.
IMPORTS provides a list of other QML modules that this module imports. Each module listed here will be added as an import entry in the generated qmldir
file. If a QML file imports the this module, it also imports all the modules listed under IMPORTS. Optionally, a version can be specified by appending it after a slash, such as QtQuick/2.0. Omitting
the version will cause the greatest version available to be imported. You may only specify the major version, as in QtQuick/2. In that case the greatest minor version available with the given major version will be
imported. Finally, auto may be given as version (QtQuick/auto). If auto is given, the version that the current module is being imported with is propagated to the module to be imported.
Given an entry QtQuick/auto in a module YourModule, if a QML file specifies import YourModule 3.14, this results in importing version 3.14 of QtQuick. For related
modules that follow a common versioning scheme, you should use auto.
OPTIONAL_IMPORTS provides a list of other QML modules that this module may import at run-time. These are not automatically imported by the QML engine when importing the current module, but rather serve as
hints to tools like qmllint. Versions can be specified in the same way as for IMPORTS. Each module listed here will be added as an optional import entry in the generated qmldir file.
DEFAULT_IMPORTS specifies which of the optional imports are the default entries that should be loaded by tooling. One entry should be specified for every group of OPTIONAL_IMPORTS in the module. As
optional imports are only resolved at runtime, tooling like qmllint cannot in general know which of the optional imports should be resolved. To remedy this, you can specify one of the optional imports as the default import;
tooling will then pick it. If you have one optional import that gets used at runtime without any further configuration, that is an ideal candidate for the default import.
DEPENDENCIES provides a list of other QML modules that this module depends on, but doesn't necessarily import. It would typically be used for dependencies that only exist at the C++ level, such as a module
registering a class to QML which is a subclass of one defined in another module. The module version of the dependencies must be specified along with the module name, in the same form as used for IMPORTS and
OPTIONAL_IMPORTS. Each module listed here will be added as a depends entry in the generated qmldir file.
IMPORT_PATH can be used to add to the search paths where other QML modules that this one depends on can be found. The other modules must have their qmldir file under their own target path below one
of the search paths.
SOURCES specifies a list of non-QML sources to be added to the backing target. It is provided as a convenience and is equivalent to adding the sources to the backing target with the built-in
target_sources() CMake command.
QML_FILES lists the .qml, .js and .mjs files for the module. These will be automatically compiled into bytecode
and embedded in the backing target unless the NO_CACHEGEN option is given. The uncompiled file is always stored in the embedded resources of the backing target, even if NO_CACHEGEN is specified. Unless
the NO_LINT option is given, the uncompiled files will also be processed by qmllint via a separate custom build target. The files will also
be used to populate type information in the generated qmldir file. See qt_target_qml_sources() for further details
on the source file properties that can be set on these files or if files need to be added to the backing target after this command has been called.
RESOURCES lists any other files needed by the module, such as images referenced from the QML code. These files will be added as compiled-in resources (see RESOURCE_PREFIX for an explanation of the base point they will be located under). If needed, their relative location can be controlled by setting the
QT_RESOURCE_ALIAS source property, just as for .qml files (see Caching compiled QML sources).
NO_GENERATE_QMLDIR can be given to disable the automatic generation of the qmldir file. This should normally be avoided, but for cases where the project needs to provide its own qmldir
file, this option can be used.
If the backing target is a static library and that static library will be installed, OUTPUT_TARGETS should be given to provide a variable in which to store a list of additional targets that will also need to be
installed. These additional targets are generated internally by qt_add_qml_module() and are referenced by the backing target's linking requirements as part of ensuring that resources are set up and loaded
correctly.
The DESIGNER_SUPPORTED keyword should be given if the QML module supports Qt Quick Designer. When present, the generated qmldir file will contain a designersupported line. See Module Definition qmldir Files for how this affects the way Qt Quick Designer handles the plugin.
The FOLLOW_FOREIGN_VERSIONING keyword relates to base types of your own C++-defined QML types that live in different QML modules. Typically, the versioning scheme of your module does not match that of the module
providing the base types. Therefore, by default all revisions of the base types are made available in any import of your module. If FOLLOW_FOREIGN_VERSIONING is given, the version information attached to the base
types and their properties is respected. So, an import MyModule 2.8 will then only make available versioned properties up to version 2.8 of any base types outside MyModule. This is mostly
useful if you want to keep your module version in sync with other modules you're basing types on. In that case you might want your custom types to not expose properties from a module's base type version greater than the one
being imported.
If a namespace is given with the NAMESPACE keyword, the plugin and registration code will be generated into a C++ namespace of this name.
For static Qt builds, qmlimportscanner is run at configure time to scan the .qml files of a QML module and identify the QML imports it uses (see qt_import_qml_plugins()). For non-static Qt builds, if the target is an executable, a similar scan is performed at build time to provide the information needed by
deployment scripts (see qt_deploy_qml_imports()). Both scans can be disabled by providing the NO_IMPORT_SCAN option. Doing so means the project
takes on the responsibility of ensuring all required plugins are instantiated and linked for static builds. For non-static builds the project must manually work out and deploy all QML modules used by an executable
target.
ENABLE_TYPE_COMPILER can be used to compile .qml files to C++ source code with qmltc.
TYPE_COMPILER_NAMESPACE argument defines a namespace, in which the generated C++ code resides. By default, no namespace is specified for user projects. The code generated from Qt's own sources is put under a
QT_NAMESPACE namespace.
