diff options
Diffstat (limited to 'src/qml/doc/src/cmake')
| -rw-r--r-- | src/qml/doc/src/cmake/cmake-properties.qdoc | 229 | ||||
| -rw-r--r-- | src/qml/doc/src/cmake/cmake-variables.qdoc | 76 | ||||
| -rw-r--r-- | src/qml/doc/src/cmake/policy/qtp0001.qdoc | 39 | ||||
| -rw-r--r-- | src/qml/doc/src/cmake/policy/qtp0004.qdoc | 34 | ||||
| -rw-r--r-- | src/qml/doc/src/cmake/policy/qtp0005.qdoc | 42 | ||||
| -rw-r--r-- | src/qml/doc/src/cmake/qt_add_qml_module.qdoc | 762 | ||||
| -rw-r--r-- | src/qml/doc/src/cmake/qt_add_qml_plugin.qdoc | 120 | ||||
| -rw-r--r-- | src/qml/doc/src/cmake/qt_deploy_qml_imports.qdoc | 116 | ||||
| -rw-r--r-- | src/qml/doc/src/cmake/qt_generate_deploy_qml_app_script.qdoc | 177 | ||||
| -rw-r--r-- | src/qml/doc/src/cmake/qt_generate_foreign_qml_types.qdoc | 77 | ||||
| -rw-r--r-- | src/qml/doc/src/cmake/qt_import_qml_plugins.qdoc | 55 | ||||
| -rw-r--r-- | src/qml/doc/src/cmake/qt_query_qml_module.qdoc | 213 | ||||
| -rw-r--r-- | src/qml/doc/src/cmake/qt_target_compile_qml_to_cpp.qdoc | 14 | ||||
| -rw-r--r-- | src/qml/doc/src/cmake/qt_target_qml_sources.qdoc | 206 |
14 files changed, 2160 insertions, 0 deletions
diff --git a/src/qml/doc/src/cmake/cmake-properties.qdoc b/src/qml/doc/src/cmake/cmake-properties.qdoc new file mode 100644 index 0000000000..a2ca59efc8 --- /dev/null +++ b/src/qml/doc/src/cmake/cmake-properties.qdoc @@ -0,0 +1,229 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\group cmake-global-properties-qtqml +\title CMake Global Properties in Qt6 Qml + +\l{CMake Command Reference#Qt6::Qml}{CMake Commands} know about the following +global CMake properties: + +\sa{CMake Property Reference} +*/ + + +/*! +\page cmake-global-property-qt-qmllinter-targets-folder.html +\ingroup cmake-properties-qtqml +\ingroup cmake-global-properties-qtqml + +\title QT_QMLLINTER_TARGETS_FOLDER + +\brief Sets the FOLDER property for targets that belong to the QML linter. + +\cmakepropertysince 6.5 +\preliminarycmakeproperty + +Name of the \l FOLDER for targets that are related to the QML linter. + +By default, this property is set to \c{QmlLinter}. + +This property only has an effect if CMake's \l USE_FOLDERS property is \c{ON}. + +You can enable folder support by calling +\l{qt6_standard_project_setup}{qt_standard_project_setup}. +*/ + + +/*! +\group cmake-source-file-properties-qtqml +\title CMake Source File Properties in Qt6 Qml + +\l{CMake Command Reference#Qt6::Qml}{CMake Commands} know about the following +CMake source file properties: + +\sa{CMake Property Reference} +*/ + + +/*! +\page cmake-source-file-property-qt-qml-internal-type.html +\ingroup cmake-source-file-properties-qtqml + +\title QT_QML_INTERNAL_TYPE + +\summary {Marks a QML file as providing an internal type.} + +\cmakepropertysince 6.2 + +Set this property to \c TRUE to indicate that the \c{.qml} file provides an internal type. + +\sa{qml-source-file-properties}{qt_target_qml_sources} +*/ + + +/*! +\page cmake-source-file-property-qt-qml-singleton-type.html +\ingroup cmake-source-file-properties-qtqml + +\title QT_QML_SINGLETON_TYPE + +\summary {Marks a QML file as providing a singleton type.} + +\cmakepropertysince 6.2 + +A \c{.qml} file that provides a singleton type needs to have its \c QT_QML_SINGLETON_TYPE source +property set to \c TRUE to ensure that the singleton command is written into the +\l{Module Definition qmldir Files}{qmldir} file. +This must be done in addition to the QML file containing the \c {pragma Singleton} statement. +The source property must be set before \l{qt_add_qml_module}{creating} the module the +singleton belongs to. + +See \l{qt_target_qml_sources_example}{qt_target_qml_sources()} for an example on +how to set the \c QT_QML_SINGLETON_TYPE property. + +\sa{qml-source-file-properties}{qt_target_qml_sources} +*/ + + +/*! +\page cmake-source-file-property-qt-qml-skip-cachegen.html +\ingroup cmake-source-file-properties-qtqml + +\title QT_QML_SKIP_CACHEGEN + +\summary {Excludes a file from being compiled to byte code.} + +\cmakepropertysince 6.2 + +Set this property to \c TRUE to prevent the \c{.qml} file from being compiled to byte code. +The file will still be added to the \c target as a resource in uncompiled form +(see \l{qmlcachegen-auto}{Caching compiled QML sources}). + +\sa{qml-source-file-properties}{qt_target_qml_sources} +*/ + + +/*! +\page cmake-source-file-property-qt-qml-skip-qmldir-entry.html +\ingroup cmake-source-file-properties-qtqml + +\title QT_QML_SKIP_QMLDIR_ENTRY + +\summary {Excludes a file from being added as a type to the QML module's typeinfo file.} + +\cmakepropertysince 6.2 + +Set this property to \c TRUE to prevent +the \c{.qml} file from being added as a type to the QML module's typeinfo file +(see \l{qmldir-autogeneration}{Auto-generating \c{qmldir} and typeinfo files}). + +\sa{qml-source-file-properties}{qt_target_qml_sources} +*/ + + +/*! +\page cmake-source-file-property-qt-qml-skip-qmllint.html +\ingroup cmake-source-file-properties-qtqml + +\title QT_QML_SKIP_QMLLINT + +\summary {Prevents a file from being included in automatic qmllint processing.} + +\cmakepropertysince 6.2 + +Set this property to \c TRUE to prevent the file from being included in +\l{qmllint-auto}{automatic qmllint processing}. + +\sa{qml-source-file-properties}{qt_target_qml_sources} +*/ + + +/*! +\page cmake-source-file-property-qt-qml-source-typename.html +\ingroup cmake-source-file-properties-qtqml + +\title QT_QML_SOURCE_TYPENAME + +\summary {Overrides the type name provided by the file.} + +\cmakepropertysince 6.2 + +Use this property to override the \c QML type name provided by this file. + +\sa{qml-source-file-properties}{qt_target_qml_sources} +*/ + + +/*! +\page cmake-source-file-property-qt-qml-source-versions.html +\ingroup cmake-source-file-properties-qtqml + +\title QT_QML_SOURCE_VERSIONS + +\summary {Specifies a custom set of versions for a type.} + +\cmakepropertysince 6.2 + +When the file needs to provide type entries for a custom set of versions, +for example when the QML types were first introduced in a minor patch +version after the \c{.0} release, specify those versions using this property. + +\sa{qml-source-file-properties}{qt_target_qml_sources} +*/ + + +/*! +\page cmake-source-file-property-qt-qmltc-file-basename.html +\ingroup cmake-source-file-properties-qtqml + +\title QT_QMLTC_FILE_BASENAME + +\summary {Specifies a non-default .h and .cpp file name.} + +\cmakepropertysince 6.3 +\preliminarycmakeproperty + +Use this property to specify a non-default \c .h and \c .cpp file name, which helps to resolve +conflicting file names. + +\sa{qmltc-cmake} +*/ + +/*! +\page cmake-source-file-property-qt-qml-skip-type-compiler.html +\ingroup cmake-source-file-properties-qtqml + +\title QT_QML_SKIP_TYPE_COMPILER + +\summary {Excludes a file from being compiled to C++ using qmltc.} + +\cmakepropertysince 6.4 +\preliminarycmakeproperty + +Set this property to \c TRUE to prevent the \c{.qml} file from being compiled to +C++ during qmltc compilation. + +\sa{qmltc-cmake} +*/ + +/*! +\page cmake-source-file-property-qt-qml-generate-java-class.html +\ingroup cmake-source-file-properties-qtqml +\ingroup cmake-android-build-properties + +\title QT_QML_GENERATE_JAVA_CLASS + +\summary {Marks a QML file for Java code generation.} + +\cmakepropertysince 6.8 +When using QML as a \l {Android: View} in Android via \l QtQuickView, you can choose +the QML components to make available as generated Java classes usable from Android code. +To mark a \c {.qml} file for code generation, set its \c QT_QML_GENERATE_JAVA_CLASS +source property to \c TRUE. The source property must be set before +\l {qt_add_qml_module}{creating} the module. The file should start with an uppercase +letter and define a QML component. This property is valid only if +\l QT_ANDROID_GENERATE_JAVA_QML_COMPONENTS is defined. + +\sa {Naming Custom QML Object Types} +*/ diff --git a/src/qml/doc/src/cmake/cmake-variables.qdoc b/src/qml/doc/src/cmake/cmake-variables.qdoc new file mode 100644 index 0000000000..de984c88ef --- /dev/null +++ b/src/qml/doc/src/cmake/cmake-variables.qdoc @@ -0,0 +1,76 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\group cmake-variables-qtqml +\title CMake Global Variables in Qt6 Qml + +\l{CMake Command Reference#Qt6::Qml}{CMake Commands} know about the following +global CMake variables: + +*/ + +/*! +\page cmake-variable-qt-qml-output-directory.html +\ingroup cmake-variables-qtqml + +\title QT_QML_OUTPUT_DIRECTORY + +\brief Base output directory below which QML modules will be created by default. + +The \l{qt6_add_qml_module}{qt6_add_qml_module()} command accepts an +\c OUTPUT_DIRECTORY argument which specifies where the QML module's \c qmldir +file, typeinfo file and plugin library will be created. When that argument is +not used, the default value is based on the \c QT_QML_OUTPUT_DIRECTORY variable, +if it is set. If \c QT_QML_OUTPUT_DIRECTORY is not set, the default value +depends on the type of backing target (see the +\l{qt6_add_qml_module#OUTPUT_DIRECTORY}{OUTPUT_DIRECTORY} documentation for +details). + +When \c QT_QML_OUTPUT_DIRECTORY is set, the default output directory will be +formed by appending the QML module's \e{target path} (which is based on the +module URI) to \c QT_QML_OUTPUT_DIRECTORY. +The \c QT_QML_OUTPUT_DIRECTORY will also be added to the import path of the +\c qmllint and \c qmlcachegen tooling targets, allowing them to find other QML +modules under the same base location. This allows the project to use a source +directory structure that doesn't exactly match the URI structure of the QML +modules, or to merge sets of QML modules under a common base point. +*/ + +/*! +\page cmake-variable-qt-qml-generate-qmlls-ini.html +\ingroup cmake-variables-qtqml + +\title QT_QML_GENERATE_QMLLS_INI + +\brief Enables autogeneration of .qmlls.ini files for \QMLLS. +\cmakevariablesince 6.7 + +\c QT_QML_GENERATE_QMLLS_INI is a boolean that describes whether +\l{qt6_add_qml_module}{qt6_add_qml_module()} calls generate \c{.qmlls.ini} files inside +the \b{source folder}, into each subdirectory with a CMakeLists.txt file creating a QML module. +If \c{.qmlls.ini} files already exist there, then they are overwritten. + +\note Using \c QT_QML_GENERATE_QMLLS_INI requires a CMake version >= 3.19. + +These \c{.qmlls.ini} files contain the path to the last configured build directory, +and is needed by \l{\QMLLS Reference}{\QMLLS} to find user defined modules. See also +\l{\QMLLS Reference}{\QMLLS} about the other ways of passing build folders to \QMLLS. + + +As this variable is used for IDE integration, it should normally not be set in a project itself, but +passed to CMake via an IDE or manually by passing +\badcode +-DQT_QML_GENERATE_QMLLS_INI=ON +\endcode +to the cmake executable. + +\warning The files generated by \c QT_QML_GENERATE_QMLLS_INI are only valid for the current +configuration and should be ignored by your version control system. For Git, add \tt{**\/.qmlls.ini} +to your top-level project \c{.gitignore}, for example. +The globbing is required because .qmlls.ini files are generated in \e{all source +subdirectories} that define QML Modules. + +*/ + + diff --git a/src/qml/doc/src/cmake/policy/qtp0001.qdoc b/src/qml/doc/src/cmake/policy/qtp0001.qdoc new file mode 100644 index 0000000000..a4e54ed1ae --- /dev/null +++ b/src/qml/doc/src/cmake/policy/qtp0001.qdoc @@ -0,0 +1,39 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-cmake-policy-qtp0001.html +\ingroup qt-cmake-policies + +\title QTP0001 +\keyword qt_cmake_policy_qtp0001 + +\summary {':/qt/qml/' is the default resource prefix for QML modules.} + +This policy was introduced in Qt 6.5. It changes where +\l{qt_add_qml_module}{qt_add_qml_module()} stores QML resources in +the resource system. + +Enabling this policy ensures that your QML module is placed under +a default \l {QML Import Path}{import path}, and its types can be +found without manual calls to \l QQmlEngine::addImportPath. + +The \c OLD behavior of this policy is that, the \c RESOURCE_PREFIX argument for +\c{qt_add_qml_module()} defaults to \c{":/"}. + +The \c NEW behavior of this policy is that the \c RESOURCE_PREFIX argument +for \c{qt_add_qml_module()} defaults to \c{":/qt/qml/"}. The new behavior +ensures that modules are put into the \l{QML Import Path} and can be +found without further setup. + +Qt 6.5 issues warnings if you do not pass any of the following arguments to the +\c qt_add_qml_module command: \c RESOURCE_PREFIX, \c NO_RESOURCE_TARGET_PATH. +Use the \l qt_policy command to suppress the warning by explicitly setting +the policy to \c OLD or \c NEW. + +\qtpolicydeprecatedbehavior + +\sa qt_policy, {qt6_standard_project_setup}{qt_standard_project_setup()}, + qt_cmake_policies, qt_add_qml_module + +*/ diff --git a/src/qml/doc/src/cmake/policy/qtp0004.qdoc b/src/qml/doc/src/cmake/policy/qtp0004.qdoc new file mode 100644 index 0000000000..9d3428e52b --- /dev/null +++ b/src/qml/doc/src/cmake/policy/qtp0004.qdoc @@ -0,0 +1,34 @@ +// Copyright (C) 2024 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-cmake-policy-qtp0004.html +\ingroup qt-cmake-policies + +\title QTP0004 +\keyword qt_cmake_policy_qtp0004 + +\summary {Extra directories with QML files in a QML module need extra qmldir files.} + +This policy was introduced in Qt 6.8. It causes the build system to generate +an extra qmldir file for each additional directory that contains QML files in +a QML module. + +Enabling this policy ensures that the implicit import of each of the QML +components in your module is the same as the module itself. This means that +all the components can see each other without explicitly importing the module. + +The \c OLD behavior of this policy is that a qmldir file is only generated for +the root directory of a module. + +The \c NEW behavior of this policy is that for each directory with QML files in +a module a separate qmldir file is generated. + +Qt 6.8 issues warnings if you do not explicitly set the policy. + +\qtpolicydeprecatedbehavior + +\sa qt_policy, {qt6_standard_project_setup}{qt_standard_project_setup()}, + qt_cmake_policies, qt_add_qml_module + +*/ diff --git a/src/qml/doc/src/cmake/policy/qtp0005.qdoc b/src/qml/doc/src/cmake/policy/qtp0005.qdoc new file mode 100644 index 0000000000..25d5175789 --- /dev/null +++ b/src/qml/doc/src/cmake/policy/qtp0005.qdoc @@ -0,0 +1,42 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-cmake-policy-qtp0005.html +\ingroup qt-cmake-policies + +\title QTP0005 +\keyword qt_cmake_policy_qtp0005 + +\summary {qt_add_qml_module's DEPENDENCIES argument accepts targets} + +This policy was introduced in Qt 6.8. It allows passing targets to +\l{qt_add_qml_module}{qt_add_qml_module()} \c DEPENDENCIES, \c IMPORTS, \c +OPTIONAL_IMPORTS and \c DEFAULT_IMPORTS. + +Enabling this policy means that the arguments which are passed to the key words +can be prefixed with TARGET, and are then treated as a target name. + +The \c OLD behavior of this policy is that the "TARGET name" is treated as two +URIs, "TARGET" and "name". + +The \c NEW behavior of this policy is that \c TARGET is considered a keyword, +and the URI is extracted from the target which follows next. It is a hard error +if the name following \c TARGET does not name a target, or if that target does +not correspond to a QML module. + +In both the \c NEW and the \c OLD behavior it is possible to specify a module +version by appending a slash and the version. See +\l{Declaring module dependencies} for more details. + +Qt 6.8 issues warnings if you pass a URI to \c DEPENDENCIES which coincides +with a target name. +Use the \l qt_policy command to suppress the warning by explicitly setting +the policy to \c OLD or \c NEW. + +\qtpolicydeprecatedbehavior + +\sa qt_policy, {qt6_standard_project_setup}{qt_standard_project_setup()}, + qt_cmake_policies, qt_add_qml_module + +*/ diff --git a/src/qml/doc/src/cmake/qt_add_qml_module.qdoc b/src/qml/doc/src/cmake/qt_add_qml_module.qdoc new file mode 100644 index 0000000000..63f9707d4d --- /dev/null +++ b/src/qml/doc/src/cmake/qt_add_qml_module.qdoc @@ -0,0 +1,762 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-add-qml-module.html +\ingroup cmake-commands-qtqml + +\title qt_add_qml_module +\target qt6_add_qml_module + +\brief Defines a QML module. + +\cmakecommandsince 6.2 + +\section1 Synopsis + +\badcode +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] + [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] + [QMLTC_EXPORT_DIRECTIVE export_macro] + [QMLTC_EXPORT_FILE_NAME header_defining_export_macro] + +) + +\endcode + +\versionlessCMakeCommandsNote qt6_add_qml_module() + +See \l {Building a QML application} and \l {Building a reusable QML module} +for examples that define QML modules. + +See \l {QT_QML_GENERATE_QMLLS_INI} for configuring your project such that information about +QML modules is exposed to the \l{QML Language Server}. + +\section1 Description + +This command defines a QML module that can consist of C++ sources, \c{.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 \c{.qml} sources, resource embedding, linting checks, and +auto-generation of some key module files. + +\section2 Target Structure + +A QML module can be structured in a few different ways. The following scenarios +are the typical arrangements: + +\section3 Separate backing and plugin targets + +This is the recommended arrangement for most QML modules. All of the module's +functionality is implemented in the \e backing target, which is given as the +first command argument. C++ sources, \c{.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, \c{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 \c{MyThings.Panels}. The call to \c{qt_add_qml_module()} +would be in the \c{CMakeLists.txt} file shown. + +\badcode +src + +-- MyThings + +-- Panels + +-- CMakeLists.txt +\endcode + +A separate \e 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 +\l{Module Definition qmldir Files}{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 \c 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 +\l{NO_GENERATE_PLUGIN_SOURCE} and usually the \l{NO_PLUGIN_OPTIONAL} options +will be needed. + +The \c STATIC QML modules also generate the static QML plugins if +\c NO_PLUGIN is not specified. Targets that import such \c STATIC QML modules +also need to explicitly link to corresponding QML plugins. + +\note +When using static linking, it might be necessary to use +\l {Q_IMPORT_QML_PLUGIN} to ensure that the QML plugin is correctly linked. + +\section3 Plugin target with no backing target + +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 \c PLUGIN_TARGET keyword must be used, with the \c target repeated as the +plugin target name. For example: + +\badcode +qt_add_qml_module(someTarget + PLUGIN_TARGET someTarget + ... +) +\endcode + +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. + +\section3 Executable as a QML module + +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 \c{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 +\c{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 \l{qmlcachegen-auto}{Caching compiled QML sources} for additional target +path differences for compiled-in resources. + + +\target qmldir-autogeneration +\section2 Auto-generating \c{qmldir} and typeinfo files + +By default, a \l{Module Definition qmldir Files}{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 \c{.qml} files added to the backing target. +The \l OUTPUT_DIRECTORY argument determines where the \c 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 \c qmldir file. + +If \l{QTP0004} policy is set to \c NEW, for each further directory that contains +\c{.qml} files another \c qmldir file is generated. These extra \c qmldir files +merely redirect to the module's base directory via a \c prefer directive. This +is so that all the QML components in a module can access each other, no matter +which directory they are stored in. + +If using a statically built Qt, the backing target's \c{.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 \c{NO_IMPORT_SCAN} keyword +can be given to disable this). When a \c{.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 \c{CMakeLists.txt} file will have +been modified. During the course of development, an existing \c{.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 +\c 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 \c AUTOMOC to be enabled on the target. The project is +responsible for ensuring this, usually by setting the \c CMAKE_AUTOMOC variable +to \c TRUE before calling \c qt_add_qml_module(), or by passing in an existing +target with the \c AUTOMOC target property already set to \c TRUE. It isn't an +error to have \c 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 \c 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 \c NO_GENERATE_QMLDIR option disables the +\c qmldir auto-generation and the \c 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 \c TYPEINFO option (but +this should not typically be needed). + +\target qmlcachegen-auto +\section2 Caching compiled QML sources + +All \c{.qml}, \c{.js}, and \c{.mjs} files added to the module via the +\c 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 (\c CMAKE_CURRENT_SOURCE_DIR). This resource path is +appended to a prefix formed by concatenating the \l{RESOURCE_PREFIX} and +the target path (but see \l NO_RESOURCE_TARGET_PATH for an exception to this). + +If \l{QTP0001} policy is set to \c NEW, the \l{RESOURCE_PREFIX} defaults +to \c{/qt/qml/} which is the default import path of the QML engine. +This ensures that modules are put into the \l{QML Import Path} and can be +found without further setup. + +Ordinarily, the project should aim to place \c{.qml} files in +the same relative location as they would have in the resources. If the \c{.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 \c QT_RESOURCE_ALIAS source file property, which must be set before +the \c{.qml} file is added. For example: + +\badcode +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 +) +\endcode + +In the above example, the target path will be \c{MyCo/Frames}. After +taking into account the source file properties, the two \c{.qml} files will be +found at the following resource paths: + +\list +\li \c{/my.company.com/imports/MyCo/Frames/MyFrame.qml} +\li \c{/my.company.com/imports/MyCo/Frames/AnotherFrame.qml} +\endlist + +In the rare case that you want to override the automatic selection of the +qmlcachegen program to be used, you may set the \c QT_QMLCACHEGEN_EXECUTABLE +target property on the module target. For example: + +\badcode +set_target_properties(someTarget PROPERTIES + QT_QMLCACHEGEN_EXECUTABLE qmlcachegen +) +\endcode + +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 +\c QT_QMLCACHEGEN_ARGUMENTS option. In particular, the \c --only-bytecode +option will turn off compilation of QML script code to C++. For example: + +\badcode +set_target_properties(someTarget PROPERTIES + QT_QMLCACHEGEN_ARGUMENTS "--only-bytecode" +) +\endcode + +Another important argument is \c{--direct-calls}. You can use it to enable the +direct mode of \l{The QML script compiler} in case the Qt Quick Compiler +Extensions are installed. If the extensions are not installed, the argument is +ignored. There is a shorthand called \c {QT_QMLCACHEGEN_DIRECT_CALLS} for it. + +\badcode +set_target_properties(someTarget PROPERTIES + QT_QMLCACHEGEN_DIRECT_CALLS ON +) +\endcode + +Finally, the \c --verbose argument can be used to see diagnostic output from +qmlcachegen: + +\badcode +set_target_properties(someTarget PROPERTIES + QT_QMLCACHEGEN_ARGUMENTS "--verbose" +) +\endcode + +With this flag set, qmlcachegen will output warnings for each function it +cannot compile to C++. Some of these warnings will point to problems in your +QML code and some will tell you that certain features of the QML language are +not implemented in the C++ code generator. In both cases, qmlcachegen will +still generate byte code for such functions. If you want to see only the +problems in your QML code, you should use qmllint and the targets generated +for it instead. + +\target qmllint-auto +\section2 Linting QML sources + +A separate linting target will be automatically created if any \c{.qml} files +are added to the module via the \c QML_FILES keyword, or by a later call to +\l{qt6_target_qml_sources}{qt_target_qml_sources()}. The name of the linting +target will be the \c target followed by \c{_qmllint}. An \c{all_qmllint} +target which depends on all the individual \c{*_qmllint} targets is also +provided as a convenience. + +\target qml-naming-js-files +\section2 Naming conventions for \c{.js} files + +JavaScript 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 \l QT_QML_SOURCE_TYPENAME to the desired type name. + +\target qml-cmake-singletons +\section2 Singletons + +If a QML module has \c{.qml} files which provide singleton types, these files +need to have their \c QT_QML_SINGLETON_TYPE source property set to \c TRUE, to +ensure that the \c singleton command is written into the +\l{Module Definition qmldir Files}{qmldir} file. This must be done in addition +to the QML file containing the \c {pragma Singleton} statement. +The source property must be set before creating the module the +singleton belongs to. + +See \l{qt_target_qml_sources_example}{qt_target_qml_sources()} for an example on +how to set the \c QT_QML_SINGLETON_TYPE property. + +\target qmltc-cmake +\section2 Compiling QML to C++ with QML type compiler + +\note The \l{QML type compiler} \c{qmltc} does not guarantee that the generated +C++ stays API-, source- or binary-compatible between past or future versions, +even patch versions. +Furthermore, qmltc-compiled apps using Qt's QML modules will require linking +against private Qt API, see also +\l{QML type compiler#compiling-qml-code-with-qmltc}{Compiling QML code with qmltc}. + + +If a QML module has \c{.qml} files, you can compile them to C++ using \l{QML +type compiler}{qmltc}. Unlike \l{qmlcachegen-auto}{bytecode compilation}, you +have to explicitly enable qmltc via \l{ENABLE_TYPE_COMPILER} argument. In which +case, \c{.qml} files specified under \c{QML_FILES} would be compiled. Files +ending with \c{.js} and \c{.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 \c{.h} and \c{.cpp} files for a given +\c{.qml} file. For example, \c{Foo.qml} ends up being compiled into \c{foo.h} +and \c{foo.cpp}. + +The created C++ files are placed into a dedicated \c{.qmltc/<target>/} +sub-directory of the \c BINARY_DIR of the \c 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: +\list + \li \c{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. + \li \c{QT_QML_SKIP_TYPE_COMPILER}: use this source file property to + specify that a QML file must be ignored by qmltc. +\endlist + +\section1 Arguments + +\section2 Required arguments + +The \c 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 \c STATIC or \c SHARED options. + +Every QML module must define a \c URI. It should be specified in dotted URI +notation, such as \c{QtQuick.Layouts}. Each segment must be a well-formed +ECMAScript Identifier Name. This means, for example, the segments +must not start with a number and they must not contain \e{-} (minus) +characters. As the \c URI will be translated into directory names, you +should restrict it to alphanumeric characters of the latin alphabet, +underscores, and dots. Other QML modules may use this name in +\l{qtqml-syntax-imports.html}{import statements} to import the module. The +\c URI will be used in the \c module line of the generated +\l{Module Definition qmldir Files}{qmldir} file. The \c URI is also used to +form the \e{target path} by replacing dots with forward slashes. + +See \l{qtqml-modules-identifiedmodules.html}{Identified Modules} for further +in-depth discussion of the module URI. + +\section2 Versions + +A QML module can also define a \c VERSION in the form \c{Major.Minor}, where +both \c Major and \c Minor must be integers. An additional \c{.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 +\c PAST_MAJOR_VERSIONS keyword (see below). +See \l{qtqml-modules-identifiedmodules.html}{Identified Modules} for further +in-depth discussion of version numbering, +\l{Registering past major versions} for registering past major versions, and +\l{Keeping module versions in sync} for keeping module versions in sync. + +If you don't need versions you should omit the \c VERSION argument. It defaults +to the highest possible version. Internal versioning of QML modules has some +fundamental flaws. You should use an external package management mechanism to +manage different versions of your QML modules. + +\section2 Adding sources and resources to the module + +\c 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 \c{target_sources()} CMake command. + +\c QML_FILES lists the \c{.qml}, \c{.js} and \c{.mjs} files for the module. +These will be automatically \l{qmlcachegen-auto}{compiled into bytecode} and +embedded in the backing target unless the \c NO_CACHEGEN option is given. +The uncompiled file is always stored in the embedded resources of the backing +target, even if \c NO_CACHEGEN is specified. Unless the \c NO_LINT option is +given, the uncompiled files will also be +\l{Linting QML sources}{processed by \c qmllint} via a separate custom build +target. The files will also be used to populate type information in the +generated \l{Module Definition qmldir Files}{qmldir} file by default. +\c NO_GENERATE_QMLDIR can be given to disable the automatic generation of the +\c qmldir file. This should normally be avoided, but for cases where the +project needs to provide its own \c qmldir file, this option can be used. + +\note See \l{qt6_target_qml_sources}{qt_target_qml_sources()} for further details on +how to add qmlfiles after \c qt_add_qml_module() was 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. +Furthermore, files added with \l{qt6_target_qml_sources}{qt_target_qml_sources()} +also can specify if they should be skipped for the linting, +\l{qmlcachegen-auto}{bytecode compilation} or \c qmldir file generation. + +\c 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 \l 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 \c QT_RESOURCE_ALIAS source property, just as for +\c{.qml} files (see \l{qmlcachegen-auto}{Caching compiled QML sources}). + +\target RESOURCE_PREFIX +\c 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 \c{/imports} to the domain name to +form the resource prefix. For example: + +\badcode +qt_add_qml_module(someTarget + RESOURCE_PREFIX /my.company.com/imports + ... +) +\endcode + +\target NO_RESOURCE_TARGET_PATH +When various files are added to the compiled-in resources, they are placed +under a path formed by concatenating the \c 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 \c{.qml} files and other resources directly +under the \c RESOURCE_PREFIX instead. This can be achieved by specifying the +\c NO_RESOURCE_TARGET_PATH option, which may only be used if the backing target +is an executable. + +\target PAST_MAJOR_VERSIONS +\section2 Registering past major versions + +\c PAST_MAJOR_VERSIONS contains a list of additional major version that the module +provides. For each of those versions and each QML file +without a \c QT_QML_SOURCE_VERSIONS setting an additional entry in the +\l{Module Definition qmldir Files}{qmldir} file will be generated to specify +the extra version. Furthermore, the generated module registration code will +register the past major versions using \l{qmlRegisterModule()} on the C++ side. +The module registration code is automatically generated for your QML module, +unless you specify \c{NO_GENERATE_QMLTYPES} (but use of this option is strongly +discouraged). Usage of \c 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 \c{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. + +\section2 Declaring module dependencies + +\c IMPORTS provides a list of other QML modules that this module imports. Each +module listed here will be added as an \c{import} entry in the generated +\l{Module Definition qmldir Files}{qmldir} file. If a QML file imports +this module, it also imports all the modules listed under \c{IMPORTS}. +Optionally, a version can be specified by appending it after a slash, such as +\c{QtQuick/2.0}. Omitting the version will cause the greatest version available +to be imported. You may only specify the major version, as in \c{QtQuick/2}. In +that case the greatest minor version available with the given major version will +be imported. Finally, \c{auto} may be given as version (\c{QtQuick/auto}). If +\c{auto} is given, the version that the current module is being imported with is +propagated to the module to be imported. Given an entry \c{QtQuick/auto} in a +module \c{YourModule}, if a QML file specifies \c{import YourModule 3.14}, this +results in importing version \c{3.14} of \c{QtQuick}. For related modules that +follow a common versioning scheme, you should use \c{auto}. + +\c OPTIONAL_IMPORTS provides a list of other QML modules that this module +\e 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 \c qmllint. Versions can be specified in the same way as for \c IMPORTS. +Each module listed here will be added as an \c{optional import} entry in the +generated \l{Module Definition qmldir Files}{qmldir} file. + +\c 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 +\c 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. + +\c 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. + +For example, if one would like to subclass \c QQuickItem as following: + +\badcode +class MyItem: public QQuickItem { ... }; +\endcode + +then one has to make sure that the module containing \c QQuickItem, called +\c Quick, is declared as a dependency via the \c DEPENDENCIES option. Not doing +so might result in errors during type compilation with +\l{QML type compiler}{qmltc} or during binding and function compilation to C++ +with \l{qmlcachegen-auto}{qmlcachegen}. + +\note Adding the module to \c DEPENDENCIES is not necessary if the module +is already imported via the \c IMPORTS option. The recommended way is to +use the lighter alternative \c DEPENDENCIES over \c IMPORTS. + +The module version of the +dependencies must be specified along with the module name, in the same form as +used for \c IMPORTS and \c OPTIONAL_IMPORTS. Each module listed here will be +added as a \c{depends} entry in the generated +\l{Module Definition qmldir Files}{qmldir} file. + +\target IMPORT_PATH +\c 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 +\c qmldir file under their own target path below one of the search paths. + +If the backing target is a static library and that static library will be +installed, \c 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 \c{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. + +\note Since Qt 6.8, it is possible to pass a target name to IMPORTS and +DEPENDENCIES. See \l{QTP0005} for more details. + +\target PLUGIN_TARGET +\section2 Targets and plugin targets + +\c PLUGIN_TARGET specifies the plugin target associated with the QML module. +The \c PLUGIN_TARGET can be the same as the backing +\c target, in which case there will be no separate backing target. +If \c PLUGIN_TARGET is not given, it defaults to \c target with \c plugin +appended. For example, a backing target called \c mymodule would have a default +plugin name of \c mymoduleplugin. The plugin target's name will be used to +populate a \c{plugin} line in the generated +\l{Module Definition qmldir Files}{qmldir} file. Therefore, you must not try to +change the plugin's output name by setting target properties like +\c OUTPUT_NAME or any of its related properties. + +The backing \c 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 \c target is a static library, the plugin will also be created +as a static library. If the backing \c target is a shared library, the plugin +will be created as a module library. If an existing \c 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 \c NO_PLUGIN option. Specifying both \c NO_PLUGIN and +\c PLUGIN_TARGET is an error. + +\target NO_CREATE_PLUGIN_TARGET +In certain situations, the project may want to delay creating the plugin target +until after the call. The \c NO_CREATE_PLUGIN_TARGET option can be given in +that situation. The project is then expected to call +\l{qt6_add_qml_plugin}{qt_add_qml_plugin()} on the plugin target once it has +been created. When \c NO_CREATE_PLUGIN_TARGET is given, \c PLUGIN_TARGET must +also be provided to explicitly name the plugin target. + +\target CLASS_NAME +\target NO_GENERATE_PLUGIN_SOURCE +By default, \c{qt_add_qml_module()} will auto-generate a \c{.cpp} file that +implements the plugin class named by the \c CLASS_NAME argument. The generated +\c{.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 \c NO_GENERATE_PLUGIN_SOURCE option should be given. Where no +\c CLASS_NAME is provided, it defaults to the \c URI with dots replaced by +underscores, then \c Plugin appended. Unless the QML module has no plugin, the +class name will be recorded as a \c classname line in the generated +\l{Module Definition qmldir Files}{qmldir} file. You need to add any C++ files +with custom plugin code to the plugin target. Since the plugin then likely +contains functionality that goes beyond simply loading the backing library, you +will probably want to add \l{NO_PLUGIN_OPTIONAL}, too. Otherwise the QML engine +may skip loading the plugin if it detects that the backing library is already +linked. + +\target NO_PLUGIN +If the \c NO_PLUGIN keyword is given, then no plugin will be built. This +keyword is thus incompatible with all the options that customize the plugin +target, in particular \l{NO_GENERATE_PLUGIN_SOURCE}, \l{NO_PLUGIN_OPTIONAL}, +\l{PLUGIN_TARGET}, \l{NO_CREATE_PLUGIN_TARGET}, and \l{CLASS_NAME}. If you do +not provide a plugin for your module, it will only be fully usable if its +backing library has been linked into the executable. It is generally hard to +guarantee that a linker preserves the linkage to a library it considers unused. + +\target NO_PLUGIN_OPTIONAL +If the \c NO_PLUGIN_OPTIONAL keyword is given, then the plugin is recorded in +the generated \c 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 \c{.cpp} implementation for the plugin, that +would normally mean the \c NO_PLUGIN_OPTIONAL keyword is also needed because +the plugin will almost certainly contain functionality that the QML module +requires. + +\section2 Automatic type registration + +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 +\l{OUTPUT_DIRECTORY}{output directory}, the file name being the \c target name +with \c{.qmltypes} appended. This file name can be changed using the +\c TYPEINFO option if desired, but this should not normally be necessary. +The file name is also recorded as a \c typeinfo entry in the generated +\l{Module Definition qmldir Files}{qmldir} file. Automatic type registration +can be disabled using the \c 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 +\c qmldir file. + +\target OUTPUT_DIRECTORY +\c OUTPUT_DIRECTORY specifies where the plugin library, \c qmldir and typeinfo +files are generated. When this keyword is not given, the default value will be +the target path (formed from the \c URI) appended to the value of the +\l 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 +\c{${CMAKE_CURRENT_BINARY_DIR}}, whereas for other targets it will be just +\c{${CMAKE_CURRENT_BINARY_DIR}}. When the structure of the source tree +matches the structure of QML module target paths (which is highly recommended), +\l QT_QML_OUTPUT_DIRECTORY often isn't needed. In order to match the structure +of the target paths, you have to call your directories \e exactly like the +segments of your module URI. For example, if your module URI is +\c{MyUpperCaseThing.mylowercasething}, you need to put this in a directory +called \c{MyUpperCaseThing/mylowercasething/}. + +The need for specifying the \c OUTPUT_DIRECTORY keyword should be rare, but if +it is used, it is likely that the caller will also need to add to the +\l IMPORT_PATH to ensure that \l{qmllint-auto}{linting}, +\l{qmlcachegen-auto}{cached compilation} of qml sources, +\l{qt6_import_qml_plugins}{automatic importing} of plugins in static builds, +and \l{qt_deploy_qml_imports}{deploying imported QML modules} for non-static +builds all work correctly. + +\section2 Qt Quick Designer compatibility + +\c DESIGNER_SUPPORTED should be given if the QML module supports +Qt Quick Designer. When present, the generated \c qmldir file will contain +a \c designersupported line. See \l{Module Definition qmldir Files} for how +this affects the way Qt Quick Designer handles the plugin. + +\section2 Keeping module versions in sync + +The \c 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 \c FOLLOW_FOREIGN_VERSIONING +is given, the version information attached to the base types and their +properties is respected. So, an \c {import MyModule 2.8} will then only make +available versioned properties up to version \c{2.8} of any base types outside +\c{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. + +\section2 C++ namespaces of generated code + +If a namespace is given with the \c NAMESPACE keyword, the plugin and registration +code will be generated into a C++ namespace of this name. + +\section2 qmlimportscanner and NO_IMPORT_SCAN + +For static Qt builds, \c{qmlimportscanner} is run at configure time to scan the +\c{.qml} files of a QML module and identify the QML imports it uses (see +\l{qt6_import_qml_plugins}{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 +\l{qt6_deploy_qml_imports}{qt_deploy_qml_imports()}). Both scans can be +disabled by providing the \c{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. + +\section2 Arguments for qmltc + +\target ENABLE_TYPE_COMPILER +\c ENABLE_TYPE_COMPILER can be used to compile \c{.qml} files to C++ source code +with \l{QML type compiler}{qmltc}. Files with the source property +\c{QT_QML_SKIP_TYPE_COMPILER} are not compiled to C++. + +\c TYPE_COMPILER_NAMESPACE argument allows to override the namespace in which +\l{QML type compiler}{qmltc} generates code. +By default, the namespace of the generated code follows the module +hierarchy as depicted in the URI, +e.g., \c MyModule for a module with URI \c MyModule or +\c com::example::Module for URI \c com.example.MyModule. +By specifying the \c TYPE_COMPILER_NAMESPACE option, the generated code +can be put instead in a custom namespace, where different subnamespaces are to +be separated by a "::", e.g. "MyNamespace::MySubnamespace" for the namespace MySubnamespace that +is inside the MyNamespace. Apart from the "::", C++ namespace naming rules +apply. + +\c QMLTC_QMLTC_EXPORT_DIRECTIVE should be used with \c QMLTC_EXPORT_FILE_NAME when +the classes generated by \l{QML type compiler}{qmltc} should be exported from +the qml library. By default, classes generated by qmltc are not exported from +their library. +The header defining the export macro for the current library +can be specified as an optional argument to \c QMLTC_EXPORT_FILE_NAME while the +exporting macro name should be specified as an argument to +\c QMLTC_QMLTC_EXPORT_DIRECTIVE. If no additional include is required or wanted, +e.g. when the header of the export macro is already indirectly included by a base +class, then the \c QMLTC_EXPORT_FILE_NAME option can be left out. +*/ diff --git a/src/qml/doc/src/cmake/qt_add_qml_plugin.qdoc b/src/qml/doc/src/cmake/qt_add_qml_plugin.qdoc new file mode 100644 index 0000000000..2ce744559c --- /dev/null +++ b/src/qml/doc/src/cmake/qt_add_qml_plugin.qdoc @@ -0,0 +1,120 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-add-qml-plugin.html +\ingroup cmake-commands-qtqml + +\title qt_add_qml_plugin +\target qt6_add_qml_plugin + +\brief Defines a plugin associated with a QML module. + +\section1 Synopsis + +\badcode +qt_add_qml_plugin( + target + [BACKING_TARGET backing_target] + [STATIC | SHARED] + [OUTPUT_DIRECTORY] + [URI] + [CLASS_NAME] + [NO_GENERATE_PLUGIN_SOURCE] + [NAMESPACE namespace] +) + +\endcode + +\versionlessCMakeCommandsNote qt6_add_qml_plugin() + +\section1 Description + +This command creates the plugin target associated with a QML module. It would +normally be called internally by \l{qt6_add_qml_module}{qt_add_qml_module()} to +create or update the plugin associated with its backing target. You should not +call this function directly unless you have special circumstances that require +you to create the target in a special way. + +The documentation for \l{qt6_add_qml_module}{qt_add_qml_module()} describes +different structural patterns for how the CMake targets associated with a QML +module can be arranged. Note that even if the QML module has no separate backing +target and all functionality is implemented directly in the plugin (not the +recommended arrangement), you should still call +\l{qt6_add_qml_module}{qt_add_qml_module()} rather than \c{qt_add_qml_plugin()}. + + +\section1 Arguments + +The \c target specifies the name of the target to use for the QML plugin. If it +does not already exist, it will be created. + +\c BACKING_TARGET specifies the name of the backing target that the plugin is +associated with. The backing target can be the same as the plugin \c target, in +which case there is only the one merged target, but this is not typically +recommended (see \l{qt6_add_qml_module}{qt_add_qml_module()} for more +information). \c BACKING_TARGET should always be provided unless there are +special circumstances that require the plugin target to be created before the +backing target. If \c BACKING_TARGET is not provided, a \c URI option must be +given. + +By default, the plugin is created with a type that is compatible with the +backing target. 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. Where no backing target is +provided or the plugin has no separate backing target, the plugin type can be +specified with either the \c STATIC or \c SHARED keywords. If the plugin type +is not determined by any of the preceding conditions, a static plugin will be +created if Qt was built as static libraries, or a module library plugin +otherwise. + +\c OUTPUT_DIRECTORY specifies the directory where the plugin library will be +created. It should always be the same location as the QML module's +\l{Module Definition qmldir Files}{qmldir} file. When \c OUTPUT_DIRECTORY is +not given, it will be obtained from information stored on the +\c BACKING_TARGET, where available. Note that this could be different to the +directory of the backing target's own library. If an output directory cannot be +obtained from the backing target, the \c CMAKE_CURRENT_BINARY_DIR is used by +default. + +\c URI declares the module identifier of the QML module this plugin is +associated with. The module identifier is the (dotted URI notation) identifier +for the QML module. If \c URI is not given, a \c BACKING_TARGET must be +provided and the backing target must have its URI recorded on it (typically by +an earlier call to \l{qt6_add_qml_module}{qt_add_qml_module()}). + +Each plugin should have a C++ class that registers the module with the QML +engine. By default, \c{qt_add_qml_plugin()} auto-generates the sources for this +C++ class, and adds them to the \c{target}'s list of sources. The generated +plugin class satisfies the requirements of the plugin being optional (see +\l{Module Definition qmldir Files}). The class name is determined as follows: + +\list + \li If \c CLASS_NAME has been given, it will be used. It must match the name + used in the QML module's \c qmldir file. + \li If \c CLASS_NAME has not been given, but \c BACKING_TARGET has, the C++ + class name will be taken from details recorded on that backing target. + Those details are usually recorded by an earlier call to + \l{qt_add_qml_module}{qt_add_qml_module()}, and they will match the name + used in the generated \c qmldir file. This is the recommended way to + provide the class name in most scenarios. + \li If the class name still cannot be determined, it is set to the module's + URI with dots replaced by underscores, and \c Plugin appended. +\endlist + +If a namespace is given with the \c NAMESPACE keyword, the plugin +code will be generated into a C++ namespace of this name. + +Some plugins may require the plugin class to be written manually. For example, +the plugin may need to perform additional initialization or register things +not implemented by the default plugin class. In such cases, the +\c NO_GENERATE_PLUGIN_SOURCE option can be given. You are then responsible for +writing your own C++ plugin class and adding it to the \c target. Note that if +you need to write your own plugin class, it is very unlikely that the plugin +can be optional. This in turn means that the \c NO_PLUGIN_OPTIONAL keyword +should be included in the call to \l{qt_add_qml_module}{qt_add_qml_module()} +when defining the QML module, or else the generated \c qmldir file will be +incorrect. Make sure your plugin class uses the same class name as determined +from the logic just above. + +*/ diff --git a/src/qml/doc/src/cmake/qt_deploy_qml_imports.qdoc b/src/qml/doc/src/cmake/qt_deploy_qml_imports.qdoc new file mode 100644 index 0000000000..87125cd0bf --- /dev/null +++ b/src/qml/doc/src/cmake/qt_deploy_qml_imports.qdoc @@ -0,0 +1,116 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-deploy-qml-imports.html +\ingroup cmake-commands-qtqml + +\title qt_deploy_qml_imports +\keyword qt6_deploy_qml_imports + +\summary {Deploy the runtime components of QML modules needed by an executable.} + +\include cmake-find-package-qml.qdocinc + +Unlike most other CMake commands provided by Qt, +\c{qt6_deploy_qml_imports} can only be called from a +deployment script. It cannot be called directly by the project. + +\include cmake-qml-qt-finalize-target-warning.qdocinc warning + +\section1 Synopsis + +\badcode +qt_deploy_qml_imports( + TARGET target + [QML_DIR qml_dir] + [PLUGINS_FOUND var_name] + [NO_QT_IMPORTS] +) +\endcode + +\section1 Description + +\note This command does not usually need to be called directly. It is used + internally by other higher level commands, but projects wishing to + implement more customized deployment logic may find it useful. + +When installing an application that uses QML, it may be non-trivial to work out +which QML modules and which parts of those QML modules need to also be +installed. Because QML plugins are not linked directly to an application's +executable, \l{qt6_deploy_runtime_dependencies}{qt_deploy_runtime_dependencies()} won't find these QML modules. +The \c{qt6_deploy_qml_imports} command provides the necessary logic which +complements \l{qt6_deploy_runtime_dependencies}{qt_deploy_runtime_dependencies()} and deploys the runtime parts +of all QML modules imported by the application. + +The \c{TARGET} option is mandatory and should specify a \c{target} that is an +executable (on macOS, it should be an app bundle) and also a QML module. +All QML sources that were added to the \c{target} via +\l{qt6_add_qml_module}{qt_add_qml_module()} or +\l{qt6_target_qml_sources}{qt_target_qml_sources()} will be recursively scanned +for QML imports. The \c{NO_IMPORT_SCAN} option must not have been given to +\l{qt6_add_qml_module}{qt_add_qml_module()}. The \c{qmldir} files and plugins +from the imported QML modules will be deployed. The \c{NO_QT_IMPORTS} option +can be given to skip deploying any QML modules provided by Qt. + +By default, the runtime parts of imported QML modules will be deployed to the +\c{Resources/qml} directory for a macOS app bundle target, and to the \c{qml} +directory under the base installation location for other platforms. For the +non-macOS case, the \c{QML_DIR} option can be used to override this default +choice. + +The command will store a list of all QML plugins it deploys in the variable +named by the \c{PLUGINS_FOUND} option, if given. This is often passed as the +\c{ADDITIONAL_MODULES} argument in a subsequent call to +\l{qt6_deploy_runtime_dependencies}{qt_deploy_runtime_dependencies()}. + +\sa {qt6_generate_deploy_qml_app_script}{qt_generate_deploy_qml_app_script()}, + {qt6_deploy_runtime_dependencies}{qt_deploy_runtime_dependencies()}, + QT_DEPLOY_QML_DIR + +\section1 Example + +\badcode +cmake_minimum_required(VERSION 3.16...3.22) +project(MyThings) + +find_package(Qt6 6.3 REQUIRED COMPONENTS Core Qml) +qt_standard_project_setup() + +qt_add_executable(MyApp main.cpp) +qt_add_qml_module(MyApp + URI Application + VERSION 1.0 + QML_FILES main.qml MyThing.qml +) + +# The following script must only be executed at install time +set(deploy_script "${CMAKE_CURRENT_BINARY_DIR}/deploy_MyApp.cmake") + +file(GENERATE OUTPUT ${deploy_script} CONTENT " +include(\"${QT_DEPLOY_SUPPORT}\") +qt_deploy_qml_imports( + # Deploy QML modules used by MyApp + TARGET MyApp + + # The found QML plugins are stored in the plugins_found variable + PLUGINS_FOUND plugins_found + + # The QML modules will be deployed into a custom directory + QML_DIR \"myqmldir\" + + # Qt QML modules will be skipped, only project-created QML modules will be deployed + NO_QT_IMPORTS +) +# Deploy application runtime dependencies and runtime dependencies +# of the found QML module plugins. +qt_deploy_runtime_dependencies( + EXECUTABLE $<TARGET_FILE:MyApp> + ADDITIONAL_MODULES \${plugins_found} +) +") + +install(TARGETS MyApp) +install(SCRIPT ${deploy_script}) +\endcode +*/ diff --git a/src/qml/doc/src/cmake/qt_generate_deploy_qml_app_script.qdoc b/src/qml/doc/src/cmake/qt_generate_deploy_qml_app_script.qdoc new file mode 100644 index 0000000000..0d5088e7e5 --- /dev/null +++ b/src/qml/doc/src/cmake/qt_generate_deploy_qml_app_script.qdoc @@ -0,0 +1,177 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-generate-deploy-qml-app-script.html +\ingroup cmake-commands-qtqml + +\title qt_generate_deploy_qml_app_script +\target qt6_generate_deploy_qml_app_script + +\summary {Generate a deployment script for a QML application.} + +\include cmake-find-package-qml.qdocinc + +\cmakecommandsince 6.3 + +\include cmake-qml-qt-finalize-target-warning.qdocinc warning + +\section1 Synopsis + +\badcode +qt_generate_deploy_qml_app_script( + TARGET <target> + OUTPUT_SCRIPT <var> + [NO_UNSUPPORTED_PLATFORM_ERROR] + [NO_TRANSLATIONS] + [NO_COMPILER_RUNTIME] + [DEPLOY_TOOL_OPTIONS ...] + [DEPLOY_USER_QML_MODULES_ON_UNSUPPORTED_PLATFORM] + [MACOS_BUNDLE_POST_BUILD] + [PRE_INCLUDE_REGEXES regexes...] + [PRE_EXCLUDE_REGEXES regexes...] + [POST_INCLUDE_REGEXES regexes...] + [POST_EXCLUDE_REGEXES regexes...] + [POST_INCLUDE_FILES files...] + [POST_EXCLUDE_FILES files...] +) +\endcode + +\versionlessCMakeCommandsNote qt6_generate_deploy_qml_app_script() + +\section1 Description + +Installing an executable target that is also a QML module requires deploying +a number of things in addition to the target itself. Qt libraries and other +libraries from the project, Qt plugins, and the runtime parts of all QML modules +the application uses may all need to be installed too. The installed layout +is also going to be different for macOS app bundles compared to other platforms. +The \c{qt_generate_deploy_qml_app_script()} is a convenience command intended +to simplify that process, similar to what +\l{qt6_generate_deploy_app_script}{qt_generate_deploy_app_script()} does for +non-QML applications. + +The command expects the application to follow Qt's recommended install +directory structure fairly closely. That structure is based on CMake's default +install layout, as determined by \l{GNUInstallDirs} (except for macOS app +bundles, which follow Apple's requirements instead). QML modules are installed +to the appropriate location for the platform. For macOS bundles, each QML +module's \c{qmldir} file is installed under the appropriate subdirectory below +\c{Resources/qml} and the module's plugin (if present) is installed under +\c{PlugIns}. The app bundle is assumed to be installed directly to the base +installation location (see the \l{Example} further below). For all other platforms, +both the \c{qmldir} and the module's plugin are installed under the appropriate +subdirectory below \c{qml}, which itself is relative to the base installation +location. + +\c{qt_generate_deploy_qml_app_script()} generates a script whose name will be +stored in the variable named by the \c{OUTPUT_SCRIPT} option. That script +is only written at CMake generate-time. It is intended to be used with the +\l{install(SCRIPT)} command, which should come after the application's target +has been installed using \l{install(TARGETS)}. + +The deployment script will call +\l{qt6_deploy_qml_imports}{qt_deploy_qml_imports()} with a suitable set of +options for the standard install layout. For macOS app bundles and Windows +targets, it will then also call +\l{qt6_deploy_runtime_dependencies}{qt_deploy_runtime_dependencies()}, again +with suitable options for the standard install layout. + +Calling \c{qt_generate_deploy_qml_app_script()} for a platform that is not +supported by \c{qt_deploy_runtime_dependencies} will result in a fatal error, +unless the \c{NO_UNSUPPORTED_PLATFORM_ERROR} option is given. When the option +is given and the project is built for an unsupported platform, neither QML modules +nor regular runtime dependencies will be installed. +To ensure that the QML modules are still installed, specify both the +\c{NO_UNSUPPORTED_PLATFORM_ERROR} and +\c{DEPLOY_USER_QML_MODULES_ON_UNSUPPORTED_PLATFORM} options. +The latter option will ensure that QML modules built as part of the project +are still installed. + +The \c{MACOS_BUNDLE_POST_BUILD} option enables an extra step when \c{target} +is a macOS app bundle. A post-build rule will be created which uses the +deployment script to deploy enough of the imported QML modules to allow the +application to run directly from the build directory (essentially just the +\c{qmldir} files and symlinks to plugins). This is usually desirable to support +development of the application. \c{MACOS_BUNDLE_POST_BUILD} is ignored for all +other platforms. + +On platforms other than macOS, Qt translations are automatically deployed. To +inhibit this behavior, specify \c{NO_TRANSLATIONS}. Use +\l{qt_deploy_translations}{qt_deploy_translations()} to deploy translations in a +customized way. + +For Windows desktop applications, the required runtime files for the compiler +are also installed by default. To prevent this, specify \c{NO_COMPILER_RUNTIME}. + +Since Qt 6.7, you can use \c{DEPLOY_TOOL_OPTIONS} to pass additional options to +the underlying deployment tool. This only has an effect if the underlying +deployment tool is either macdeployqt or windeployqt. + +The options \c{PRE_INCLUDE_REGEXES}, \c{PRE_EXCLUDE_REGEXES}, +\c{POST_INCLUDE_REGEXES}, \c{POST_EXCLUDE_REGEXES}, \c{POST_INCLUDE_FILES}, and +\c{POST_EXCLUDE_FILES} can be specified to control the deployment of runtime +dependencies. These options do not apply to all platforms and are forwarded +unmodified to +\l{qt6_deploy_runtime_dependencies}{qt_deploy_runtime_dependencies()}. + +For deploying a non-QML application, use +\l{qt6_generate_deploy_app_script}{qt_generate_deploy_app_script()} +instead. It is an error to call both \c{qt_generate_deploy_qml_app_script()} +and \l{qt6_generate_deploy_app_script}{qt_generate_deploy_app_script()} for the +same target. + +\sa {qt6_standard_project_setup}{qt_standard_project_setup()}, + {qt6_generate_deploy_app_script}{qt_generate_deploy_app_script()} + +\section1 Example + +The following example shows how to deploy a QtQuick app. + +\badcode +cmake_minimum_required(VERSION 3.16...3.22) +project(MyThings) + +find_package(Qt6 6.3 REQUIRED COMPONENTS Core Qml) +qt_standard_project_setup() + +qt_add_executable(MyApp main.cpp) +qt_add_qml_module(MyApp + URI Application + VERSION 1.0 + QML_FILES main.qml MyThing.qml +) + +install(TARGETS MyApp + BUNDLE DESTINATION . + RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR} +) + +qt_generate_deploy_qml_app_script( + TARGET MyApp + OUTPUT_SCRIPT deploy_script + MACOS_BUNDLE_POST_BUILD + NO_UNSUPPORTED_PLATFORM_ERROR + DEPLOY_USER_QML_MODULES_ON_UNSUPPORTED_PLATFORM +) +install(SCRIPT ${deploy_script}) +\endcode + +The following example shows how to pass additional options to the underlying +deployment tool. + +\badcode +set(deploy_tool_options_arg "") +if(APPLE) + set(deploy_tool_options_arg --hardened-runtime) +elseif(WIN32) + set(deploy_tool_options_arg --no-compiler-runtime) +endif() + +qt_generate_deploy_qml_app_script( + ... + DEPLOY_TOOL_OPTIONS ${deploy_tool_options_arg} +) +install(SCRIPT ${deploy_script}) +\endcode +*/ diff --git a/src/qml/doc/src/cmake/qt_generate_foreign_qml_types.qdoc b/src/qml/doc/src/cmake/qt_generate_foreign_qml_types.qdoc new file mode 100644 index 0000000000..22d72c101b --- /dev/null +++ b/src/qml/doc/src/cmake/qt_generate_foreign_qml_types.qdoc @@ -0,0 +1,77 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-generate-foreign-qml-types.html +\ingroup cmake-commands-qtqml + +\title qt_generate_foreign_qml_types +\target qt6_generate_foreign_qml_types + +\summary{Registers types from one target in a QML module.} + +\include cmake-find-package-qml.qdocinc + +\section1 Synopsis + +\badcode +qt_generate_foreign_qml_types( + source_target + destination_qml_target +) + +\endcode + +\versionlessCMakeCommandsNote qt6_generate_foreign_qml_types() + +\section1 Description + +\c qt_generate_foreign_qml_types extracts types marked via QML registration +macros (like \l QML_ELEMENT) from \c source_target and registers them as foreign +types in the QML module \c destination_qml_target. + +This can be useful when one wants to create a library with optional QML integration, without +depending directly on QML. + +\badcode +// myclass.h +#include <QtQmlIntegration/qqmlintegration.h> + +class MyClass : public QObject +{ + QML_ELEMENT + Q_OBJECT + + // [...] +}; +\endcode + +\badcode +# CMakeLists.txt +qt_add_library(mylib myclass.h ...) +target_link_libraries(mylib PRIVATE Qt::Core Qt::QmlIntegration) + +qt_add_qml_module(mylib_declarative + VERSION 1.0 + URI "mylib" + ... +) +qt_generate_foreign_qml_types(mylib mylib_declarative) +\endcode + +\note In the example above, \c mylib does not depend on QtQml or QtQuick, but only on the +header-only QmlIntegration target (for the QtQmlIntegration/qqmlintegration.h header, which provides +the \c QML_ELEMENT macro). + +The effect is equivalent to using \c QML_FOREIGN with custom structs in the QML library to expose +the types. + +\note In order to implement custom behavior, such as exposing an existing +singleton instance with its own life cycle to QML, you should add custom types +to your QML library (mylib_declarative in the above example). In turn, you +should omit the \l QML_ELEMENT and similar macros from the original C++ classes +so that qt_generate_foreign_qml_types() does not generate more QML integration +structs for them. The QML macros, as well as any singleton factory functions, +can be added to the structs that contain the \l QML_FOREIGN. + +*/ diff --git a/src/qml/doc/src/cmake/qt_import_qml_plugins.qdoc b/src/qml/doc/src/cmake/qt_import_qml_plugins.qdoc new file mode 100644 index 0000000000..8d6b32f903 --- /dev/null +++ b/src/qml/doc/src/cmake/qt_import_qml_plugins.qdoc @@ -0,0 +1,55 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-import-qml-plugins.html +\ingroup cmake-commands-qtqml + +\title qt_import_qml_plugins +\target qt6_import_qml_plugins + +\brief Ensures QML plugins needed by a target are imported for static builds. + +\cmakecommandsince 6.0 + +\section1 Synopsis + +\badcode +qt_import_qml_plugins(target) +\endcode + +\versionlessCMakeCommandsNote qt6_import_qml_plugins() + +\section1 Description + +\note This command only has any effect if Qt was built statically. If called + using a non-static Qt, it will do nothing and return immediately. + +\c{qt_import_qml_plugins()} runs \c{qmlimportscanner} on the \c target +immediately as part of the call (unless the \c{NO_IMPORT_SCAN} option was +passed to \l{qt6_add_qml_module}{qt_add_qml_module()} when defining the QML +module). It finds the static QML plugins used by the +\c target and links it to those plugins so that they are part of the executable +or shared library that \c target represents. The search follows QML module +imports recursively. + +Because the call to \c{qmlimportscanner} runs at configure time rather than +generation or build time, \c{qt_import_qml_plugins()} only knows about the +information recorded on the \c target (or other targets it links or imports) +at the time \c{qt_import_qml_plugins()} is called. Any linking or import +relationships added after this call will not be considered. Therefore, this +command should be called as late as possible in the \c{target}'s directory +scope so that all the linking and import relationships are known. + +If \c target was created using \l{qt6_add_executable}{qt_add_executable()}, +projects would not normally need to call \c{qt_import_qml_plugins()} directly. +When Qt is built statically, the command is called automatically as part of +\l{qt6_add_executable#Finalization}{target finalization} if \c target links to +the Qml library. By default, this finalization occurs at the end of the same +directory scope in which the \c target was created. If the \c target was +created using the standard CMake \c{add_executable()} command instead, the +project needs to call \c{qt_import_qml_plugins()} itself. + +\sa Q_IMPORT_QML_PLUGIN + +*/ diff --git a/src/qml/doc/src/cmake/qt_query_qml_module.qdoc b/src/qml/doc/src/cmake/qt_query_qml_module.qdoc new file mode 100644 index 0000000000..c72626a52d --- /dev/null +++ b/src/qml/doc/src/cmake/qt_query_qml_module.qdoc @@ -0,0 +1,213 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-query-qml-module.html +\ingroup cmake-commands-qtqml + +\title qt_query_qml_module +\target qt6_query_qml_module + +\summary {Retrieve information about a QML module.} + +\include cmake-find-package-qml.qdocinc + +\cmakecommandsince 6.3 + +\section1 Synopsis + +\badcode +qt_query_qml_module( + target + [URI uri_var] + [VERSION version_var] + [PLUGIN_TARGET plugin_target_var] + [TARGET_PATH target_path_var] + [MODULE_RESOURCE_PATH module_resource_path_var] + [QMLDIR qmldir_var] + [TYPEINFO typeinfo_var] + [QML_FILES qml_files_var] + [QML_FILES_DEPLOY_PATHS qml_files_deploy_paths_var] + [QML_FILES_PREFIX_OVERRIDES qml_files_prefix_overrides_var] + [RESOURCES resources_var] + [RESOURCES_DEPLOY_PATHS resources_deploy_paths_var] + [RESOURCES_PREFIX_OVERRIDES resources_prefix_overrides_var] +) +\endcode + +\versionlessCMakeCommandsNote qt6_query_qml_module() + +\section1 Description + +This command is used to obtain information about a QML module \c target. +That \c target must have previously been created by or passed to an earlier +call to \l{qt6_add_qml_module}{qt_add_qml_module()}. The \c target cannot be an +imported target. + +The information provided by this command enables the caller to deploy all parts +of a single QML module. The project should install the \c target and the +associated plugin target (if the module has one and it is separate from the +backing \c target) using the standard \l{install(TARGETS)} command. +Everything else can be deployed with \l{install(FILES)}. + +\section1 Arguments + +Each of the optional arguments specifies the name of a variable in which to +store the corresponding QML module property. + +\c URI and \c VERSION provide the module's uri and version respectively. + +\c PLUGIN_TARGET can be used to obtain the name of the plugin target for the +QML module. Not all QML modules have a plugin, so the value returned for this +option could be an empty string. If the QML module has no separate backing +target, then \c target will be the same as the plugin target. + +\c TARGET_PATH is the \c URI with dots (.) replaced by forward slashes (/). +It represents the path below the base QML module installation directory where +this QML module's \c{qmldir} file (and possibly others) should be deployed. +The QML module installation directory serves as a QML import path where +the QML engine will look for QML modules. +The default base QML module installation directory used by +\l{qt6_generate_deploy_qml_app_script}{qt_generate_deploy_qml_app_script()} +is \c{qml}. A project using a deployment script can use \l{QT_DEPLOY_QML_DIR} +rather than hard-coding this location (also see \l{QT_DEPLOY_PREFIX}). + +\c MODULE_RESOURCE_PATH provides the resource path under which the QML module's +compiled-in files can be found. It is formed from +\l{qt6_add_qml_module}{qt_add_qml_module()}'s \c{RESOURCE_PREFIX} concatenated +with the module's \c TARGET_PATH. +The queried value should not be used for deployment, but may be helpful in +matching up resource paths with file system locations, if needed. + +\c QMLDIR provides the path to the \c{qmldir} file. When deploying the QML +module, this file should be copied to the target path. In a deployment script, +this location can be obtained using \c{${QT_DEPLOY_PREFIX}/${QT_DEPLOY_QML_DIR}}. + +\c TYPEINFO provides the path to the module's typeinfo file, if it has one. +It will be an empty string if the module has no typeinfo file. The typeinfo +file should be deployed to the same path as the \c{qmldir} file. + +\c QML_FILES provides a list of all files added to the QML module through one +of the following methods: + +\list +\li As \c{QML_FILES} arguments in \l{qt6_add_qml_module}{qt_add_qml_module()}. +\li As \c{FILES} arguments in \l{qt6_target_qml_sources}{qt_target_qml_sources()}. +\endlist + +All files will be recorded with absolute paths. + +\c QML_FILES_DEPLOY_PATHS provides a list with exactly the same number of +elements as \c QML_FILES. Each element of the \c QML_FILES_DEPLOY_PATHS list is +the path below the target path where the corresponding element of \c QML_FILES +should be deployed. The paths in \c QML_FILES_DEPLOY_PATHS include the file +name, since this could be different to the file name in \c QML_FILES due to the +use of resource aliases (see \l{QT_RESOURCE_ALIAS}). + +Entries in \c QML_FILES_DEPLOY_PATHS can also be an empty string. Any file +added using \l{qt6_target_qml_sources}{qt_target_qml_sources()} with a custom +\c PREFIX will have no deploy path, since using a custom prefix typically means +the file sits outside of the QML module's target path. + +\c QML_FILES_PREFIX_OVERRIDES provides another list with exactly the same +number of elements as \c QML_FILES. Where a file has been added with a custom +prefix as described in the preceding paragraph, its corresponding entry in the +\c QML_FILES_PREFIX_OVERRIDES list will contain the custom prefix used. For all +other files, their list entries will be an empty string. + +\note As a special case, if there is only one file in the \c QML_FILES list, +then \c QML_FILES_DEPLOY_PATHS or \c QML_FILES_PREFIX_OVERRIDES may be an empty +string depending on whether that file has a custom prefix. +This is because CMake's way of representing lists and strings means that +it is impossible to distinguish between an empty string and a list with a single +empty element. + +The \c RESOURCES, \c RESOURCES_DEPLOY_PATHS, and \c RESOURCES_PREFIX_OVERRIDES +options are analogous to those for \c QML_FILES discussed above. +\c RESOURCES provides a list of all files added to the QML module as +\c RESOURCES arguments to either \l{qt6_add_qml_module}{qt_add_qml_module()} or +\l{qt6_target_qml_sources}{qt_target_qml_sources()}. All paths will be +absolute. The meaning and usage of \c RESOURCES_DEPLOY_PATHS and +\c RESOURCES_PREFIX_OVERRIDES follows the same patterns as +\c QML_FILES_DEPLOY_PATHS and \c QML_FILES_PREFIX_OVERRIDES respectively. + +\section1 Example + +\badcode +cmake_minimum_required(VERSION 3.16...3.22) +project(MyThings) + +find_package(Qt6 6.3 REQUIRED COMPONENTS Core Qml) + +set(module_name "MyThings") +qt_add_qml_module(${module_name} + URI My.Things + VERSION 1.3 + RESOURCE_PREFIX org.mycompany/imports + QML_FILES + First.qml + Second.qml + RESOURCES + Third.txt +) + +qt_query_qml_module(${module_name} + URI module_uri + VERSION module_version + PLUGIN_TARGET module_plugin_target + TARGET_PATH module_target_path + QMLDIR module_qmldir + TYPEINFO module_typeinfo + QML_FILES module_qml_files + QML_FILES_DEPLOY_PATHS qml_files_deploy_paths + RESOURCES module_resources + RESOURCES_DEPLOY_PATHS resources_deploy_paths +) + +message("My QML module URI is: ${module_uri}") +message("My QML module version is: ${module_version}") + +# Install the QML module backing library +set(staging_prefix "staging") +install(TARGETS ${module_name} + ARCHIVE DESTINATION "${staging_prefix}/${CMAKE_INSTALL_LIBDIR}" + LIBRARY DESTINATION "${staging_prefix}/${CMAKE_INSTALL_LIBDIR}" + RUNTIME DESTINATION "${staging_prefix}/${CMAKE_INSTALL_BINDIR}" +) +set(module_dir "${staging_prefix}/qml/${module_target_path}") + +# Install the QML module runtime loadable plugin +install(TARGETS "${module_plugin_target}" + LIBRARY DESTINATION "${module_dir}" + RUNTIME DESTINATION "${module_dir}" +) + +# Install the QML module meta information. +install(FILES "${module_qmldir}" DESTINATION "${module_dir}") +install(FILES "${module_typeinfo}" DESTINATION "${module_dir}") + +# Install QML files, possibly renamed. +list(LENGTH module_qml_files num_files) +math(EXPR last_index "${num_files} - 1") +foreach(i RANGE 0 ${last_index}) + list(GET module_qml_files ${i} src_file) + list(GET qml_files_deploy_paths ${i} deploy_path) + get_filename_component(dst_name "${deploy_path}" NAME) + get_filename_component(dest_dir "${deploy_path}" DIRECTORY) + install(FILES "${src_file}" DESTINATION "${module_dir}/${dest_dir}" RENAME "${dst_name}") +endforeach() + +# Install resources, possibly renamed. +list(LENGTH module_resources num_files) +math(EXPR last_index "${num_files} - 1") +foreach(i RANGE 0 ${last_index}) + list(GET module_resources ${i} src_file) + list(GET resources_deploy_paths ${i} deploy_path) + get_filename_component(dst_name "${deploy_path}" NAME) + get_filename_component(dest_dir "${deploy_path}" DIRECTORY) + install(FILES "${src_file}" DESTINATION "${module_dir}/${dest_dir}" RENAME "${dst_name}") +endforeach() + +\endcode + +*/ diff --git a/src/qml/doc/src/cmake/qt_target_compile_qml_to_cpp.qdoc b/src/qml/doc/src/cmake/qt_target_compile_qml_to_cpp.qdoc new file mode 100644 index 0000000000..0ef6e421ed --- /dev/null +++ b/src/qml/doc/src/cmake/qt_target_compile_qml_to_cpp.qdoc @@ -0,0 +1,14 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-target-compile-qml-to-cpp.html +\ingroup cmake-commands-qtqml + +\title qt_target_compile_qml_to_cpp +\target qt6_target_compile_qml_to_cpp + +This command is removed in Qt 6.4 in favor of \l{qt6_add_qml_module} which can +now invoke qmltc internally as described in the \l{qmltc-cmake}{qmltc section}. + +*/ diff --git a/src/qml/doc/src/cmake/qt_target_qml_sources.qdoc b/src/qml/doc/src/cmake/qt_target_qml_sources.qdoc new file mode 100644 index 0000000000..336cd973f9 --- /dev/null +++ b/src/qml/doc/src/cmake/qt_target_qml_sources.qdoc @@ -0,0 +1,206 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-target-qml-sources.html +\ingroup cmake-commands-qtqml + +\title qt_target_qml_sources +\target qt6_target_qml_sources + +\brief Add qml files and resources to an existing QML module target. + +\cmakecommandsince 6.2 + +\section1 Synopsis + +\badcode +qt_target_qml_sources( + target + [QML_FILES ...] + [RESOURCES ...] + [PREFIX resource_path] + [OUTPUT_TARGETS out_targets_var] + [NO_LINT] + [NO_CACHEGEN] + [NO_QMLDIR_TYPES] +) + +\endcode + +\versionlessCMakeCommandsNote qt6_target_qml_sources() + +\section1 Description + +\note This command requires CMake 3.19 or later. + +\c{qt_target_qml_sources()} provides the ability to add more files to a QML +module after \l{qt6_add_qml_module}{qt_add_qml_module()} has been called. +Typically, you pass the set of \c{.qml} files and resources to +\l{qt6_add_qml_module}{qt_add_qml_module()} directly, but in some cases, it may +be desirable, or even necessary, to add files after +\l{qt6_add_qml_module}{qt_add_qml_module()} has been called. For example, you +may wish to add files conditionally based on an \c{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 \c{qt_target_qml_sources()} command enables these +scenarios. + +\section1 Arguments + +The \c 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. + +\c QML_FILES is a list of \c{.qml}, \c{.js} and \c{.mjs} files to be added to +the QML module. This option has exactly the same effect as the \c QML_FILES +option of the \l{qt6_add_qml_module}{qt_add_qml_module()} command, including +the automatic compilation to bytecode and lint processing. + +The \c NO_CACHEGEN and \c NO_LINT options also have the same effect as they do +for \l{qt6_add_qml_module}{qt_add_qml_module()}. They disable the bytecode +compilation and lint processing for the files listed with \c QML_FILES. This +behavior can also be specified just for individual files using +\l{qml-source-file-properties}{source file properties}. + +\c NO_QMLDIR_TYPES prevents the \c QML_FILES from being added as types to the +generated \l{qmldir-autogeneration}{qmldir} file. + +\c RESOURCES has exactly the same effect as the \c RESOURCES option of the +\l{qt6_add_qml_module}{qt_add_qml_module()} command. It provides a list of +files to be added to the \c target as ordinary resources. These files are +typically things like images, shaders, etc. that the QML code refers to in some +way. + +\target PREFIX +Files added to the module via \c QML_FILES or \c RESOURCES will be placed under +the same resource prefix and target path as they would if they were added by the +\l{qt6_add_qml_module}{qt_add_qml_module()} command. This can be overridden by +providing a different location with the \c PREFIX option. The value following +the \c 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 \c CMAKE_CURRENT_SOURCE_DIR. The \l{QT_RESOURCE_ALIAS} source +file property can also be used to override that relative path. + +\badcode +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 +) +\endcode + +In the above example, the \c backing target's resources will end up with the +following contents: + +\list +\li \c{/my.company.com/imports/Example/special/First.qml} +\li \c{/my.company.com/imports/Example/icons/logo.png} +\li \c{/other.company.com/debugging/Inspector.qml} +\endlist + +\c OUTPUT_TARGETS is also analogous to the same option for +\l{qt6_add_qml_module}{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 \c target will be installed, these additional targets will also need to +be installed to satisfy linking requirements. + +\target qml-source-file-properties +\section1 Source File Properties + +A number of source file properties can be used to influence how each individual +\c{.qml} file is treated at various points in the QML module processing. These +override any higher level options specified in calls to +\c{qt_target_qml_sources()} or \l{qt6_add_qml_module}{qt_add_qml_module()}. +All of these properties need to be set before the files are added with either +of those two commands. + +\c QT_QML_SKIP_QMLLINT can be set to \c TRUE on a source file to prevent it +from being included in the \l{qmllint-auto}{automatic qmllint processing}. +By default, all \c{.qml} files will be included in the target's lint run, but +this option can be used to exclude specific files. + +\c QT_QML_SKIP_CACHEGEN does a similar thing, preventing a source file from +being compiled to byte code when this property is set to \c TRUE. Note that the +file will still be added to the \c target as a resource in uncompiled form +(see \l{qmlcachegen-auto}{Caching compiled QML sources}). + +Set the \c QT_QML_SKIP_QMLDIR_ENTRY source file property to \c TRUE to prevent +that \c{.qml} file from being added as a type to the QML module's typeinfo file +(see \l{qmldir-autogeneration}{Auto-generating \c{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 \l{qmldir-autogeneration}{generating the \c qmldir file}, a +single type entry will be generated for each \c{.qml} file that provides a type. +It will be given a version number \c{X.0} where \c{X} is the major version of +the QML module. If the QML module has any \c PAST_MAJOR_VERSIONS set, the same +pattern will be applied to those too, appending \c{X.0} for each past major +version \c{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 \c{.0} release), specify those versions in the source file's +\c QT_QML_SOURCE_VERSIONS property. One type entry will be created for each +version. + +If the type that a \c{.qml} file provides is a singleton, set its +\c QT_QML_SINGLETON_TYPE property to \c TRUE. Similarly, the file's +\c QT_QML_INTERNAL_TYPE source property can be set to \c TRUE to indicate that +the type it provides is an internal one. The name of the type itself can also +be overridden using the \c QT_QML_SOURCE_TYPENAME property. All three of these +will be reflected in the file's type entries in the +\l{qmldir-autogeneration}{generated \c qmldir file}. +The source properties must be set before \l{qt_add_qml_module}{creating} the +module the singleton belongs to. + +\target QT_RESOURCE_ALIAS +All files listed with \c QML_FILES or \c RESOURCES will be added to the +\c{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 \l PREFIX argument. The relative path will default to the path of the file +relative to the \c{target}'s \c SOURCE_DIR target property. This relative path +can be overridden by setting the \c 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. + +\target qt_target_qml_sources_example +\snippet cmake/qt_target_qml_sources/CMakeLists.txt 0 + +In the above example, the \c qt_target_qml_sources_example target's resources +will end up with the following contents: + +\list +\li \c{/my.company.com/imports/Example/File.qml} +\li \c{/my.company.com/imports/Example/FunnySingleton.qml} +\li \c{/my.company.com/imports/Example/templates/File.qml} +\li \c{/my.company.com/imports/Example/some_old_thing.qml} +\li \c{/my.company.com/imports/Example/button-types.png} +\li \c{/my.company.com/imports/Example/doc/README.txt} +\endlist + +The generated \c qmldir file will contain the following type entries: + +\badcode +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 +\endcode + +\note The source FunnySingleton.qml file must already contain +the \c {pragma Singleton} statement. Setting the \c QT_QML_SINGLETON_TYPE source +property does not automatically generate the pragma. + +\snippet cmake/qt_target_qml_sources/FunnySingleton.qml 0 + +*/ |