qt_add_qml_module

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

概要

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_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]

)

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

QMLモジュールを定義した例としては、Building a QML applicationと Building a reusable QML moduleを参照してください。

QMLモジュールに関する情報がQML言語サーバーに公開されるようにプロジェクトを 設定する方法についてはQT_QML_GENERATE_QMLLS_INIを参照してください。

説明

このコマンドはQMLモジュールを定義するもので、C++ソース、.qml ファイル、あるいはその両方から構成されます。モジュールの詳細が提供され、一貫性が保たれていることを確認します。また、.qml のソースのキャッシュコンパイル、リソースの埋め込み、リンティングチェック、いくつかの重要なモジュールファイルの自動生成などの設定や調整も行います。

ターゲット構造

QMLモジュールはいくつかの異なる方法で構造化することができます。以下のシナリオは典型的なものです：

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

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

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

次の例は、MyThings.Panels というURIを持つQMLモジュールに適したソースディレクトリ構造を示しています。qt_add_qml_module() への呼び出しは、CMakeLists.txt ファイル内にあります。

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

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

プラグインターゲットには、プラグインクラスの些細な実装しか含まれていないことが理想的です。これにより、qmldir ファイルでプラグインをオプションとして指定することができます。他のターゲットはバッキング・ターゲットに直接リンクすることができ、プラグインは実行時に不要になるため、ロード時のパフォーマンスが向上します。デフォルトでは、最小限のプラグインクラスを定義したC++ソースファイルが自動的に生成され、プラグインターゲットに追加されます。QMLモジュールがカスタムプラグインクラスの実装を必要とする場合には、NO_GENERATE_PLUGIN_SOURCEオプションと、通常はNO_PLUGIN_OPTIONALオプションが必要になります。

NO_PLUGIN が指定されていない場合、STATIC QMLモジュールは静的な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モジュールのターゲットパスと一致することは期待できません。コンパイル済みリソースのターゲットパスの違いについてはCaching compiled QML sourcesを参照してください。

qmldir 、typeinfoファイルの自動生成

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

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

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

バッキングターゲットの 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 ファイルはバイトコードにコンパイルされ、バッキングターゲットに直接キャッシュされます。これにより、モジュールのロード時のパフォーマンスが向上します。コンパイルされていないオリジナルのファイルもバッキングターゲットの リソースに保存されます。

各ファイルのリソースパスは現在のソースディレクトリ(CMAKE_CURRENT_SOURCE_DIR)からの相対パスで決定されます。このリソースパスには、RESOURCE_PREFIXとターゲットパスを連結したプレフィックスが付加されます（ただし、NO_RESOURCE_TARGET_PATHを参照）。

QTP0001ポリシーがNEW に設定されている場合、RESOURCE_PREFIXのデフォルトはQMLエンジンのデフォルトインポートパスである/qt/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"
)

もう一つの重要な引数は--direct-calls です。これを使うと、Qt Quick Compiler Extensions がインストールされている場合に、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++ にコンパイルできない関数ごとに警告を出力します。このフラグを設定すると、qmlcachegenはC++にコンパイルできない関数ごとに警告を出力します。これらの警告の中には、QMLコードに問題があることを示すものや、QML言語の特定の機能がC++コードジェネレータに実装されていないことを示すものがあります。どちらの場合でも、qmlcachegen はそのような関数のバイトコードを生成します。QMLコードの問題点だけを確認したい場合は、qmllintとそのために生成されたターゲットを代わりに使用してください。

QMLソースのリンティング

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

.js ファイルの命名規則

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

また、小文字のファイル名を使用し、ソースファイルのプロパティQT_QML_SOURCE_TYPENAMEに希望の型名を設定することもできます。

シングルトン

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

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このソースファイルプロパティは、QMLファイルをqmltcが無視するように指定するために使用します。

引数

必要な引数

target はQMLモジュールのバッキングターゲットの名前を指定します。デフォルトでは、Qtが共有ライブラリとしてビルドされた場合は共有ライブラリとして、そうでない場合はスタティックライブラリとして作成されます。この選択はSTATIC またはSHARED オプションで明示的に上書きすることができます。

全てのQMLモジュールはURI を定義しなければなりません。QtQuick.Layouts のようにドット付きURI表記で指定します。各セグメントは整形式の ECMAScript Identifier Name でなければなりません。これは例えば、セグメントが数字で始まったり、-(マイナス)文字を含んではならないことを意味します。URI はディレクトリ名に変換されるため、ラテンアルファベットの英数字、アンダースコア、ドットに限定する必要があります。他のQMLモジュールでは、この名前をimport文の中で使ってモジュールをimportすることがあります。URI は生成されるqmldirファイルのmodule 行で使われます。また、URI はドットをスラッシュに置き換えてターゲットパスを形成する際にも使用されます。

モジュールURIの詳細については、識別されたモジュールを参照してください。

バージョン

QMLモジュールでは、Major.Minor という形式でVERSION を定義することもできます。Major とMinor はともに整数でなければなりません。さらに.Patch を追加することもできますが、無視されます。また、PAST_MAJOR_VERSIONS キーワードの後に、そのモジュールが提供するメジャーバージョン以前の型のリストを指定することもできます(後述)。バージョン番号の付け方については「識別モジュール」、過去のメジャーバージョンの登録については「過去のメジャーバージョンの登録」、モジュールのバージョンの同期については「モジュールのバージョンの同期」を参照してください。

バージョンが必要ない場合は、VERSION 引数を省略する必要があります。デフォルトは可能な限り高いバージョンです。QMLモジュールの内部バージョン管理には根本的な欠陥があります。QMLモジュールの異なるバージョンを管理するためには、外部のパッケージ管理機構を使うべきです。

モジュールへのソースとリソースの追加

SOURCES はバッキングターゲットに追加する非QMLソースのリストを指定します。これは便宜的に提供されているもので、組み込みの CMake コマンドでバッキングターゲットにソースを追加するのと同じです。target_sources()

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

RESOURCES は、QML コードから参照されるイメージなど、モジュールが必要とする その他のファイルをリストします。これらのファイルはコンパイルされたリソースとして追加されます (ベースポイントについてはRESOURCE_PREFIX を参照してください)。必要であれば、 ファイルと同様に、 source プロパティを設定することで、相対的な位置を制御することができます（.qml QT_RESOURCE_ALIAS コンパイル済みQMLソースのキャッシュを参照）。

RESOURCE_PREFIX はプロジェクトの名前空間をカプセル化するためのもので、プロジェクトが定義するすべてのQMLモジュールに対して同じ名前空間が設定されます。また、プロジェクトが定義するすべてのQMLモジュールで同じ名前になることが多いでしょう。この名前空間は、プロジェクトが使用するリソース接頭辞や、他のプロジェクトが使用する可能性のあるリソース接頭辞と衝突しないように選択する必要があります。プロジェクトが所属する組織のドメイン名を組み込むのがよい選択です。一般的な慣例としては、ドメイン名に を付加してリソース接頭辞とします。例えば/imports

qt_add_qml_module(someTarget
    RESOURCE_PREFIX /my.company.com/imports
    ...
)

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

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

PAST_MAJOR_VERSIONS には、モジュールが提供する追加メジャーバージョンのリストが含まれています。これらのバージョンと、 の設定がない各QMLファイルに対して、QT_QML_SOURCE_VERSIONS qmldirファイルに追加エントリが生成され、追加バージョンが指定されます。さらに、生成されたモジュール登録コードは、C++側で () を使って過去のメジャーバージョンを登録します。モジュール登録コードは、 を指定しない限り、QMLモジュールに対して自動的に生成されます（ただし、このオプションの使用は強く推奨されません）。 を使用すると、モジュールがインポートされる際にオーバーヘッドが発生します。モジュールのメジャーバージョンはできるだけ増やさないようにしてください。このモジュールをインポートするすべてのQMLファイルがインポート時にバージョンを省略することを信頼できるようになれば、 を省略しても大丈夫です。すべてのQMLファイルが最新バージョンのモジュールをインポートするようになります。もし、バージョン指定のインポートをサポートしなければならないのであれば、過去のメジャーバージョンのうち、限られたものだけをサポートするようにしてください。qmlRegisterModule NO_GENERATE_QMLTYPES PAST_MAJOR_VERSIONS PAST_MAJOR_VERSIONS

モジュール依存性の宣言

IMPORTS には、このモジュールがインポートする他のQMLモジュールの一覧が表示されます。ここに列挙された各モジュールは、生成されたqmldirファイルの エントリとして追加されます。QML ファイルがこのモジュールをインポートする場合、 にリストされているすべてのモジュールもインポートされます。オプションとして、 のように、スラッシュの後にバージョンを付けて指定することもできます。バージョンを省略すると、利用可能な最大のバージョンがインポートされます。 のようにメジャーバージョンのみを指定することもできます。 この場合、指定されたメジャーバージョンで利用可能な最大のマイナーバージョンがインポートされます。最後に、 に version ( ) を指定することもできる。 が与えられた場合、現在のモジュールがインポートされているバージョンは、 インポートされるモジュールに伝搬されます。あるモジュール に というエントリーがあった場合、QMLファイルで を指定すると、 のバージョン をインポートすることになります。共通のバージョニングスキームに従っている関連モジュールの場合は、 を使うべきです。import IMPORTS QtQuick/2.0 QtQuick/2 autoQtQuick/auto auto YourModule QtQuick/auto import YourModule 3.14 QtQuick 3.14 auto

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

DEFAULT_IMPORTS は、オプションのインポートのうち、ツーリングによってロードされるデフォルトのエントリーを指定します。モジュール内の のグループごとに1つのエントリを指定する必要があります。オプションのインポートは実行時にしか解決されないので、qmllintのようなツールは一般的にどのオプションのインポートが解決されるべきかを知ることができません。これを解決するには、オプションのインポートの1つをデフォルトのインポートとして指定します。もし、これ以上の設定なしに実行時に使用されるオプションのインポートが1つでもあれば、それはデフォルトのインポートとして理想的な候補です。OPTIONAL_IMPORTS

DEPENDENCIES は、このモジュールが依存する他のQMLモジュールのリストです。例えば、他のモジュールで定義されているクラスのサブクラスを QML に登録するような場合です。

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

class MyItem: public QQuickItem { ... };

のようにサブクラス化したい場合、Quick というQQuickItem を含むモジュールがDEPENDENCIES オプションで依存関係として宣言されていることを確認する必要があります。そうしないと、qmltcによる型コンパイル時や、qmlcachegenによるC++へのバインディングや関数コンパイル時にエラーが発生する可能性があります。

依存モジュールのバージョンは、IMPORTS やOPTIONAL_IMPORTS で使われるのと同じ形式で、モジュール名と一緒に指定しなければなりません。ここに列挙された各モジュールは、生成されたqmldirファイルにdepends エントリとして追加されます。

IMPORT_PATH は、このモジュールが依存する他の QML モジュールを検索するためのパスです。他のモジュールは ファイルを検索パスの一つ下のターゲットパスに置く必要があります。qmldir

バッキングターゲットがスタティックライブラリで、そのスタティックライブラリがインストー ルされる場合、OUTPUT_TARGETS 、インストールが必要な追加ターゲットのリ ストを格納する変数を指定する必要があります。これらの追加ターゲットは、qt_add_qml_module() によって内部的に生成され、リソースが正しくセットアップされロードされることを保証する一環として、バッキングターゲットのリンク要件によって参照される。

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

PLUGIN_TARGET は、QMLモジュールに関連するプラグインターゲットを指定します。 はバッキングターゲット と同じにすることができます。 が指定されない場合、デフォルトは に が付加されたものになります。例えば、 というバッキングターゲットは、 というデフォルトのプラグイン名を持ちます。プラグインターゲットの名前は、生成されるPLUGIN_TARGET target PLUGIN_TARGET target plugin mymodule mymodulepluginqmldirファイルの 行に入力するために使用されます。したがって、 のようなターゲットプロパティやそれに関連するプロパティを設定して、プラグインの出力名を変更しようとしてはいけません。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++ファイルをプラグインターゲットに追加する必要があります。プラグインには単にバッキングライブラリを読み込むだけではない機能が含まれている可能性が高いので、NO_PLUGIN_OPTIONALも追加しておくとよいでしょう。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 キーワードも必要になります。

自動型登録

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

OUTPUT_DIRECTORY は、プラグイン・ライブラリ、 、typeinfo ファイルの生成場所を指定します。このキーワードが指定されない場合、デフォルト値はqmldir QT_QML_OUTPUT_DIRECTORY変数の値にターゲットパス（ ）を追加したものになります。QT_QML_OUTPUT_DIRECTORY変数が定義されていない場合、デフォルト値はバッキングターゲットの種類に依存します。実行可能ファイルの場合、この値は に追加されたターゲットパスとなりますが、その他のターゲットの場合は となります。ソースツリーの構造とQMLモジュールのターゲットパスの構造が一致する場合（これは非常に推奨されます）、URI ${CMAKE_CURRENT_BINARY_DIR} ${CMAKE_CURRENT_BINARY_DIR}QT_QML_OUTPUT_DIRECTORYは多くの場合必要ありません。ターゲットパスの構造と一致させるためには、モジュールURIのセグメントとまったく同じようにディレクトリを呼び出す必要があります。例えば、モジュールURIが の場合、これを というディレクトリに置く必要があります。MyUpperCaseThing.mylowercasething MyUpperCaseThing/mylowercasething/

OUTPUT_DIRECTORY キーワードを指定する必要はほとんどないと思われますが、もし指定した場合、linting、qmlソースのキャッシュコンパイル、静的ビルドにおけるプラグインの自動インポート、静的ビルド以外でのインポートされたQMLモジュールのデプロイがすべて正しく動作するように、呼び出し元はIMPORT_PATHにも追加する必要があると思われます。

Qt Quick Designer との互換性

DESIGNER_SUPPORTED は QML モジュールが Qt Quick Designer をサポートしている場合に指定します。互換性がある場合、生成される ファイルには 行が含まれます。これが Qt Quick Designer のプラグイン処理にどのように影響するかについてはqmldir designersupported Module Definition qmldir Filesを参照してください。

モジュールバージョンの同期

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

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

NAMESPACE キーワードで名前空間を指定すると、プラグインと登録コードはこの名前の C++ 名前空間に生成されます。

qmlimportscanner および NO_IMPORT_SCAN

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

qmltc の引数

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

TYPE_COMPILER_NAMESPACE 引数を使用すると、qmltc がコードを生成する名前空間をオーバーライドできます。デフォルトでは、生成されるコードの名前空間は URI で示されるモジュール階層に従います。例えば、URI のモジュールには を、URI のモジュールには を指定します。 オプションを指定すると、生成されたコードをカスタム名前空間に置くことができます。異なるサブ名前空間は "::" で区切られます。MyNamespace::MySubnamespace」のように、「::」で区切ります。MyModule MyModule com.example.MyModule com::example::Module TYPE_COMPILER_NAMESPACE

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