qt_add_qml_plugin

QMLモジュールに関連付けられたプラグインを定義します。

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

find_package(Qt6 REQUIRED COMPONENTS Qml)

概要

qt_add_qml_plugin(
    target
    [BACKING_TARGET backing_target]
    [STATIC | SHARED]
    [OUTPUT_DIRECTORY]
    [URI]
    [CLASS_NAME]
    [NO_GENERATE_PLUGIN_SOURCE]
    [NAMESPACE namespace]
)

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

説明

このコマンドは、QMLモジュールに関連付けられたプラグインターゲットを作成します。通常、qt_add_qml_module()によって内部的に呼び出され、そのバックイングターゲットに関連付けられたプラグインを作成または更新します。特別な方法でターゲットを作成する必要がある特別な事情がない限り、この関数を直接呼び出してはなりません。

qt_add_qml_module()のドキュメントには、QML モジュールに関連付けられた CMake ターゲットをどのように構成できるかについて、さまざまな構造パターンが説明されています。 なお、QMLモジュールに個別のバッキングターゲットがなく、すべての機能がプラグイン内で直接実装されている場合（推奨されない構成）であっても、qt_add_qml_plugin()ではなくqt_add_qml_module()を呼び出す必要があります。

引数

target は、QML プラグインに使用するターゲットの名前を指定します。そのターゲットがまだ存在しない場合は、作成されます。

BACKING_TARGET は、プラグインに関連付けられるバッキングターゲットの名前を指定します。 バッキングターゲットは、プラグインのtarget と同じにすることができます。その場合、マージされたターゲットは 1 つだけになりますが、通常はこの方法は推奨されません（詳細についてはqt_add_qml_module()を参照してください）。プラグインターゲットをバッキングターゲットよりも先に作成する必要がある特別な事情がない限り、BACKING_TARGET は常に指定する必要があります。BACKING_TARGET が指定されていない場合は、URI オプションを指定する必要があります。

デフォルトでは、プラグインはバッキングターゲットと互換性のあるタイプで作成されます。バッキングターゲットが静的ライブラリの場合、プラグインも静的ライブラリとして作成されます。バッキングターゲットが共有ライブラリの場合、プラグインはモジュールライブラリとして作成されます。 バッキングターゲットが指定されていない場合、またはプラグインに個別のバッキングターゲットがない場合は、STATIC またはSHARED キーワードのいずれかでプラグインのタイプを指定できます。プラグインのタイプが前述の条件のいずれによっても決定されない場合、Qtが静的ライブラリとしてビルドされている場合は静的プラグインが作成され、それ以外の場合はモジュールライブラリプラグインが作成されます。

OUTPUT_DIRECTORY プラグインライブラリが作成されるディレクトリを指定します。これは常に、QMLモジュールのqmldirファイルと同じ場所である必要があります。OUTPUT_DIRECTORY が指定されていない場合、利用可能な場合はBACKING_TARGET に保存されている情報から取得されます。 なお、これはバッキングターゲット自身のライブラリのディレクトリとは異なる場合があることに注意してください。バッキングターゲットから出力ディレクトリを取得できない場合、デフォルトではCMAKE_CURRENT_BINARY_DIR が使用されます。

URI このプラグインが関連付けられている QML モジュールのモジュール識別子を宣言します。 モジュール識別子は、QML モジュールの（ドット区切りの URI 表記による）識別子です。URI が指定されていない場合は、BACKING_TARGET を指定する必要があり、バッキングターゲットの URI がそこに記録されている必要があります（通常は、以前のqt_add_qml_module() の呼び出しによって記録されます）。

各プラグインには、QMLエンジンにモジュールを登録するC++クラスが1つずつ存在する必要があります。デフォルトでは、qt_add_qml_plugin() がこのC++クラスのソースコードを自動生成し、target のソースリストに追加します。生成されたプラグインクラスは、プラグインがオプションであるという要件を満たしています（「モジュール定義のqmldirファイル」を参照）。 クラス名は次のように決定されます：

• CLASS_NAME が指定されている場合は、その名前が使用されます。この名前は、QMLモジュールのqmldir ファイルで使用されている名前と一致している必要があります。
• CLASS_NAME が指定されていないが、BACKING_TARGET が指定されている場合、C++のクラス名は、そのバッキングターゲットに記録されている詳細情報から取得されます。これらの詳細情報は通常、以前のqt_add_qml_module()の呼び出しによって記録されており、生成されたqmldir ファイルで使用されている名前と一致します。これは、ほとんどのシナリオにおいてクラス名を指定するための推奨される方法です。
• それでもクラス名を特定できない場合は、モジュールの URI からドットをアンダースコアに置き換え、末尾にPlugin を付加したものがクラス名として設定されます。

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

プラグインによっては、プラグインクラスを手動で記述する必要がある場合があります。たとえば、プラグインが追加の初期化を実行したり、デフォルトのプラグインクラスでは実装されていないものを登録したりする必要がある場合などです。そのような場合は、NO_GENERATE_PLUGIN_SOURCE オプションを指定することができます。 その場合、独自のC++プラグインクラスを記述し、それをtarget に追加する必要があります。なお、独自のプラグインクラスを記述する必要がある場合、そのプラグインがオプションとなる可能性は極めて低いことに注意してください。 これはつまり、QMLモジュールを定義する際、qt_add_qml_module()の呼び出しにNO_PLUGIN_OPTIONAL キーワードを含める必要があることを意味します。そうしないと、生成されるqmldir ファイルが不正なものになってしまいます。プラグインクラスが、前述のロジックに基づいて決定されたものと同じクラス名を使用していることを確認してください。