qt_target_qml_sources

既存の QML モジュールターゲットに QML ファイルとリソースを追加します。

このコマンドは Qt 6.2 で導入されました。

このコマンドは、Qt6 パッケージのQml コンポーネントに定義されており、次のように読み込むことができます:

find_package(Qt6 REQUIRED COMPONENTS Qml)

概要

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

バージョン指定なしのコマンドが無効になっている場合は、代わりに `qt6_target_qml_sources() ` を使用してください。このコマンドは、本コマンドと同じ引数をサポートしています。

説明

qt_target_qml_sources() qt_add_qml_module()の呼び出し後に、QML モジュールにファイルを追加する機能を提供します。 通常、.qml ファイルやリソースのセットはqt_add_qml_module()に直接渡しますが、場合によっては、qt_add_qml_module()の呼び出し後にファイルを追加することが望ましい、あるいは必要となることもあります。 たとえば、if ステートメントの式に基づいて条件付きでファイルを追加したり、特定の条件が満たされた場合にのみ追加されるサブディレクトリからファイルを追加したりしたい場合があります。また、リソースプレフィックスが異なる、あるいはリンティングやバイトコードコンパイルが無効になっているなど、他のファイルとは特性が異なる一連のファイルを追加したい場合もあるでしょう。qt_target_qml_sources() コマンドを使用することで、このようなシナリオを実現できます。

引数

target は、QMLモジュールのバッキングターゲットである必要があります。また、QMLモジュールに個別のバッキングターゲットがない場合は、そのモジュールのプラグインターゲットである必要があります。

QML_FILES は、QMLモジュールに追加される.qml 、.js 、および.mjs ファイルのリストです。このオプションは、バイトコードへの自動コンパイルやlint処理を含め、qt_add_qml_module()コマンドのQML_FILES オプションとまったく同じ効果を持ちます。

NO_CACHEGEN およびNO_LINT オプションも、qt_add_qml_module()の場合と同様の効果を持ちます。これらは、QML_FILES で指定されたファイルに対して、バイトコードへのコンパイルとlint処理を無効にします。この動作は、ソースファイルのプロパティを使用して個々のファイルに対してのみ指定することも可能です。

NO_QMLDIR_TYPES これにより、QML_FILES が生成されるqmldirファイルに型として追加されるのを防ぎます。

RESOURCES qt_add_qml_module()コマンドの `RESOURCES ` オプションとまったく同じ効果があります。これは、target に通常のリソースとして追加されるファイルのリストを提供します。これらのファイルは通常、QML コードが何らかの形で参照する画像やシェーダーなどです。

QML_FILES またはRESOURCES を介してモジュールに追加されたファイルは、qt_add_qml_module()コマンドで追加された場合と同様に、同じリソースプレフィックスとターゲットパスの下に配置されます。これは、PREFIX オプションで異なる場所を指定することで上書きできます。PREFIX キーワードに続く値は、ターゲットパスを追加することなく、そのまま使用されます。 各ファイルの最終的なリソースパスは、プレフィックスに、CMAKE_CURRENT_SOURCE_DIR の下にあるファイルのパスを加えたものになります。また、QT_RESOURCE_ALIASソースファイルプロパティを使用することで、その相対パスを上書きすることも可能です。

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
)

上記の例では、backing ターゲットのリソースは、最終的に以下の内容になります：

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

OUTPUT_TARGETS これは、qt_add_qml_module() の同名のオプションにも類似しています。静的ビルド用に作成された追加のターゲットを格納する変数の名を指定するために使用します。target がインストールされる場合、リンク要件を満たすために、これらの追加のターゲットもインストールする必要があります。

ソースファイルのプロパティ

QMLモジュールの処理の各段階で、個々の.qml ファイルがどのように扱われるかを制御するために、いくつかのソースファイルプロパティを使用できます。これらは、qt_target_qml_sources() やqt_add_qml_module()の呼び出しで指定された上位レベルのオプションよりも優先されます。これらのプロパティはすべて、これら2つのコマンドのいずれかを使用してファイルを追加する前に設定する必要があります。

QT_QML_SKIP_QMLLINT ソースファイルに `TRUE ` を設定することで、そのファイルが自動的な qmllint 処理の対象から除外されます。デフォルトでは、すべての `.qml ` ファイルがターゲットの lint 実行対象に含まれますが、このオプションを使用することで特定のファイルを除外することができます。

QT_QML_SKIP_CACHEGEN TRUE に設定すると、ソースファイルがバイトコードにコンパイルされるのを防ぐという、同様の動作をします。なお、そのファイルはコンパイルされていない形式のリソースとして に追加されることに注意してください（「target コンパイル済みQMLソースのキャッシュ」を参照）。

QT_QML_SKIP_QMLDIR_ENTRY ソースファイルプロパティをTRUE に設定すると、その QML または JavaScript ファイルが QML モジュールのqmldir ファイルに型として追加されるのを防ぐことができます（「qmldir および typeinfo ファイルの自動生成」を参照）。これは通常、プライベートな JavaScript ファイルなど、パブリックな型を公開していないファイルに対して使用されます。 ECMAScriptモジュールでもなく、.pragma library によってステートレスライブラリとして宣言もされていない、大文字の名前を持つJavaScriptファイルについては、このオプションを検討すべきです。これらをqmldir ファイルに含めると、それらが属するモジュールを明示的または暗黙的にインポートするすべてのQMLドキュメントのスコープ内で、それらのファイルが再評価されます。

デフォルトでは、 qmldir ファイルを生成する際、型を提供する各.qml ファイルに対して、1つの型エントリが生成されます。そのバージョン番号はX.0 となります。ここで、X はQMLモジュールのメジャーバージョンです。QMLモジュールにPAST_MAJOR_VERSIONS が設定されている場合、それらに対しても同様のパターンが適用され、過去の各メジャーバージョンに対してX.0 が付加されますX 。 ファイルが別のバージョンセット（例：.0 のリリース後にマイナーパッチバージョンで初めて追加された場合など）の型エントリを提供する必要がある場合は、ソースファイルのQT_QML_SOURCE_VERSIONS プロパティでそれらのバージョンを指定してください。バージョンごとに1つの型エントリが作成されます。

.qml ファイルが提供する型がシングルトンである場合は、そのQT_QML_SINGLETON_TYPE プロパティをTRUE に設定します。同様に、ファイルのQT_QML_INTERNAL_TYPE ソースプロパティをTRUE に設定することで、そのファイルが提供する型が内部型であることを示すことができます。 型自体の名前も、QT_QML_SOURCE_TYPENAME プロパティを使用して上書きできます。これら3つすべては、生成されるqmldir ファイル内のそのファイルの型エントリに反映されます。sourceプロパティは、シングルトンが属するモジュールを作成する前に設定する必要があります。

QML_FILES またはRESOURCES でリストされたすべてのファイルは、target のリソースに追加されます。リソース内でのそれらの場所は、基点と相対パスで構成されます。基点はデフォルトで、QMLモジュールのリソースプレフィックスとそのターゲットパスを連結したものになりますが、これらはPREFIX引数で上書きできます。 相対パスは、デフォルトでは、target のSOURCE_DIR ターゲットプロパティに対する相対パスとなります。この相対パスは、ソースファイルのQT_RESOURCE_ALIAS プロパティを設定することで上書きできます。これは通常、異なるディレクトリにあるファイルを収集し、リソース内で共通の場所に表示させるために使用されます。 ただし、Qt 6.8 以降では、QML モジュールのすべてのファイルを暗黙のインポートで見つけられるようにしたい場合、QTP0004を有効にする方が多くの場合、より良い選択肢となります。 それでもなお、このような手動での設定が必要な場合は、NO_GENERATE_EXTRA_QMLDIRS をqt_add_qml_module に渡すことをお勧めします。これは、追加のqmldirsではリソースファイルのエイリアスが考慮されないためです。

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

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

上記の例では、qt_target_qml_sources_example ターゲットのリソースは最終的に以下の内容になります：

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

生成されたqmldir ファイルには、以下のタイプエントリが含まれます：

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

pragma Singleton
import QtQml

QtObject {}