qt_target_qml_sources | Qt QML 6.4.1

- Qt 6.4
- Qt QML
- qt_target_qml_sources
- Qt 6.4.1 Reference Documentation

# qt_target_qml_sources

This command was introduced in Qt 6.2.

## Synopsis

     qt_target_qml_sources(
         target
         [QML_FILES ...]
         [RESOURCES ...]
         [PREFIX resource_path]
         [OUTPUT_TARGETS out_targets_var]
         [NO_LINT]
         [NO_CACHEGEN]
         [NO_QMLDIR_TYPES]
     )

If versionless commands are disabled, use `qt6_target_qml_sources()` instead. It supports the same set of arguments as this command.

## Description

Note: This command requires CMake 3.19 or later.

`qt_target_qml_sources()` provides the ability to add more files to a QML module after qt_add_qml_module() has been called. Typically, you pass the set of `.qml` files and resources to qt_add_qml_module() directly, but in some cases, it may be desirable, or even necessary, to add files after qt_add_qml_module() has been called. For example, you may wish to add files conditionally based on an `if` statement expression, or from subdirectories that will only be added if certain criteria are met. You might want to add a set of files with different characteristics to the others, such as a different resource prefix, or with linting and bytecode compilation disabled. The `qt_target_qml_sources()` command enables these scenarios.

## Arguments

The `target` must be the backing target of a QML module, or if the QML module has no separate backing target, it must be the module's plugin target.

`QML_FILES` is a list of `.qml`, `.js` and `.mjs` files to be added to the QML module. This option has exactly the same effect as the `QML_FILES` option of the qt_add_qml_module() command, including the automatic compilation to bytecode and lint processing.

The `NO_CACHEGEN` and `NO_LINT` options also have the same effect as they do for qt_add_qml_module(). They disable the bytecode compilation and lint processing for the files listed with `QML_FILES`. This behavior can also be specified just for individual files using source file properties.

`NO_QMLDIR_TYPES` prevents the `QML_FILES` from being added as types to the generated qmldir file.

`RESOURCES` has exactly the same effect as the `RESOURCES` option of the qt_add_qml_module() command. It provides a list of files to be added to the `target` as ordinary resources. These files are typically things like images, shaders, etc. that the QML code refers to in some way.

Files added to the module via `QML_FILES` or `RESOURCES` will be placed under the same resource prefix and target path as they would if they were added by the qt_add_qml_module() command. This can be overridden by providing a different location with the `PREFIX` option. The value following the `PREFIX` keyword will be used directly, without appending any target path. The final resource path of each file will be the prefix, plus the path of the file below the `CMAKE_CURRENT_SOURCE_DIR`. The QT_RESOURCE_ALIAS source file property can also be used to override that relative path.

     qt_add_qml_module(backing
         URI Example
         VERSION 1.0
         RESOURCE_PREFIX /my.company.com/imports
     )

     qt_target_qml_sources(backing
         QML_FILES special/First.qml
         RESOURCES icons/logo.png
     )

     qt_target_qml_sources(backing
         PREFIX /other.company.com/debugging
         QML_FILES Inspector.qml
     )

In the above example, the `backing` target's resources will end up with the following contents:

- `/my.company.com/imports/Example/special/First.qml`
- `/my.company.com/imports/Example/icons/logo.png`
- `/other.company.com/debugging/Inspector.qml`

`OUTPUT_TARGETS` is also analogous to the same option for qt_add_qml_module(). Use it to specify the name of a variable in which to store any additional targets created for static builds. If the `target` will be installed, these additional targets will also need to be installed to satisfy linking requirements.

## Source File Properties

A number of source file properties can be used to influence how each individual `.qml` file is treated at various points in the QML module processing. These override any higher level options specified in calls to `qt_target_qml_sources()` or qt_add_qml_module(). All of these properties need to be set before the files are added with either of those two commands.

`QT_QML_SKIP_QMLLINT` can be set to `TRUE` on a source file to prevent it from being included in the automatic qmllint processing. By default, all `.qml` files will be included in the target's lint run, but this option can be used to exclude specific files.

`QT_QML_SKIP_CACHEGEN` does a similar thing, preventing a source file from being compiled to byte code when this property is set to `TRUE`. Note that the file will still be added to the `target` as a resource in uncompiled form (see Caching compiled QML sources).

Set the `QT_QML_SKIP_QMLDIR_ENTRY` source file property to `TRUE` to prevent that `.qml` file from being added as a type to the QML module's typeinfo file (see Auto-generating `qmldir` and typeinfo files). This would normally only be used for a file that does not expose a public type, such as a private JS file.

By default, when generating the `qmldir` file, a single type entry will be generated for each `.qml` file that provides a type. It will be given a version number `X.0` where `X` is the major version of the QML module. If the QML module has any `PAST_MAJOR_VERSIONS` set, the same pattern will be applied to those too, appending `X.0` for each past major version `X`. For situations where a file needs to provide type entries for a different set of versions instead (e.g. it was first added in a minor patch version after the `.0` release), specify those versions in the source file's `QT_QML_SOURCE_VERSIONS` property. One type entry will be created for each version.

If the type that a `.qml` file provides is a singleton, set its `QT_QML_SINGLETON_TYPE` property to `TRUE`. Similarly, the file's `QT_QML_INTERNAL_TYPE` source property can be set to `TRUE` to indicate that the type it provides is an internal one. The name of the type itself can also be overridden using the `QT_QML_SOURCE_TYPENAME` property. All three of these will be reflected in the file's type entries in the generated `qmldir` file.

All files listed with `QML_FILES` or `RESOURCES` will be added to the `target`'s resources. Their location in the resources consists of a base point and a relative path. The base point defaults to the concatenation of the QML module's resource prefix and its target path, but these can be overridden with the PREFIX argument. The relative path will default to the path of the file relative to the `target`'s `SOURCE_DIR` target property. This relative path can be overridden by setting the `QT_RESOURCE_ALIAS` property on the source file. This is commonly used to collect files from different directories and have them appear in the resources under a common location.

     set_source_files_properties(nested/way/down/File.qml PROPERTIES
         QT_RESOURCE_ALIAS File.qml
     )
     set_source_files_properties(TemplateFile.qml PROPERTIES
         QT_RESOURCE_ALIAS templates/File.qml
         QT_QML_SKIP_QMLDIR_ENTRY TRUE
         QT_QML_SKIP_QMLLINT TRUE
         QT_QML_SKIP_CACHEGEN TRUE
     )
     set_source_files_properties(FunnySingleton.qml PROPERTIES
         QT_QML_SINGLETON_TYPE TRUE
     )
     qt_add_qml_module(qt_target_qml_sources_example
         URI Example
         VERSION 2.3
         RESOURCE_PREFIX /my.company.com/imports
         QML_FILES
             nested/way/down/File.qml
             TemplateFile.qml
             FunnySingleton.qml
     )

     set_source_files_properties(some_old_thing.qml PROPERTIES
         QT_QML_SOURCE_VERSIONS "1.1;2.0"
         QT_QML_SOURCE_TYPENAME OldThing
     )
     set_source_files_properties(../../../images/button-types.png PROPERTIES
         QT_RESOURCE_ALIAS button-types.png
     )
     qt_target_qml_sources(qt_target_qml_sources_example
         QML_FILES some_old_thing.qml
         RESOURCES
             ../../../images/button-types.png
             doc/README.txt
     )

In the above example, the `qt_target_qml_sources_example` target's resources will end up with the following contents:

- `/my.company.com/imports/Example/File.qml`
- `/my.company.com/imports/Example/FunnySingleton.qml`
- `/my.company.com/imports/Example/templates/File.qml`
- `/my.company.com/imports/Example/some_old_thing.qml`
- `/my.company.com/imports/Example/button-types.png`
- `/my.company.com/imports/Example/doc/README.txt`

The generated `qmldir` file will contain the following type entries:

     File 2.0 File.qml
     singleton FunnySingleton 2.0 FunnySingleton.qml
     OldThing 1.1 some_old_thing.qml
     OldThing 2.0 some_old_thing.qml

Note: The source FunnySingleton.qml file must already contain the `pragma Singleton` statement. Setting the `QT_QML_SINGLETON_TYPE` source property does not automatically generate the pragma.

     pragma Singleton
     import QtQml

     QtObject {}