qt_add_qml_module

QML モジュールを定義します。

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

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

find_package(Qt6 REQUIRED COMPONENTS Qml)

概要

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_GENERATE_EXTRA_QMLDIRS]
    [NO_GENERATE_QTCONF]                          # since Qt 6.12
    [NO_GENERATE_AOT_VALIDATION]                  # since Qt 6.12
    [NO_LINT]
    [NO_CACHEGEN]
    [NO_RESOURCE_TARGET_PATH]
    [NO_IMPORT_SCAN]
    [DISCARD_QML_CONTENTS]
    [ENABLE_TYPE_COMPILER]
    [TYPE_COMPILER_NAMESPACE namespace]
    [QMLTC_EXPORT_DIRECTIVE export_macro]
    [QMLTC_EXPORT_FILE_NAME header_defining_export_macro]

)

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

QMLモジュールを定義する例については、「QMLアプリケーションの構築」および「再利用可能なQMLモジュールの構築」を参照してください。

説明

このコマンドは、C++ソース、.qml ファイル、あるいはその両方で構成されるQMLモジュールを定義します。これにより、モジュールに不可欠な詳細情報が確実に提供され、その一貫性が保たれます。また、.qml ソースのキャッシュ付きコンパイル、リソースの埋め込み、リンティングチェック、および一部の主要なモジュールファイルの自動生成などの設定と調整も行います。

概念的な概要や一般的な使用例については、「CMake による統合」を参照してください。カスタムディレクトリ構成やバージョン管理などの高度なトピックについては、「QML モジュールの作成」を参照してください。

ターゲット構造

QMLモジュールの構造には、いくつかの異なる方法があります。以下のシナリオが典型的な構成例です：

バッキングターゲットとプラグインターゲットの分離

これは、ほとんどのQMLモジュールにおいて推奨される構成です。モジュールのすべての機能は、最初のコマンド引数として指定されるバッキングターゲットに実装されます。C++ソース、.qml ファイル、およびリソースはすべて、バッキングターゲットに追加する必要があります。バッキングターゲットはライブラリであり、プロジェクトで定義された他のライブラリと同じ場所にインストールする必要があります。

バッキングターゲットが作成されるソースディレクトリ構造は、QMLモジュールのターゲットパスと一致している必要があります（ターゲットパスとは、モジュールのURIからドットをスラッシュに置き換えたものです）。ソースディレクトリ構造がターゲットパスと一致しない場合、qt_add_qml_module() は警告を出力します。

以下の例は、URI がMyThings.Panels である QML モジュールに適したソースディレクトリ構造を示しています。qt_add_qml_module() の呼び出しは、示されているCMakeLists.txt ファイル内に行われます。

src
 +-- MyThings
      +-- Panels
           +-- CMakeLists.txt

QMLモジュールには、個別のプラグインターゲットが関連付けられています。これは、アプリケーションがバックイングターゲットにまだリンクしていない場合に、実行時にモジュールを動的に読み込むために使用されます。プラグインターゲットもライブラリとなり、通常はモジュールのqmldirファイルと同じディレクトリにインストールされます。

プラグインターゲットには、理想的にはプラグインクラスのごく単純な実装のみを含めるべきです。これにより、qmldir ファイル内でそのプラグインをオプションとして指定できるようになります。そうすれば、他のターゲットはバックイングターゲットに直接リンクでき、実行時にプラグインが必要なくなるため、読み込み時のパフォーマンスが向上します。 デフォルトでは、最小限のプラグインクラスを定義する C++ ソースファイルが自動的に生成され、プラグインターゲットに追加されます。QML モジュールでカスタムプラグインクラスの実装が必要な場合は、NO_GENERATE_PLUGIN_SOURCEオプション、および通常はNO_PLUGIN_OPTIONALオプションが必要になります。

また、`STATIC ` QMLモジュールは、`NO_PLUGIN `が指定されていない場合、静的QMLプラグインも生成します。このような`STATIC ` QMLモジュールをインポートするターゲットも、対応するQMLプラグインに明示的にリンクする必要があります。

バッキングターゲットのないプラグインターゲット

QMLモジュールは、プラグインターゲットを自身のバッキングターゲットとして機能させる形で定義することができます。この場合、モジュールは実行時に動的に読み込まれる必要があり、他のターゲットから直接リンクすることはできません。この構成を作成するには、PLUGIN_TARGET キーワードを使用し、プラグインターゲット名としてtarget を繰り返し指定する必要があります。例：

qt_add_qml_module(someTarget
    PLUGIN_TARGET someTarget
    ...
)

この構成はデプロイがわずかに簡単に見えるかもしれませんが、ロード時のパフォーマンスが向上する可能性があるため、可能な限り別のバッキングターゲットを使用することを推奨します。

QMLモジュールとして実行可能

実行可能ファイルは、QMLモジュールのバッキングターゲットとして機能します。この場合、QMLモジュールは常にアプリケーションの一部として直接読み込まれるため、プラグインライブラリは存在しません。qt_add_qml_module() コマンドは、実行可能ファイルがバッキングターゲットとして使用されていることを検出し、個別のプラグインの作成を自動的に無効にします。 この構成を使用する場合は、名前に「PLUGIN 」を含むオプションは一切使用しないでください。

実行ファイルがバッキングターゲットとして使用される場合、ソースディレクトリ構造がQMLモジュールのターゲットパスと一致する必要はありません。コンパイル済みリソースに関するターゲットパスのその他の相違点については、「コンパイル済みQMLソースのキャッシュ」を参照してください。

qmldir およびtypeinfoファイルの自動生成

デフォルトでは、定義中のQMLモジュールに対してqmldirファイルとtypeinfoファイルが自動生成されます。これらのファイルの内容は、このコマンドに指定された各種引数、およびバッキングターゲットに追加されたソースファイルや.qml ファイルによって決定されます。OUTPUT_DIRECTORY引数は、qmldir ファイルおよびtypeinfoファイルの書き込み先を指定します。QMLモジュールにプラグインが含まれている場合、そのプラグインもqmldir ファイルと同じディレクトリに作成されます。

QTP0004ポリシーが NEW に設定されている場合、.qml ファイルを含む各ディレクトリごとに、別のqmldir ファイルが生成されます。これらの追加のqmldir ファイルは、prefer ディレクティブを介してモジュールのベースディレクトリへリダイレクトするだけです。これは、モジュール内のすべてのQMLコンポーネントが、どのディレクトリに保存されていても互いにアクセスできるようにするためです。

静的にビルドされたQtを使用する場合、CMakeのconfigure実行中にバッキングターゲットの.qml ファイルがスキャンされ、モジュールで使用されるインポートを特定し、リンク関係を設定します（NO_IMPORT_SCAN キーワードを指定することで、これを無効にできます）。.qml ファイルがモジュールに追加または削除されると、CMakeLists.txt ファイルが変更されたことになるため、通常、CMakeは自動的に再実行され、関連するファイルが再スキャンされます。 開発の過程で、既存の.qml ファイルにインポートや型が追加・削除されることがあります。これだけではCMakeは自動的に再実行されないため、qmldir ファイルの再生成とリンク関係の更新を強制するには、明示的にCMakeを再実行する必要があります。

ビルド時に、バッキングターゲットの C++ ソースがスキャンされ、typeinfo ファイルと、関連する型を登録するための C++ ファイルが生成されます。生成された C++ ファイルは、ソースとしてバッキングターゲットに自動的に追加されます。これには、ターゲットで `AUTOMOC ` が有効になっている必要があります。 これを確実に行うのはプロジェクトの責任であり、通常はqt_add_qml_module() を呼び出す前にCMAKE_AUTOMOC 変数をTRUE に設定するか、AUTOMOC ターゲットプロパティがすでにTRUE に設定されている既存のターゲットを渡すことで行います。ターゲットでAUTOMOC が無効になっていてもエラーにはなりませんが、その場合はプロジェクトがその影響に対処する責任を負います。 これには、詳細情報が欠落した状態で自動生成されるのを防ぐために、typeinfo ファイルを手動で生成したり、型を登録するための C++ コードを追加したりする必要がある場合があります。

プロジェクトでは、可能な限り自動生成されたtypeinfoファイルおよびqmldir ファイルを使用することを推奨します。これらはメンテナンスが容易であり、手動で作成したファイルに見られるようなエラーの発生リスクも低減されます。とはいえ、プロジェクトがこれらのファイルを独自に用意する必要がある状況では、自動生成を無効にすることができます。NO_GENERATE_QMLDIR オプションはqmldir の自動生成を無効にし、NO_GENERATE_QMLTYPES オプションはtypeinfoおよびC++型登録の自動生成を無効にします。自動生成されたtypeinfoファイルに問題がないものの、プロジェクトでそのファイルに別の名前を使用したい場合は、TYPEINFO オプションを使用してデフォルト名を上書きできます（ただし、通常はこれが必要になることはありません）。

コンパイル済み QML ソースのキャッシュ

QML_FILES 引数を通じてモジュールに追加されたすべての.qml 、.js 、および.mjs ファイルは、バイトコードにコンパイルされ、バッキングターゲットに直接キャッシュされます。これにより、モジュールの読み込み時のパフォーマンスが向上します。元の未コンパイルファイルも、QMLエンジンが特定の状況でそれらを必要とする可能性があるため、バッキングターゲットのリソースに保存されます。

各ファイルのリソースパスは、現在のソースディレクトリ（CMAKE_CURRENT_SOURCE_DIR ）に対する相対パスによって決定されます。このリソースパスは、RESOURCE_PREFIXとターゲットパスを連結して形成されたプレフィックスに追加されます（ただし、これに対する例外についてはNO_RESOURCE_TARGET_PATH を参照してください）。

QTP0001ポリシーが NEW に設定されている場合、RESOURCE_PREFIXのデフォルト値は/qt/qml/ となり、これはQMLエンジンのデフォルトのインポートパスです。これにより、モジュールがQMLインポートパスに配置され、追加の設定なしで見つけられるようになります。

通常、プロジェクトでは、.qml ファイルを、リソース内での配置と同じ相対位置に配置することを目指すべきです。もし.qml ファイルが、目的のリソースパスとは異なる相対ディレクトリにある場合、リソース内でのその場所を明示的に指定する必要があります。これは、QT_RESOURCE_ALIAS ソースファイルのプロパティを設定することで行います。この設定は、.qml ファイルを追加する前に設定する必要があります。例：

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
)

上記の例では、ターゲットパスはMyCo/Frames となります。ソースファイルのプロパティを考慮すると、2つの.qml ファイルは以下のリソースパスで見つかります：

• /my.company.com/imports/MyCo/Frames/MyFrame.qml
• /my.company.com/imports/MyCo/Frames/AnotherFrame.qml

ごく稀に、使用される qmlcachegen プログラムの自動選択を上書きしたい場合は、モジュールターゲットでQT_QMLCACHEGEN_EXECUTABLE ターゲットプロパティを設定することができます。例えば：

set_target_properties(someTarget PROPERTIES
    QT_QMLCACHEGEN_EXECUTABLE qmlcachegen
)

これにより、より適切な代替手段があったとしても、qmlcachegen が使用するプログラムとして明示的に選択されます。

さらに、QT_QMLCACHEGEN_ARGUMENTS オプションを設定することで、qmlcachegenに追加の引数を渡すことができます。特に、--only-bytecode オプションを指定すると、QMLスクリプトコードのC++へのコンパイルが無効になります。例：

set_target_properties(someTarget PROPERTIES
    QT_QMLCACHEGEN_ARGUMENTS "--only-bytecode"
)

もう1つの重要な引数は `--direct-calls` です。これを使用すると、Qt Quick コンパイラ拡張機能がインストールされている場合に、QMLスクリプトコンパイラのダイレクトモードを有効にできます。拡張機能がインストールされていない場合、この引数は無視されます。これには `QT_QMLCACHEGEN_DIRECT_CALLS ` という短縮形があります。

set_target_properties(someTarget PROPERTIES
    QT_QMLCACHEGEN_DIRECT_CALLS ON
)

最後に、--verbose 引数を使用すると、qmlcachegen からの診断出力を確認できます:

set_target_properties(someTarget PROPERTIES
    QT_QMLCACHEGEN_ARGUMENTS "--verbose"
)

このフラグを指定すると、qmlcachegen は C++ にコンパイルできない関数ごとに警告を出力します。これらの警告の中には、QML コードの問題を指摘するものもあれば、QML 言語の特定の機能が C++ コードジェネレータで実装されていないことを知らせるものもあります。 いずれの場合も、qmlcachegenはそうした関数に対してバイトコードを生成します。QMLコード自体の問題のみを確認したい場合は、代わりにqmllintと、それ用に生成されたターゲットを使用してください。

QMLソースのリンティング

QML_FILES キーワード、またはその後のqt_target_qml_sources()の呼び出しによって、.qml ファイルがモジュールに追加されると、個別のリンティングターゲットが自動的に作成されます。リンティングターゲットの名前は、target に続いて_qmllint となります。また、利便性のため、個々の*_qmllint ターゲットすべてに依存するall_qmllint ターゲットも提供されています。

dump_qml_context_properties というグローバルなビルドターゲットが自動的に作成され、qmlコンテキストプロパティのダンプファイルがまだ存在しない場合にqmlcontextpropertydumpを実行します。qmlcontextpropertydumpは、qmllintが読み込んでQMLにおけるコンテキストプロパティの使用について警告を表示するためのqmlコンテキストプロパティのダンプファイルを作成します。

clean_qml_context_properties というグローバルビルドターゲットを使用すると、既存のqmlコンテキストプロパティダンプファイルを削除することができ、dump_qml_context_properties というグローバルビルドターゲットによる今後のビルドで、qmlコンテキストプロパティダンプファイルを再計算するために使用できます。

QT_QMLLINT_CONTEXT_PROPERTY_DUMP変数が有効になっている場合、リンティングターゲットはdump_qml_context_properties ビルドターゲットに依存します。

.js ファイルの命名規則

コンポーネントとして扱われることを意図したJavaScriptファイル名は、大文字で始まる必要があります。

あるいは、小文字のファイル名を使用し、ソースファイルプロパティQT_QML_SOURCE_TYPENAME を目的の型名に設定することも可能です。

シングルトン

QMLモジュールにシングルトン型を提供する.qml ファイルが含まれている場合、singleton コマンドがqmldirファイルに書き込まれるように、これらのファイルのQT_QML_SINGLETON_TYPE ソースプロパティをTRUE に設定する必要があります。これは、pragma Singleton ステートメントを含むQMLファイルの設定に加えて行う必要があります。ソースプロパティは、シングルトンが属するモジュールを作成する前に設定する必要があります。

QT_QML_SINGLETON_TYPE プロパティの設定方法の例については、qt_target_qml_sources()を参照してください。

QML タイプコンパイラを使用した QML から C++ へのコンパイル

QMLモジュールに.qml ファイルが含まれている場合、qmltcを使用してそれらをC++にコンパイルできます。バイトコードコンパイルとは異なり、ENABLE_TYPE_COMPILER引数を介してqmltcを明示的に有効にする必要があります。その場合、QML_FILES で指定された.qml ファイルがコンパイルされます。 qmltcはJavaScriptコードをコンパイルしないため、.js および.mjs で終わるファイルは無視されます。さらに、ソースファイルプロパティでQT_QML_SKIP_TYPE_COMPILERが指定されているファイルもスキップされます。

デフォルトでは、qmltc は指定された `.qml ` ファイルに対して、小文字の `.h ` および `.cpp ` ファイルを作成します。たとえば、`Foo.qml ` は最終的に `foo.h ` および `foo.cpp` にコンパイルされます。

生成されたC++ファイルは、target のBINARY_DIR ディレクトリ内の専用の.qmltc/<target>/ サブディレクトリに配置されます。これらのファイルはその後、ターゲットソースに自動的に追加され、他のソースファイルとともにQt C++コードとしてコンパイルされます。

QML_FILESの処理中、以下のソースファイルのプロパティが考慮されます：

• QT_QMLTC_FILE_BASENAME: このソースファイルプロパティを使用して、デフォルトとは異なる .h および .cpp ファイル名を指定します。これは、例えばファイル名の競合を解決する場合に役立ちます（コンパイル対象の main.qml があるものの、main.h がすでに存在しており、#include "main.h" が期待どおりに動作しない可能性がある場合などを想定してください）。 QT_QMLTC_FILE_BASENAME はファイル名（拡張子なし）であることが想定されているため、先頭のディレクトリ部分は無視されます。デフォルトの動作とは異なり、QT_QMLTC_FILE_BASENAME は小文字に変換されません。
• QT_QML_SKIP_TYPE_COMPILER: このソースファイルプロパティを使用して、qmltc によって QML ファイルが無視されるように指定します。

引数

qt_add_qml_module の引数は、以下のカテゴリに分類されます。

必須の引数

target は、QML モジュールの基盤となるターゲットの名前を指定します。デフォルトでは、Qt が共有ライブラリとしてビルドされている場合は共有ライブラリとして、それ以外の場合は静的ライブラリとして作成されます。この設定は、STATIC またはSHARED オプションを使用して明示的に上書きすることができます。

すべてのQMLモジュールは、URI を定義する必要があります。これは、QtQuick.Layouts のようなドット区切りのURI表記で指定する必要があります。各セグメントは、正規のECMAScript識別子名でなければなりません。つまり、例えば、セグメントは数字で始まってはならず、-（マイナス）文字を含んではなりません。URI はディレクトリ名に変換されるため、ラテンアルファベットの英数字、アンダースコア、およびドットに限定する必要があります。 他の QML モジュールでは、この名前をimport 文で使用してモジュールをインポートする場合があります。URI は、生成されたqmldirファイル内の `module ` 行で使用されます。また、URI は、ドットをスラッシュに置き換えてターゲットパスを形成する際にも使用されます。

モジュール URI に関するより詳細な説明については、「識別されたモジュール」を参照してください。

バージョン

QMLモジュールは、Major.Minor という形式でVERSION を定義することもできます。この場合、Major とMinor はいずれも整数でなければなりません。追加の.Patch コンポーネントを付加することもできますが、これは無視されます。また、PAST_MAJOR_VERSIONS キーワードの後に、そのモジュールが型を提供する以前のメジャーバージョンのリストをオプションで指定することもできます（後述）。 バージョン番号付けに関するより詳細な説明については「Identified Modules」を、過去のメジャーバージョンの登録については「Registering past major versions」を、モジュールバージョンの同期保持については「Keeping module versions in sync」を参照してください。

バージョンを指定する必要がない場合は、VERSION 引数を省略してください。デフォルトでは、可能な限り高いバージョンが設定されます。QMLモジュールの内部バージョン管理には、いくつかの根本的な欠点があります。QMLモジュールの異なるバージョンを管理するには、外部のパッケージ管理メカニズムを使用することをお勧めします。

モジュールへのソースおよびリソースの追加

SOURCES は、バッキングターゲットに追加するQML以外のソースのリストを指定します。これは利便性のために提供されており、組み込みのCMakeコマンド `target_sources() ` を使用してバッキングターゲットにソースを追加することと同等です。

QML_FILES モジュール用の.qml 、.js 、および.mjs ファイルのリストを指定します。NO_CACHEGEN オプションが指定されていない限り、これらは自動的にバイトコードにコンパイルされ、バッキングターゲットに埋め込まれます。NO_CACHEGEN が指定されている場合でも、未コンパイルのファイルは常にバッキングターゲットの埋め込みリソースに格納されます。NO_LINT オプションが指定されていない限り、未コンパイルのファイルは、別のカスタムビルドターゲットを介して qmllint によっても処理されます。 また、これらのファイルはデフォルトで、生成されるqmldirファイルの型情報を埋めるためにも使用されます。NO_GENERATE_QMLDIR を指定することで、qmldir ファイルの自動生成を無効にできます。通常はこれを避けるべきですが、プロジェクトで独自のqmldir ファイルを用意する必要がある場合は、このオプションを使用できます。 Qt 6.8 以降、QTP0004が有効になっている場合、qt_add_qml_module は QML モジュール内の各サブディレクトリに対して追加のqmldir ファイルを作成します。これにより、各 QML ファイルが暗黙のインポートを通じて自身のモジュールをインポートするようになります。この動作は、QML モジュールに対してNO_GENERATE_EXTRA_QMLDIRS フラグを渡すことで無効にできます。NO_GENERATE_QMLDIR はNO_GENERATE_EXTRA_QMLDIRS を意味します。

RESOURCES には、QMLコードから参照される画像など、モジュールに必要なその他のファイルが列挙されます。これらのファイルは、コンパイル済みリソースとして追加されます（これらのファイルが配置される基点については、RESOURCE_PREFIXを参照してください）。 必要に応じて、.qml ファイルと同様に、QT_RESOURCE_ALIAS ソースプロパティを設定することで、これらのファイルの相対的な配置を制御できます（「コンパイル済みQMLソースのキャッシュ」を参照）。

RESOURCE_PREFIX は、プロジェクトのネームスペースをカプセル化することを目的としており、多くの場合、プロジェクトが定義するすべてのQMLモジュールで同じものになります。

ただし、代わりにQTP0001CMake ポリシーを設定することをお勧めします。これにより、QML モジュールが QML エンジンのデフォルトのインポートパスのいずれかに確実に配置されるよう、デフォルトのリソースプレフィックスが定義されます。

RESOURCE_PREFIX を設定する場合は、QMLエンジンがQMLモジュールを検出できるよう、そのパスをインポートパスにも追加する必要があります。

QTP0001が有効になっている場合（例：qt_standard_project_setup(REQUIRES 6.5) 経由）、デフォルト値は"/qt/qml/" となります。そうでない場合は"/" となります。

コンパイル済みリソースにさまざまなファイルが追加されると、それらはRESOURCE_PREFIX とターゲットパスを連結して形成されたパス下に配置されます。 バッキングターゲットが実行ファイルであるという特殊なケースでは、モジュールの.qml ファイルやその他のリソースを、代わりにRESOURCE_PREFIX の直下に配置した方が望ましい場合があります。これは、NO_RESOURCE_TARGET_PATH オプションを指定することで実現できますが、このオプションはバッキングターゲットが実行ファイルである場合にのみ使用可能です。

過去のメジャーバージョンの登録

PAST_MAJOR_VERSIONS には、モジュールが提供する追加のメジャーバージョンのリストが含まれています。これらの各バージョンおよびQT_QML_SOURCE_VERSIONS 設定のない各QMLファイルについて、qmldirファイル内に追加のエントリが生成され、その追加バージョンが指定されます。さらに、生成されたモジュール登録コードは、C++側でqmlRegisterModule()を使用して、過去のメジャーバージョンを登録します。NO_GENERATE_QMLTYPES を指定しない限り、QMLモジュール用のモジュール登録コードは自動的に生成されます（ただし、このオプションの使用は強く推奨されません）。PAST_MAJOR_VERSIONS を使用すると、モジュールがインポートされる際に若干のオーバーヘッドが発生します。モジュールのメジャーバージョンは、できるだけ頻繁に変更しないようにしてください。 このモジュールをインポートするすべてのQMLファイルが、インポート時にバージョンを省略することが確実になったら、PAST_MAJOR_VERSIONS を安全に省略できます。そうすれば、すべてのQMLファイルがモジュールの最新バージョンをインポートするようになります。バージョン指定のインポートをサポートする必要がある場合は、過去のメジャーバージョンのうち、限られた数のみをサポートすることを検討してください。

モジュールの依存関係の宣言

IMPORTS には、このモジュールがインポートする他のQMLモジュールのリストが指定されます。ここにリストされた各モジュールは、生成されるqmldirファイル内のimport エントリとして追加されます。QMLファイルがこのモジュールをインポートする場合、IMPORTS の下にリストされているすべてのモジュールも同時にインポートされます。 オプションとして、スラッシュの後にバージョンを指定することもできます（例：QtQuick/2.0 ）。バージョンを省略すると、利用可能な最新バージョンがインポートされます。QtQuick/2 のように、メジャーバージョンのみを指定することも可能です。その場合、指定されたメジャーバージョンで利用可能な最新のマイナーバージョンがインポートされます。 最後に、auto をバージョンとして指定することも可能です（例：QtQuick/auto ）。auto を指定すると、現在のモジュールがインポートされているバージョンが、インポート対象のモジュールに引き継がれます。モジュールYourModule にQtQuick/auto というエントリがある場合、QML ファイルでimport YourModule 3.14 を指定すると、QtQuick のバージョン3.14 がインポートされます。共通のバージョン管理スキームに従う関連モジュールについては、auto を使用する必要があります。

IMPORTS 内のエントリは、ターゲット名の先頭にTARGET キーワードを付けることで、CMakeターゲットを参照することもできます。この場合、QMLモジュールのURIはターゲットから自動的に決定されます。これには、CMakeポリシーQTP0005の適用が必要です。

たとえば、QMLモジュールは、そのモジュールを提供するCMakeターゲットを参照することで、別のモジュールをインポートできます:

qt_add_qml_module(my_module
    URI MyModule
    VERSION 1.0
    IMPORTS
        TARGET OtherQmlModule
)

OPTIONAL_IMPORTS は、このモジュールが実行時にインポート可能な他のQMLモジュールのリストを提供します。これらは、現在のモジュールをインポートする際にQMLエンジンによって自動的にインポートされるものではなく、qmllint などのツールに対するヒントとして機能します。バージョンは、IMPORTS と同様に指定できます。ここにリストされた各モジュールは、生成されるqmldirファイル内に optional import エントリとして追加されます。

OPTIONAL_IMPORTS 内のエントリは、ターゲット名の先頭にTARGET キーワードを付けることで、CMakeターゲットを参照することもできます。この場合、QMLモジュールのURIはターゲットから自動的に決定されます。これを行うには、CMakeポリシーQTP0005を有効にする必要があります。

例：

qt_add_qml_module(my_module
    URI MyModule
    VERSION 1.0
    OPTIONAL_IMPORTS
        TARGET OptionalQmlModule
)

DEFAULT_IMPORTS は、オプションのインポートのうち、ツールによって読み込まれるべきデフォルトのエントリを指定します。モジュール内のOPTIONAL_IMPORTS のグループごとに、1つのエントリを指定する必要があります。オプションのインポートは実行時にのみ解決されるため、qmllintのようなツールは、一般的にどのオプションのインポートを解決すべきかを知ることができません。 この問題を解決するために、オプションのインポートの1つをデフォルトのインポートとして指定することができます。そうすれば、ツールはそのインポートを選択します。追加の設定なしに実行時に使用されるオプションのインポートが1つある場合、それがデフォルトのインポートとして最適な候補となります。

DEFAULT_IMPORTS 内のエントリは、ターゲット名の前にTARGET キーワードを付けることで、CMakeターゲットを参照することもできます。この場合、QMLモジュールのURIはターゲットから自動的に決定されます。これには、CMakeポリシーQTP0005の適用が必要です。

例：

qt_add_qml_module(my_module
    URI MyModule
    VERSION 1.0
    OPTIONAL_IMPORTS
        TARGET BackendA
        TARGET BackendB
    DEFAULT_IMPORTS
        TARGET BackendA
)

DEPENDENCIES は、このモジュールが依存しているが、必ずしもインポートするわけではない他のQMLモジュールのリストを提供します。これは通常、C++レベルでのみ存在する依存関係に使用されます。例えば、別のモジュールで定義されたC++型を使用または継承するクラスをQMLに登録するモジュールなどが該当します。

例えば、次のようにQQuickItem をサブクラス化したい場合：

class MyItem: public QQuickItem { ... };

この場合、`QQuickItem` を含むモジュール（QtQuick ）が、DEPENDENCIES オプションを介して依存関係として宣言されていることを確認する必要があります：

qt_add_qml_module(myTarget
    ...
    DEPENDENCIES QtQuick
)

そうしないと、リンティングエラーが発生したり、qmltcによる型コンパイル中、あるいはqmlcachegen による C++ へのバインディングおよび関数コンパイル中にエラーが発生する可能性があります。

別の例としては、次のようなものがあります:

class MyComponent : public QObject {
    Q_OBJECT
    QML_ELEMENT

    // ...

signals:
    void sigZoomAtMousePosition(const QPointF& aMousePos, double aZoomScaleFactor);
};

ここでは、QMLツールが `QPointF` を見つけ、使用するためには `DEPENDENCIES QtQml ` が必要です：

qt_add_qml_module(myTarget
    ...
    DEPENDENCIES QtQml
)

DEPENDENCIES 内のエントリは、ターゲット名の先頭にTARGET キーワードを付けることで、CMake ターゲットを参照することもできます。この場合、QML モジュールの URI およびインポートパスは、ターゲットから自動的に決定されます。これには、CMake ポリシーQTP0005 を有効にする必要があります。

たとえば、QMLモジュールは、それを提供するCMakeターゲットを参照することで、別のモジュールへの依存関係を宣言できます:

qt_add_qml_module(my_module
    URI MyModule
    VERSION 1.0
    DEPENDENCIES
        TARGET OtherQmlModule
)

バッキングターゲットが実行ファイルであり、TARGET の依存関係が使用される場合（QTP0005が必要）、qt_add_qml_module() はビルドツリー内の実行ファイルの隣にqt.conf ファイルを自動的に生成します。このファイルはQMLインポートパスを設定し、手動でIMPORT_PATH ファイルに記述することなく、実行時にQMLエンジンがモジュールの依存関係を検出できるようにします。NO_GENERATE_QTCONF オプションを指定すると、この動作が抑制されます。これは、生成されたファイルがビルドディレクトリにすでに存在するqt.conf と競合する場合などに必要となる可能性があります。このオプションはQt 6.12で導入されました。

依存関係のモジュールバージョンは、モジュール名とともに、IMPORTS やOPTIONAL_IMPORTS で使用されるのと同じ形式で指定する必要があります。ここにリストされた各モジュールは、生成されるqmldirファイル内にdepends エントリとして追加されます。

IMPORT_PATH を使用すると、このモジュールが依存する他の QML モジュールが見つかる検索パスに追加できます。他のモジュールについては、検索パスのいずれかの下にある独自のターゲットパス内に、qmldir ファイルが存在する必要があります。Qt は、IMPORT_PATH 以下のすべてのファイルが信頼できるソースからのものであると想定します。

バックイングターゲットが静的ライブラリであり、その静的ライブラリがインストールされる場合、OUTPUT_TARGETS を指定して、同様にインストールが必要な追加ターゲットのリストを格納する変数を用意する必要があります。これらの追加ターゲットはqt_add_qml_module() によって内部的に生成され、リソースが正しく設定および読み込まれることを保証するための一環として、バックイングターゲットのリンク要件によって参照されます。

ターゲットとプラグインターゲット

以下のオプションは、プラグインターゲットの作成および設定方法を制御します。ほとんどのモジュールでは、デフォルト設定で適切であり、これらのオプションはいずれも必要ありません。一般的なシナリオ：

• デフォルト— 生成されたソースファイルを含む個別のプラグインターゲットが自動的に作成されます。このプラグインはオプションであり（バックエンドライブラリが直接リンクされた場合は読み込まれません）。
• カスタムプラグイン—NO_GENERATE_PLUGIN_SOURCEを使用して、独自のプラグインクラス実装を提供します。また、CLASS_NAME を独自のプラグインクラス名に合わせて設定する必要があります。通常、プラグインには複雑なコードが含まれるため、NO_PLUGIN_OPTIONALの設定も必要になります。
• プラグインなし— モジュールが常に直接リンクされ、動的にロードされることがない場合は、NO_PLUGINを使用します。
• 実行可能ターゲット— プラグインは自動的に作成されません。

PLUGIN_TARGET QMLモジュールに関連付けられるプラグインターゲットを指定します。PLUGIN_TARGET は、バッキングターゲットであるtarget と同じにすることも可能です。その場合、個別のバッキングターゲットは存在しません。PLUGIN_TARGET が指定されていない場合、デフォルトではtarget にplugin が付加されたものが使用されます。 たとえば、mymodule という名前のバッキング・ターゲットの場合、デフォルトのプラグイン名はmymoduleplugin となります。プラグイン・ターゲットの名前は、生成されるqmldirファイル内のplugin 行に設定される値として使用されます。したがって、OUTPUT_NAME やその関連プロパティなどのターゲット・プロパティを設定して、プラグインの出力名を変更しようとしないでください。

バックエンドのtarget およびプラグインターゲット（異なる場合）は、すでに存在しない限り、コマンドによって作成されます。プロジェクトでは、適切なターゲットタイプとして作成されるよう、通常はコマンドによる作成を許可する必要があります。バックエンドのtarget が静的ライブラリの場合、プラグインも静的ライブラリとして作成されます。 バッキングのtarget が共有ライブラリの場合、プラグインはモジュールライブラリとして作成されます。既存のtarget が渡され、それが実行可能ターゲットである場合、プラグインは作成されません。常にバッキングターゲットに直接リンクするつもりで、プラグインを必要としない場合は、NO_PLUGIN オプションを追加することでプラグインを無効にできます。NO_PLUGIN とPLUGIN_TARGET の両方を指定するとエラーとなります。

状況によっては、プロジェクトが呼び出しが完了するまでプラグインターゲットの作成を遅らせたい場合があります。その場合は、NO_CREATE_PLUGIN_TARGET オプションを指定できます。その場合、プロジェクトはプラグインターゲットが作成された後に、そのターゲットに対してqt_add_qml_plugin()を呼び出すことが期待されます。NO_CREATE_PLUGIN_TARGET が指定された場合、プラグインターゲットを明示的に指定するためにPLUGIN_TARGET も指定する必要があります。

デフォルトでは、qt_add_qml_module() は、CLASS_NAME 引数で指定されたプラグインクラスを実装する.cpp ファイルを自動生成します。生成された.cpp ファイルは、コンパイル対象のソースファイルとしてプラグインターゲットに自動的に追加されます。 プロジェクトでプラグインクラスの独自の実装を提供したい場合は、NO_GENERATE_PLUGIN_SOURCE オプションを指定する必要があります。CLASS_NAME が指定されていない場合、デフォルトでは「URI 」のドットをアンダースコアに置き換え、その後に「Plugin 」を付加したものが使用されます。QMLモジュールにプラグインが存在しない場合を除き、クラス名は生成されたqmldirファイル内の classname 行として記録されます。 カスタムプラグインコードを含む C++ ファイルは、plugin ターゲットに追加する必要があります。プラグインには、単にバックエンドライブラリをロードする以上の機能が含まれている可能性が高いので、NO_PLUGIN_OPTIONAL も追加することをお勧めします。そうしないと、QML エンジンは、バックエンドライブラリがすでにリンクされていることを検出した場合、プラグインのロードをスキップしてしまう可能性があります。

NO_PLUGIN キーワードが指定された場合、プラグインはビルドされません。 したがって、このキーワードは、プラグインターゲットをカスタマイズするすべてのオプション、特にNO_GENERATE_PLUGIN_SOURCE、NO_PLUGIN_OPTIONAL、PLUGIN_TARGET、NO_CREATE_PLUGIN_TARGET、およびCLASS_NAME と互換性がありません。 モジュールにプラグインを指定しない場合、そのモジュールを完全に利用するには、その基盤となるライブラリが実行ファイルにリンクされている必要があります。リンカーが、未使用とみなしたライブラリへのリンク関係を維持することを保証するのは、一般的に困難です。

NO_PLUGIN_OPTIONAL キーワードが指定された場合、そのプラグインは生成されたqmldir ファイルに「非オプション」として記録されます。QMLモジュールのすべての機能がそのバックイングターゲットで実装されており、プラグインターゲットが別個のものである場合、そのプラグインはオプションにすることができます。これがデフォルトであり、推奨される構成です。 自動生成されたプラグインのソースファイルはこの要件を満たしています。プロジェクトがプラグイン用に独自の.cpp 実装を提供する場合、プラグインにはほぼ確実にQMLモジュールが必要とする機能が含まれるため、通常はNO_PLUGIN_OPTIONAL キーワードも必要となります。

自動型登録

qt_add_qml_module は、いくつかのファイルを自動的に生成します。以下のオプションは、生成される内容を制御します。ほとんどの場合、デフォルト設定で問題なく、これらのオプションは一切必要ありません。

AUTOMOC によって処理されるバックイングターゲットの C++ ソースに対して、型登録が自動的に行われます。これにより、出力ディレクトリに typeinfo ファイルが生成され、そのファイル名はtarget 名に.qmltypes が付加されたものになります。必要に応じて、TYPEINFO オプションを使用してこのファイル名を変更できますが、通常は変更する必要はありません。 また、このファイル名は、生成されたqmldirファイル内のtypeinfo エントリとしても記録されます。NO_GENERATE_QMLTYPES オプションを使用すると、自動型登録を無効にできます。この場合、typeinfo ファイルは生成されませんが、プロジェクトは依然として typeinfo ファイルを生成し、生成されたqmldir ファイルと同じディレクトリに配置することが期待されます。

OUTPUT_DIRECTORY プラグインライブラリ、qmldir 、および typeinfo ファイルが生成される場所を指定します。このキーワードが指定されていない場合、デフォルト値は、QT_QML_OUTPUT_DIRECTORY変数の値にターゲットパス（URI から形成される）を付加したものです。その変数が定義されていない場合、デフォルト値はバッキングターゲットの種類によって異なります。 実行ファイルの場合、値はターゲットパスに${CMAKE_CURRENT_BINARY_DIR} を付加したものであり、その他のターゲットの場合は単に${CMAKE_CURRENT_BINARY_DIR} となります。ソースツリーの構造がQMLモジュールのターゲットパスの構造と一致している場合（強く推奨されます）、QT_QML_OUTPUT_DIRECTORYは多くの場合不要です。 ターゲットパスの構造と一致させるには、ディレクトリ名をモジュールURIのセグメントと完全に同じ名前にする必要があります。たとえば、モジュールURIがMyUpperCaseThing.mylowercasething である場合、MyUpperCaseThing/mylowercasething/ という名前のディレクトリに配置する必要があります。

OUTPUT_DIRECTORY キーワードを指定する必要性は稀ですが、使用する場合、呼び出し元はIMPORT_PATHにも追加する必要があるでしょう。そうすることで、linting、QMLソースのキャッシュコンパイル、静的ビルドにおけるプラグインの自動インポート、および非静的ビルドでのインポート済みQMLモジュールのデプロイがすべて正しく機能するようになります。

Qt Quick Designerとの互換性

DESIGNER_SUPPORTED QMLモジュールがQt Quick Designerに対応している場合は、これを指定する必要があります。指定されている場合、生成されたqmldir ファイルにはdesignersupported 行が含まれます。これがQt Quick Designerによるプラグインの処理にどのような影響を与えるかについては、「モジュール定義のqmldirファイル」を参照してください。

モジュールバージョンの同期を維持する

FOLLOW_FOREIGN_VERSIONING キーワードは、異なるQMLモジュールに存在する、C++で定義された独自のQML型の基底型に関連します。通常、モジュールのバージョン管理方式は、基底型を提供するモジュールのそれとは一致しません。 そのため、デフォルトでは、モジュールのインポート時に、基底型のすべてのリビジョンが利用可能になります。FOLLOW_FOREIGN_VERSIONING を指定すると、基底型およびそのプロパティに付随するバージョン情報が尊重されます。 したがって、import MyModule 2.8 を指定した場合、MyModule 以外のベース型のバージョン2.8 までのプロパティのみが利用可能になります。これは主に、モジュールのバージョンを、ベースとしている他のモジュールと同期させたい場合に役立ちます。その場合、インポートされているバージョンよりも新しいバージョンのモジュールのベース型から、カスタム型がプロパティを公開しないようにしたい場合があります。

生成されたコードの C++ 名前空間

NAMESPACE キーワードで名前空間が指定された場合、プラグインおよび登録コードは、この名前のC++名前空間内に生成されます。

qmlimportscanner および NO_IMPORT_SCAN

静的Qtビルドの場合、configure実行時にqmlimportscanner が実行され、QMLモジュールの.qml ファイルがスキャンされ、そのモジュールが使用するQMLインポートが特定されます（qt_import_qml_plugins()を参照）。 非静的Qtビルドの場合、ターゲットが実行可能ファイルであるときは、デプロイメントスクリプトに必要な情報を提供するために、ビルド時に同様のスキャンが実行されます（qt_deploy_qml_imports()を参照）。NO_IMPORT_SCAN オプションを指定することで、両方のスキャンを無効にできます。 これを行うと、静的ビルドにおいて、必要なすべてのプラグインがインスタンス化され、リンクされることを確保する責任がプロジェクト側に移ります。非静的ビルドの場合、プロジェクト側は実行可能ターゲットで使用されるすべての QML モジュールを手動で特定し、デプロイする必要があります。

DISCARD_QML_CONTENTS

デフォルトでは、QML および JS ソースファイルの内容はターゲットのリソースシステムに含まれます。DISCARD_QML_CONTENTS を使用すると、これらの内容を削除し、バイナリサイズを縮小できます。

qmltc の引数

ENABLE_TYPE_COMPILER qmltc を使用して、.qml ファイルをC++ソースコードにコンパイルするために使用できます。sourceプロパティがQT_QML_SKIP_TYPE_COMPILER に設定されているファイルは、C++にコンパイルされません。

TYPE_COMPILER_NAMESPACE この引数を使用すると、qmltc がコードを生成する名前空間を上書きすることができます。デフォルトでは、生成されるコードの名前空間は、URI に示されているモジュール階層に従います。例えば、URI がMyModule のモジュールではMyModule となり、URI がcom.example.MyModule の場合はcom::example::Module となります。TYPE_COMPILER_NAMESPACE オプションを指定することで、生成されたコードをカスタムネームスペースに配置することができます。この場合、異なるサブネームスペースは「::」で区切られます。例えば、MyNamespace内に存在するMySubnamespaceというネームスペースの場合は「MyNamespace::MySubnamespace」となります。 「::」を除き、C++ の名前空間の命名規則が適用されます。

QMLTC_EXPORT_DIRECTIVE qmltcによって生成されたクラスを qml ライブラリからエクスポートする必要がある場合は、QMLTC_EXPORT_FILE_NAME とともに使用してください。デフォルトでは、qmltc によって生成されたクラスはライブラリからエクスポートされません。 現在のライブラリのエクスポートマクロを定義するヘッダーは、QMLTC_EXPORT_FILE_NAME のオプション引数として指定できますが、エクスポートマクロ名はQMLTC_EXPORT_DIRECTIVE の引数として指定する必要があります。追加のインクルードが必要ない、または不要な場合（例えば、エクスポートマクロのヘッダーが基底クラスによって間接的にすでにインクルードされている場合など）、QMLTC_EXPORT_FILE_NAME オプションは省略できます。