From 1cc0fed1c3b6386297d26dc79dd22f87384392bc Mon Sep 17 00:00:00 2001 From: Craig Scott Date: Wed, 25 Aug 2021 22:28:23 +1000 Subject: Add documentation for qt_target_qml_sources() Change-Id: I4e868bb522202f23e99abbb808b976c1d58ebf8c Reviewed-by: Fabian Kosmale (cherry picked from commit 4c305d7d2807b3bba9c3935cfe28b88e491f6032) Reviewed-by: Qt Cherry-pick Bot --- src/qml/CMakeLists.txt | 5 + src/qml/Qt6QmlMacros.cmake | 74 +-------- .../cmake/qt_target_qml_sources/CMakeLists.txt | 39 +++++ .../cmake/qt_target_qml_sources/TemplateFile.qml | 3 + .../cmake/qt_target_qml_sources/doc/README.txt | 1 + .../qt_target_qml_sources/nested/way/down/File.qml | 3 + .../cmake/qt_target_qml_sources/some_old_thing.qml | 3 + src/qml/doc/src/cmake/qt_target_qml_sources.qdoc | 172 ++++++++++++++++++++- 8 files changed, 223 insertions(+), 77 deletions(-) create mode 100644 src/qml/doc/snippets/cmake/qt_target_qml_sources/CMakeLists.txt create mode 100644 src/qml/doc/snippets/cmake/qt_target_qml_sources/TemplateFile.qml create mode 100644 src/qml/doc/snippets/cmake/qt_target_qml_sources/doc/README.txt create mode 100644 src/qml/doc/snippets/cmake/qt_target_qml_sources/nested/way/down/File.qml create mode 100644 src/qml/doc/snippets/cmake/qt_target_qml_sources/some_old_thing.qml (limited to 'src') diff --git a/src/qml/CMakeLists.txt b/src/qml/CMakeLists.txt index 6a06972897..23bd60a9c2 100644 --- a/src/qml/CMakeLists.txt +++ b/src/qml/CMakeLists.txt @@ -683,3 +683,8 @@ qt_internal_create_tracepoints(Qml qtqml.tracepoints) qt_internal_add_docs(Qml doc/qtqml.qdocconf ) + +# include snippet projects for developer builds +if(QT_FEATURE_private_tests AND CMAKE_VERSION VERSION_GREATER_EQUAL "3.19") + add_subdirectory(doc/snippets/cmake/qt_target_qml_sources) +endif() diff --git a/src/qml/Qt6QmlMacros.cmake b/src/qml/Qt6QmlMacros.cmake index cc58b77240..a47737d3bc 100644 --- a/src/qml/Qt6QmlMacros.cmake +++ b/src/qml/Qt6QmlMacros.cmake @@ -1185,79 +1185,7 @@ if(NOT QT_NO_CREATE_VERSIONLESS_FUNCTIONS) endfunction() endif() -# Add Qml files (.qml,.js,.mjs) to a Qml module. -# -# target: The backing target of the qml module. (REQUIRED) -# -# QML_FILES: The qml files to add to the backing target. Supported file extensions -# are .qml, .js and .mjs. No other file types should be listed. (REQUIRED) -# -# RESOURCES: Resources used in QML, for example images. (OPTIONAL) -# -# PREFIX: The resource path under which to add the compiled qml files. If not -# specified, the QT_QML_MODULE_RESOURCE_PREFIX property of the target is used -# as the default, if set (that property is set by qt6_add_qml_module()). -# If the default is empty, this option must be provided. (OPTIONAL) -# -# OUTPUT_TARGETS: In static builds, additional CMake targets can be created -# which consumers of the module will need to potentially install. -# Supply the name of an output variable, which will be set to a list of these -# targets. If installing the main target, you will also need to install these -# output targets for static builds. (OPTIONAL) -# -# NO_LINT: Do not add the specified files to the ${target}_qmllint target. -# If this option is not given, the default will be taken from the target. -# -# NO_CACHEGEN: Do not compile the qml files. Add the raw qml files to the -# target resources instead. If this option is not given, the default will be -# taken from the target. -# -# NO_QMLDIR_TYPES: Do not append type information from the qml files to the -# qmldir file associated with the qml module. If this option is not given, -# the default will be taken from the target. -# -# In addition to the above NO_... options, individual files can be explicitly -# skipped by setting the relevant source property. These are: -# -# - QT_QML_SKIP_QMLLINT -# - QT_QML_SKIP_QMLDIR_ENTRY -# - QT_QML_SKIP_CACHEGEN -# -# Disabling the qmldir entry for a qml file would normally only be used for a -# file that does not expose a public type (e.g. a private JS file). -# If appending of type information has not been disabled for a particular qml -# file, the following additional source properties can be specified to -# customize the file's type details: -# -# QT_QML_SOURCE_VERSION: Version(s) for this qml file. If not present the module -# major version and minor version 0 will be used. If any PAST_MAJOR_VERSIONS -# are given, those will be amended with minor version 0 and also added to the -# default. -# -# QT_QML_SOURCE_TYPENAME: Override the file's type name. If not present, the -# type name will be deduced using the file's basename. -# -# QT_QML_SINGLETON_TYPE: Set to true if this qml file contains a singleton type. -# -# QT_QML_INTERNAL_TYPE: When set to true, the type specified by -# QT_QML_SOURCE_TYPENAME will not be available to users of this module. -# -# e.g.: -# set_source_files_properties(my_qml_file.qml -# PROPERTIES -# QT_QML_SOURCE_VERSION "2.3;6.0" -# QT_QML_SOURCE_TYPENAME MyQmlFile -# -# qt6_target_qml_sources(my_qml_module -# QML_FILES -# my_qml_file.qml -# ) -# -# The above will produce the following entries in the qmldir file: -# -# MyQmlFile 2.3 my_qml_file.qml -# MyQmlFile 6.0 my_qml_file.qml -# + function(qt6_target_qml_sources target) get_target_property(uri ${target} QT_QML_MODULE_URI) diff --git a/src/qml/doc/snippets/cmake/qt_target_qml_sources/CMakeLists.txt b/src/qml/doc/snippets/cmake/qt_target_qml_sources/CMakeLists.txt new file mode 100644 index 0000000000..0bba788b20 --- /dev/null +++ b/src/qml/doc/snippets/cmake/qt_target_qml_sources/CMakeLists.txt @@ -0,0 +1,39 @@ +cmake_minimum_required(VERSION 3.19) +project(qt_target_qml_sources_snippet) + +set(CMAKE_AUTOMOC TRUE) +set(QT_QML_OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}) + +# ![0] +set_source_files_properties(nested/way/down/File.qml PROPERTIES + QT_RESOURCE_ALIAS File.qml +) +set_source_files_properties(TemplateFile.qml PROPERTIES + QT_RESOURCE_ALIAS templates/File.qml + QT_QML_SKIP_QMLDIR_ENTRY TRUE + QT_QML_SKIP_QMLLINT TRUE + QT_QML_SKIP_CACHEGEN TRUE +) +qt_add_qml_module(qt_target_qml_sources_example + URI Example + VERSION 2.3 + RESOURCE_PREFIX /my.company.com/imports + QML_FILES + nested/way/down/File.qml + TemplateFile.qml +) + +set_source_files_properties(some_old_thing.qml PROPERTIES + QT_QML_SOURCE_VERSIONS "1.1;2.0" + QT_QML_SOURCE_TYPENAME OldThing +) +set_source_files_properties(../../../images/button-types.png PROPERTIES + QT_RESOURCE_ALIAS button-types.png +) +qt_target_qml_sources(qt_target_qml_sources_example + QML_FILES some_old_thing.qml + RESOURCES + ../../../images/button-types.png + doc/README.txt +) +# ![0] diff --git a/src/qml/doc/snippets/cmake/qt_target_qml_sources/TemplateFile.qml b/src/qml/doc/snippets/cmake/qt_target_qml_sources/TemplateFile.qml new file mode 100644 index 0000000000..8fc36a40da --- /dev/null +++ b/src/qml/doc/snippets/cmake/qt_target_qml_sources/TemplateFile.qml @@ -0,0 +1,3 @@ +import QtQml + +QtObject {} diff --git a/src/qml/doc/snippets/cmake/qt_target_qml_sources/doc/README.txt b/src/qml/doc/snippets/cmake/qt_target_qml_sources/doc/README.txt new file mode 100644 index 0000000000..52d51e034d --- /dev/null +++ b/src/qml/doc/snippets/cmake/qt_target_qml_sources/doc/README.txt @@ -0,0 +1 @@ +Dummy file, contents not important. diff --git a/src/qml/doc/snippets/cmake/qt_target_qml_sources/nested/way/down/File.qml b/src/qml/doc/snippets/cmake/qt_target_qml_sources/nested/way/down/File.qml new file mode 100644 index 0000000000..8fc36a40da --- /dev/null +++ b/src/qml/doc/snippets/cmake/qt_target_qml_sources/nested/way/down/File.qml @@ -0,0 +1,3 @@ +import QtQml + +QtObject {} diff --git a/src/qml/doc/snippets/cmake/qt_target_qml_sources/some_old_thing.qml b/src/qml/doc/snippets/cmake/qt_target_qml_sources/some_old_thing.qml new file mode 100644 index 0000000000..8fc36a40da --- /dev/null +++ b/src/qml/doc/snippets/cmake/qt_target_qml_sources/some_old_thing.qml @@ -0,0 +1,3 @@ +import QtQml + +QtObject {} diff --git a/src/qml/doc/src/cmake/qt_target_qml_sources.qdoc b/src/qml/doc/src/cmake/qt_target_qml_sources.qdoc index 05770b30e0..d40f9994fa 100644 --- a/src/qml/doc/src/cmake/qt_target_qml_sources.qdoc +++ b/src/qml/doc/src/cmake/qt_target_qml_sources.qdoc @@ -32,12 +32,21 @@ \title qt_target_qml_sources \target qt6_target_qml_sources -\brief Add qml sources to an existing QML module target. +\brief Add qml files and resources to an existing QML module target. \section1 Synopsis \badcode -qt_target_qml_sources(...) +qt_target_qml_sources( + target + [QML_FILES ...] + [RESOURCES ...] + [PREFIX resource_path] + [OUTPUT_TARGETS out_targets_var] + [NO_LINT] + [NO_CACHEGEN] + [NO_QMLDIR_TYPES] +) \endcode @@ -45,9 +54,164 @@ qt_target_qml_sources(...) \section1 Description -TBD +\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 -TBD +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}. + +\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. + +\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/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 +OldThing 1.1 some_old_thing.qml +OldThing 2.0 some_old_thing.qml +\endcode + */ -- cgit v1.2.3