CMake - qt add qml moduleコマンドのソースを表示

== 概要 ==

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

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

== qt_add_qml_moduleコマンド ==
qt_add_qml_moduleコマンドは、C++ソース、.qmlファイル、またはその両方からなるQMLモジュールを定義する。<br>
モジュールの詳細が提供され、それらが一貫していることを保証する。<br>
<br>
また、.qmlソースのキャッシュコンパイル、リソースの埋め込み、リンティングチェック、いくつかの重要なモジュールファイルの自動生成等の設定や調整も行う。<br>
<br>
バージョンレスコマンドが無効の場合は、代わりに<code>qt6_add_qml_module</code>コマンドを使用する必要がある。<br>
 <syntaxhighlight lang="cmake">
 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]
 )
 </syntaxhighlight>
<br>
QMLモジュールを定義した例については、[https://doc.qt.io/qt-6/cmake-build-qml-application.html Building a QML application]や[https://doc.qt.io/qt-6/cmake-build-reusable-qml-module.html Building a reusable QML module]を参照すること。<br>
QMLモジュールに関する情報がQML言語サーバに公開されるようにプロジェクトを設定する方法については、[https://doc.qt.io/qt-6/cmake-variable-qt-qml-generate-qmlls-ini.html QT_QML_GENERATE_QMLLS_INI]を参照すること。<br>
<br><br>

== qt_add_qml_moduleコマンドの引数 ==
==== TARGET (必須) ====
モジュールのターゲット名を指定する。<br>
これはCMakeのターゲット名 (プロジェクト名) を指定することにより、他のターゲットからリンクすることができる。<br>
<br>
ターゲット名は、以下に示すような用途で使用される。<br>
* CMakeのビルドシステム内において、このQMLモジュールを識別するためのユニークな名前として機能する。
* 生成されるC++クラスやファイル名のベースとなる。
* 他のCMakeコマンド (例: <code>target_link_libraries</code>コマンド等) において、このモジュールを参照する際に使用される。
<br>
 <syntaxhighlight lang="cmake">
 qt_add_qml_module(<CMakeのターゲット名 (プロジェクト名)>
    # ...略
 )
 </syntaxhighlight>
<br>
<u>※注意</u><br>
<u>TARGETとURIに同じ名前を使用することは非推奨である。</u><br>
<u>これには、いくつかの理由がある。</u><br>
* 名前の衝突
*: 第1引数はCMakeのターゲット名として使用、URIはQMLモジュールの識別子として使用される。
*: 同じ名前を使用する場合、ビルドシステムや実行時に予期しない動作や衝突を引き起こす可能性がある。
* 可読性と保守性
*: 異なる名前を使用することにより、コードの可読性が向上して、他の開発者がプロジェクトを理解しやすくなる。
* 将来の拡張性
*: プロジェクト規模が大きくなるにつれて、CMakeのターゲット名とQMLモジュールを別々に参照する必要が出てくる可能性がある。
*: 最初から異なる名前を使用しておくことにより、後々の変更が容易になる。
* Qtの推奨プラクティス
*: Qtの公式ドキュメントでは、通常、これらの識別子に異なる名前を使用することが示されている。
<br>
==== URI (必須) ====
URI (Uniform Resource Identifier) は、QMLモジュールのインポート識別子を指定する。<br>
QMLファイルでは、このURIを使用してモジュールをインポートする。<br>
<br>
URIは、以下に示すような目的で使用される。<br>
* QMLファイル内において、このモジュールをインポートする際の識別子となる。
* モジュールの名前空間を定義して、他のモジュールとの衝突を防ぐ。
* ファイルシステム上でのモジュールの配置位置を決定する際のベースとなる。
<br>
 <syntaxhighlight lang="cmake">
 qt_add_qml_module(<ターゲット名>
    URI MyCompany.MyProduct
    VERSION 1.0
    # ...略
 )
 </syntaxhighlight>
<br>
この場合、QMLファイル内で以下のようにモジュールをインポートすることができる。<br>
 <syntaxhighlight lang="qml">
 import MyCompany.MyProduct 1.0
 </syntaxhighlight>
<br>
URIは、通常、逆ドメイン表記法 (例: com.mycompany.myproduct) やプロジェクト構造を反映した階層的な名前 （例: MyCompany.MyProduct) を使用する。<br>
これらの引数は異なる目的で使用されるため、通常は異なる名前を付けることが推奨される。<br>
<br>
URIはQMLのコンテキストで使用されるため、適切な名前を付けることにより、プロジェクトの構造が明確になり、保守性が向上する。<br>
<br>
==== VERSION ====
モジュールのバージョンを指定する。<br>
バージョンを指定しない場合、プロジェクトのバージョンが使用される。<br>
<br>
以下の例では、引数<code>VERSION</code>に2.0を指定することにより、QMLファイルにおいて、以下に示すようにQMLモジュールをインポートすることができる。<br>
 <syntaxhighlight lang="cmake">
 qt_add_qml_module(<ターゲット名>
    URI MyCompany.MyProduct
    VERSION 2.0
    # ...略
 )
 </syntaxhighlight>
<br>
 <syntaxhighlight lang="qml">
 // QMLファイル
 
 import MyCompany.MyProduct 2.0
 </syntaxhighlight>
<br>

==== QML_FILES ====
モジュールに含めるQMLファイルのリストを指定する。<br>
指定したファイル群は、自動的にリソースにコンパイルされる。<br>
<br>
==== SOURCES ====
C++ソースファイルのリストを指定する。<br>
指定したソースファイル群は、モジュールのコンパイルに使用される。<br>
<br>
==== HEADERS ====
ヘッダファイルのリストを指定する。<br>
これは、public APIとして扱われるヘッダファイル群を指定する。<br>
<br>
==== RESOURCE_PREFIX ====
リソースのプレフィックスを指定する。<br>
RESOURCE_PREFIXは、この仮想ファイルシステム内でのパスの始まりを定義する。<br>
<br>
Qtのリソースシステムは、アプリケーションにバイナリデータ (画像、QMLファイル、その他のアセット) を埋め込む方法を提供するものである。<br>
これらのリソースは、仮想的なファイルシステム内にあるかのように扱われる。<br>
<br>
これは、QMLファイルがリソースシステムでアクセスされる時のパスを決定するものである。<br>
<br>
Qt 6では、デフォルト値は"/qt/qml/"である。<br>
これは、警告QTP0001ポリシーに関連している。<br>
<br>
 例: RESOURCE_PREFIXの値が<u>/qt/qml</u>の場合
 
 この場合、QMLモジュールのリソースが仮想的なパス/qt/qmlディレクトリの下に配置されることを意味する。
 <u>実際のファイルシステム上にこのディレクトリが存在するわけではなく、これは仮想的なパスである。</u>
 
 例えば、QMLモジュールにMyComponent.qmlファイルが存在する場合、このファイルは以下に示すようにアクセスできる。
 qrc:/qt/qml/<URIの値>/MyComponent.qml
<br>
<u>※注意</u><br>
<u>RESOURCE_PREFIXを変更する場合、QMLファイル内でリソースを参照する方法も適切に調整する必要がある。</u><br>
<br>

==== OUTPUT_DIRECTORY ====
生成されたファイルの出力ディレクトリを指定する。<br>
未指定の場合は、<code>${CMAKE_CURRENT_BINARY_DIR}</code>が使用される。<br>
<br>
==== IMPORT_PATH ====
インポートパスを追加する。<br>
これは、QMLエンジンがモジュールを検索する場所である。<br>
<br>
==== DEPENDENCIES ====
このモジュールが依存する他のQMLモジュールを指定する。<br>
<br>
==== DESIGNER_SUPPORTED ====
Qt Creatorのデザイナにおいて、このモジュールをサポートするかどうかを指定する。<br>
<br>
==== CLASSNAME ====
モジュールのC++クラス名を指定する。<br>
未指定の場合は、自動生成される。<br>
<br>
==== PLUGIN_TARGET ====
別のターゲットをプラグインとして使用する場合に指定する。<br>
<br>
==== ENABLE_TYPE_COMPILER ====
QMLコンパイラを有効にするかどうかを指定する。<br>
デフォルトは有効である。<br>
<br><br>

== 複数のqt_add_qml_moduleコマンド ==
異なるURIを持つ<code>qt_add_qml_module</code>コマンドを複数記述することは、一般的に推奨される方法である。<br>
<br>
以下に示すような状況において、複数の<code>qt_add_qml_module</code>コマンドを使用することを推奨する。<br>
* 異なるQMLモジュールの定義
*: プロジェクト内で複数の独立したQMLモジュールを作成する場合
* 異なる機能や目的を持つモジュール
*: アプリケーションの異なる部分や機能のために別々のモジュールを定義する場合
* バージョン管理
*: 同じモジュールの異なるバージョンを別々に定義する場合
<br>
<u>ただし、同じターゲット名を指定することは出来ないことに注意する。</u><br>
<br>
<u>Qt 6の場合、<code>qt6_add_qml_module</code>コマンドを使用することも可能である。</u><br>
<br>
 <syntaxhighlight lang="cmake">
 qt_add_qml_module(<任意の名前 1>
    URI Com.MyCompany.Module1
    VERSION 1.0
    QML_FILES
       Module1Component1.qml
       Module1Component2.qml
 )
 
 qt_add_qml_module(<任意の名前 2>
    URI Com.MyCompany.Module2
    VERSION 1.0
    QML_FILES
       Module2Component1.qml
       Module2Component2.qml
 )
 </syntaxhighlight>
<br>
この方法には、以下に示すようないくつかのメリットがある。<br>
* モジュールの明確な分離
* コードの整理と管理が容易になる。
* 各モジュールを個別に開発、テスト、更新できる。
<br>
ただし、モジュール間の依存関係や名前空間の衝突に注意する必要がある。<br>
適切に設計されている場合は、複数の<code>qt_add_qml_module</code>コマンドを使用することにより、より構造化されて、メンテナンスが容易なプロジェクトを設計することができる。<br>
<br><br>


{{#seo:
|title={{PAGENAME}} : Exploring Electronics and SUSE Linux | MochiuWiki
|keywords=MochiuWiki,Mochiu,Wiki,Mochiu Wiki,Electric Circuit,Electric,pcb,Mathematics,AVR,TI,STMicro,AVR,ATmega,MSP430,STM,Arduino,Xilinx,FPGA,Verilog,HDL,PinePhone,Pine Phone,Raspberry,Raspberry Pi,C,C++,C#,Qt,Qml,MFC,Shell,Bash,Zsh,Fish,SUSE,SLE,Suse Enterprise,Suse Linux,openSUSE,open SUSE,Leap,Linux,uCLnux,Podman,電気回路,電子回路,基板,プリント基板
|description={{PAGENAME}} - 電子回路とSUSE Linuxに関する情報 | This page is {{PAGENAME}} in our wiki about electronic circuits and SUSE Linux
|image=/resources/assets/MochiuLogo_Single_Blue.png
}}

__FORCETOC__
[[カテゴリ:Qt]]