CMake - qt add qml moduleコマンド

概要

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

QML型とQMLモジュールの登録

QMLで使用する型を登録するためには、CMakeのqt_add_qml_moduleコマンドを使用して、QMLモジュールを定義する必要がある。
次に、新しいモジュールにC++ヘッダを追加して、その中でQMLに公開する型を定義する。

qt_add_qml_moduleコマンド

qt_add_qml_moduleコマンドは、C++ソース、.qmlファイル、またはその両方からなるQMLモジュールを定義する。
モジュールの詳細が提供され、それらが一貫していることを保証する。

また、.qmlソースのキャッシュコンパイル、リソースの埋め込み、リンティングチェック、いくつかの重要なモジュールファイルの自動生成等の設定や調整も行う。

バージョンレスコマンドが無効の場合は、代わりにqt6_add_qml_moduleコマンドを使用する必要がある。

 qt_add_qml_module(
    <ターゲット名>
    URI <任意のURI>
    [VERSION <任意のバージョン>]
    [PAST_MAJOR_VERSIONS ...]
    [STATIC | SHARED]
    [PLUGIN_TARGET <プラグインターゲット名>]
    [OUTPUT_DIRECTORY <出力先ディレクトリ>]
    [RESOURCE_PREFIX <リソースプリフィックス>]
    [CLASS_NAME <クラス名>]
    [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]
 )

QMLモジュールを定義した例については、Building a QML applicationやBuilding a reusable QML moduleを参照すること。
QMLモジュールに関する情報がQML言語サーバに公開されるようにプロジェクトを設定する方法については、QT_QML_GENERATE_QMLLS_INIを参照すること。

qt_add_qml_moduleコマンドの引数

TARGET (必須)

モジュールのターゲット名を指定する。
これはCMakeのターゲット名 (プロジェクト名) を指定することにより、他のターゲットからリンクすることができる。

ターゲット名は、以下に示すような用途で使用される。

• CMakeのビルドシステム内において、このQMLモジュールを識別するためのユニークな名前として機能する。
• 生成されるC++クラスやファイル名のベースとなる。
• 他のCMakeコマンド (例: target_link_librariesコマンド等) において、このモジュールを参照する際に使用される。

 qt_add_qml_module(<CMakeのターゲット名 (プロジェクト名)>
    # ...略
 )

※注意
TARGETとURIに同じ名前を使用することは非推奨である。
これには、いくつかの理由がある。

• 名前の衝突

  第1引数はCMakeのターゲット名として使用、URIはQMLモジュールの識別子として使用される。

  同じ名前を使用する場合、ビルドシステムや実行時に予期しない動作や衝突を引き起こす可能性がある。

• 可読性と保守性

  異なる名前を使用することにより、コードの可読性が向上して、他の開発者がプロジェクトを理解しやすくなる。

• 将来の拡張性

  プロジェクト規模が大きくなるにつれて、CMakeのターゲット名とQMLモジュールを別々に参照する必要が出てくる可能性がある。

  最初から異なる名前を使用しておくことにより、後々の変更が容易になる。

• Qtの推奨プラクティス

  Qtの公式ドキュメントでは、通常、これらの識別子に異なる名前を使用することが示されている。

URI (必須)

URI (Uniform Resource Identifier) は、QMLモジュールのインポート識別子を指定する。
QMLファイルでは、このURIを使用してモジュールをインポートする。

URIは、以下に示すような目的で使用される。

• QMLファイル内において、このモジュールをインポートする際の識別子となる。
• モジュールの名前空間を定義して、他のモジュールとの衝突を防ぐ。
• ファイルシステム上でのモジュールの配置位置を決定する際のベースとなる。

 qt_add_qml_module(<ターゲット名>
    URI MyCompany.MyProduct
    VERSION 1.0
    # ...略
 )

この場合、QMLファイル内で以下のようにモジュールをインポートすることができる。

 import MyCompany.MyProduct 1.0

URIは、通常、逆ドメイン表記法 (例: com.mycompany.myproduct) やプロジェクト構造を反映した階層的な名前 （例: MyCompany.MyProduct) を使用する。
これらの引数は異なる目的で使用されるため、通常は異なる名前を付けることが推奨される。

URIはQMLのコンテキストで使用されるため、適切な名前を付けることにより、プロジェクトの構造が明確になり、保守性が向上する。

VERSION

モジュールのバージョンを指定する。
例: "1.0"

バージョンを指定しない場合、プロジェクトのバージョンが使用される。

QML_FILES

モジュールに含めるQMLファイルのリストを指定する。
指定したファイル群は、自動的にリソースにコンパイルされる。

SOURCES

C++ソースファイルのリストを指定する。
指定したソースファイル群は、モジュールのコンパイルに使用される。

HEADERS

ヘッダファイルのリストを指定する。
これは、public APIとして扱われるヘッダファイル群を指定する。

RESOURCE_PREFIX

リソースのプレフィックスを指定する。
デフォルト値は、"/qt/qml/"である。

これは、QMLファイルがリソースシステムでアクセスされる時のパスを決定するものである。

OUTPUT_DIRECTORY

生成されたファイルの出力ディレクトリを指定する。
未指定の場合は、${CMAKE_CURRENT_BINARY_DIR}が使用される。

IMPORT_PATH

インポートパスを追加する。
これは、QMLエンジンがモジュールを検索する場所である。

DEPENDENCIES

このモジュールが依存する他のQMLモジュールを指定する。

DESIGNER_SUPPORTED

Qt Creatorのデザイナにおいて、このモジュールをサポートするかどうかを指定する。

CLASSNAME

モジュールのC++クラス名を指定する。
未指定の場合は、自動生成される。

PLUGIN_TARGET

別のターゲットをプラグインとして使用する場合に指定する。

ENABLE_TYPE_COMPILER

QMLコンパイラを有効にするかどうかを指定する。
デフォルトは有効である。