CMake による統合

QMLモジュールを定義するには、CMakeコマンド `qt_add_qml_module` を使用することが推奨されます。これにより、型の登録、リソースの埋め込み、プラグインの作成、およびツールとの統合が自動化されます。このページでは、qt_add_qml_module の背後にある概念を説明し、一般的な使用パターンを順を追って解説します。

すべてのオプションに関する完全なリファレンスについては、qt_add_qml_module を参照してください。

重要な概念

例を見る前に、qt_add_qml_module が実際に何を作成するのかを理解しておくと役立ちます：

• バッキングターゲット— モジュールの C++ コード、コンパイル済みの QML ファイル、およびリソースを含むライブラリ（または実行ファイル）。これはqt_add_qml_module の最初の引数であり、リンク対象となるターゲットです。既存のターゲット（qt_add_executable やqt_add_library で事前に作成されたもの）でもよいですし、qt_add_qml_module が自動的に作成することもできます。
• プラグインターゲット— QMLエンジンが実行時にモジュールを動的に読み込めるようにする小さなライブラリです。これは自動的に作成され、バッキングターゲットとは別個のものです。実行ファイルがバッキングターゲットに直接リンクする場合、プラグインは実行時に読み込まれません。NO_PLUGIN を使用することで、プラグインを完全に省略することができます。
• qmldir ファイル— モジュールが提供する型とその場所を QML エンジンに伝えるモジュールメタデータファイルです。これは自動的に生成されます。
• typeinfoファイル（.qmltypes ） — QMLツール（qmlcachegen、qmllint、qmlls、Qt Creator ）で使用される、機械可読な型情報です。これも自動的に生成されます。

ディレクトリ構造

ソースディレクトリ構造は、モジュールの URI を反映する必要があります。URI は、ドットをスラッシュに置き換えることでパスに変換されます。たとえば、URI がMyCompany.Controls であるモジュールは、以下の場所に配置する必要があります:

src/MyCompany/Controls/CMakeLists.txt
src/MyCompany/Controls/Button.qml
src/MyCompany/Controls/mywidget.cpp
src/MyCompany/Controls/mywidget.h

この規約により、QMLエンジンやツールは追加の設定なしにモジュールを検出できるようになります。 ディレクトリ構造がURIと一致しない場合は、ビルド出力がURIと一致するパスに配置されるようにOUTPUT_DIRECTORYを設定し、QMLエンジンやツールがモジュールを特定できるようにIMPORT_PATHを設定する必要があります。

一般的なパターン

QMLのみのアプリケーション

最も単純なケース：QML ファイルのみで構成され、C++ 型を含まない実行ファイルです。

cmake_minimum_required(VERSION 3.16)
project(myapp LANGUAGES CXX)

find_package(Qt6 REQUIRED COMPONENTS Quick)
qt_standard_project_setup(REQUIRES 6.8)

qt_add_executable(myapp)
qt_add_qml_module(myapp
    URI MyApp
    QML_FILES
        Main.qml
        Button.qml
    RESOURCES
        images/logo.png
)

target_link_libraries(myapp PRIVATE Qt6::Quick)

バックイングターゲットは実行ファイルであるため、プラグインは作成されません。QML ファイルはコンパイルされ、リソースとして埋め込まれます。RESOURCES キーワードを使用すると、QML ファイル以外のファイル（画像、フォントなど）を同じリソース階層に追加できます。

C++ 型を含むアプリケーション

C++型をQMLから利用可能なアプリケーション：

qt_add_executable(myapp)
qt_add_qml_module(myapp
    URI MyApp
    QML_FILES
        Main.qml
    SOURCES
        backend.cpp backend.h
)

backend.h 内のC++型には、QML_ELEMENT （またはQML_NAMED_ELEMENT のような類似のマクロ）による注釈が必要であり、Q_OBJECT またはQ_GADGET マクロを使用する必要があります。型の登録はAUTOMOC を通じて自動的に行われます。利用可能な登録マクロの完全な概要については、「QML型システムへのC++型の登録」を参照してください。

再利用可能なライブラリモジュール

他のプロジェクトやモジュールがインポートできる、ライブラリとしてパッケージ化された QML モジュール：

# In src/MyCompany/Controls/CMakeLists.txt
qt_add_qml_module(mycontrols
    URI MyCompany.Controls
    QML_FILES
        Button.qml
        Slider.qml
    SOURCES
        theme.cpp theme.h
)

これにより、mycontrols （基盤となるライブラリ）とmycontrolsplugin （プラグイン）の2つのターゲットが生成されます。他のモジュールは、QML内でimport MyCompany.Controls を使用してこれをインポートします。mycontrols に直接リンクするアプリケーションでは、実行時にプラグインをロードする必要はありません。

ライブラリモジュールを使用するアプリケーション

上記の「再利用可能なライブラリモジュール」の例から、mycontrols モジュールを使用する場合：

# In the application's CMakeLists.txt
qt_add_executable(myapp)
qt_add_qml_module(myapp
    URI MyApp
    QML_FILES Main.qml
    DEPENDENCIES TARGET mycontrols
)

target_link_libraries(myapp PRIVATE mycontrols)

DEPENDENCIES行を指定することで、QML ツール（qmlcachegen、qmllint、qmlls）がMyCompany.Controls が提供する型を確実に検出できるようになります。

// In Main.qml
import MyCompany.Controls

Button { text: "Click me" }

シングルトンを含むモジュール

シングルトン型を提供するQMLファイルでは、qt_add_qml_module の呼び出しの前にソースファイルプロパティを設定する必要があります：

set_source_files_properties(Theme.qml PROPERTIES QT_QML_SINGLETON_TYPE TRUE)

qt_add_qml_module(mymodule
    URI MyModule
    QML_FILES
        Theme.qml
        Main.qml
)

また、QMLファイルにはpragma Singleton を含める必要があります。CMakeプロパティとQMLプラグマの両方が必須です。

カスタムプラグインを含むモジュール

カスタム初期化（例えば、画像プロバイダの登録など）を行う必要がある場合は、独自の `QQmlEngineExtensionPlugin ` サブクラスを提供できます。

# In CMakeLists.txt
qt_add_qml_module(mymodule
    URI MyModule
    NO_GENERATE_PLUGIN_SOURCE
    NO_PLUGIN_OPTIONAL
    CLASS_NAME MyModulePlugin
    QML_FILES
        Main.qml
    SOURCES
        myimageprovider.cpp myimageprovider.h
)

# Add the custom plugin source to the plugin target
target_sources(mymoduleplugin PRIVATE plugin.cpp)

// In plugin.cpp
#include <QtQml/QQmlEngineExtensionPlugin>
#include "myimageprovider.h"

class MyModulePlugin : public QQmlEngineExtensionPlugin
{
    Q_OBJECT
    Q_PLUGIN_METADATA(IID QQmlEngineExtensionInterface_iid)
public:
    void initializeEngine(QQmlEngine *engine, const char *uri) override
    {
        engine->addImageProvider("myprovider", new MyImageProvider);
    }
};

#include "plugin.moc"

NO_GENERATE_PLUGIN_SOURCE を指定すると、ビルドシステムはデフォルトのプラグインソースを生成しないように指示されます。CLASS_NAME は、実装内のクラス名と一致している必要があります。NO_PLUGIN_OPTIONAL を指定すると、プラグインが常に読み込まれるようになります。これは、このオプションを指定しないとスキップされてしまう初期化ロジックが含まれているためです。

QMLファイルの追加

最初の `qt_add_qml_module ` の呼び出し後に追加された QML ファイルについては、`qt_target_qml_sources` を使用します：

qt_target_qml_sources(my_qml_module
    QML_FILES
        DynamicallyAddedType.qml
)

これは、プラットフォームや設定に基づいてファイルを条件付きで含める場合に役立ちます。

CMakeの詳細リファレンス

すべての CMake コマンド、プロパティ、変数、およびポリシーに関する完全な詳細については、「QML 向けの CMake 統合」を参照してください。