QML モジュールを CMake に移植する

Qt 6 では QML モジュールがより強力に、より使いやすくなりました。以下のセクションでは、QML モジュールをqt_add_qml_moduleCMake API に移植する方法を説明します。

すでにqt_add_qml_module を使っている QML モジュールを最新化する方法についてはModern QML modulesも参照してください。

修正すべき問題の特定

qmllint を使ってこのプロセスをサポートします。

qt_add_qml_moduleで定義された各 QML モジュールには_qmllint という CMake ターゲットがあり、潜在的な問題や改善点を特定することができます。例えば、MyQmlLibrary という QML モジュールの場合、MyQmlLibrary_qmllint を使用します。すべてのQMLモジュールに対してqmllintを実行するには、all_qmllint を使います。

QMLモジュールの問題を示唆するqmllintの警告カテゴリーは以下の通りです：

• [インポート］
• [未使用インポート］
• [未解決タイプ］
• [未解決のエイリアス］
• [enum-entryの欠落] [missing-property
• [見つからないプロパティ］
• [型が見つからない］

qt_add_qml_module 用のプロジェクトを準備する

qt_add_qml_module を CMake で使えるようにする

qt_add_qml_module をCMake で使えるようにするには、Core とQml をプロジェクトのトップレベルCMakeLists.txt ファイルのfind_package の呼び出しに追加します：

find_package(Qt6 REQUIRED COMPONENTS Core Qml)

qt_standard_project_setup を使ってください。

qt_standard_project_setup は qt_add_qml_module に必要なQt CMake ポリシーを設定します。

qt_add_qml_module を呼び出す前に、プロジェクトのトップレベルCMakeLists.txt ファイルでqt_standard_project_setup を呼び出してください：

qt_standard_project_setup(REQUIRES 6.8)

qt_add_qml_module を使う

qt_add_qml_moduleは QML モジュールを生成する CMake 関数です。自動的にqmldir とqmltypes ファイルを生成し、qmlcachegenやqmllint のようなツールをセットアップします。

QMLモジュールは、CMakeの実行ファイルとライブラリターゲットの両方に追加することができます。実行ファイルターゲットに追加された QML モジュールは、他の実行ファイルから使用されたり、リンクされたりすることはありませんが、ライブラリターゲットに追加された QML モジュールは、他の実行ファイルから使用されたり、リンクされたりすることができます。

実行可能ターゲットに QML モジュールを追加する

この場合、QMLモジュールのソースファイルは別のライブラリとしてコンパイルされる のではなく、実行ファイルの一部として扱われます。つまり、このモジュールのためのモジュールもプラグインライブラリも作成されず、モジュールは実行ファイルに完全に統合されます。その結果、モジュールは特定のプログラムと結び付き、他の実行ファイルやライブラリで再利用することはできません。

QMLモジュールを実行ファイルに追加するには、CMakeLists.txt ：

# pre-existing:
qt_add_executable(MyApp main.cpp)

# add this
qt_add_qml_module(MyApp
    URI MyAppModule
    QML_FILES
        Main.qml # and possibly more .qml files
)

QQmlApplicationEngine::loadFromModule やQQmlComponent::loadFromModule のようなloadFromModule のメソッドでインスタンス化できるように、Main.qml は大文字で始める必要があります。また、ビルドフォルダ内での名前の衝突を避けるため、 QML モジュールの URI はターゲット名とは異なるものにする必要があります。

QMLモジュールをライブラリターゲットに追加する

QMLモジュールをライブラリに追加するには、CMakeLists.txt ：

qt_add_qml_module(MyQmlLibrary
    URI MyQmlModule
    QML_FILES MyQmlComponent1.qml MyQmlComponent2.qml...
    SOURCES MyCppComponent1.h MyCppComponent1.cpp MyCppComponent2.h MyCppComponent2.cpp...
    RESOURCES MyResource1.png MyResource2.png...
)

qt_add_qml_module は、この例のようにMyQmlLibrary ターゲットがまだ存在しない場合、qt_add_libraryを使ってSHARED ライブラリを作成します。

loadFromModuleを使ってQMLファイルをロードする

QMLファイルを読み込むには、loadFromModule ：

engine.load(QUrl(QStringLiteral("qrc:/MyQmlModule/Main.qml")));
// becomes
engine.loadFromModule("MyQmlModule", "Main");

手書きのqmldirファイルを削除する

qt_add_qml_module は自動的にqmldir ファイルを生成します。qmldir にシングルトンがある場合は、qt_add_qml_module の呼び出しの前にCMakeLists.txt で宣言してください：

set_source_files_properties(MySingleton.qml PROPERTIES QT_QML_SINGLETON_TYPE TRUE)

その後、手書きのqmldir を削除してください。

qmlplugindump によって生成された qmltypes ファイルを削除する

qt_add_qml_moduleは、すべての型が宣言的な型登録を使っている場合にqmltypes ファイルを自動生成します。これにより、qmlplugindump のようなツールを使ってqmltypes ファイルを手作業で生成する必要がなくなります。

これを実現するには、qmlRegisterType とその亜種の手動呼び出しを削除します。そして、QML_ELEMENT などを使用して、宣言的に型を登録します：

// add this header
#include <QtQml/qqmlregistrations.h>

class MyComponent: public QObject {
    Q_OBJECT

    // add this line to register MyComponent as 'MyComponent' in QML.
    QML_ELEMENT
    ....
};

外部型の登録のような複雑な登録の扱い方については、C++の型をQMLの型システムで登録するを参照してください。

その後、手書きのqmltypes ファイルを削除してください。

手書きの型登録プラグインを削除する

qt_add_qml_moduleは QMLモジュールプラグインを自動生成してくれます。プラグインのタスクが型登録だけであれば、手書きのプラグインは必要ありません。宣言的な型登録に切り替えたことで、プラグインからすべてのコードが削除されたのであれば、プラグインを完全に削除してください。

プラグインの自動生成を可能にするために、qt_add_qml_moduleから NO_PLUGIN,NO_PLUGIN_OPTIONAL,NO_CREATE_PLUGIN_TARGET,NO_GENERATE_PLUGIN_SOURCE の引数を削除していることを確認してください。

qrc ファイルの削除

qt_add_qml_module は自動的にqrc ファイルを生成します。イメージやサウンドファイルのようなqrc ファイルのリソースをリストするには、qt_add_qml_module のRESOURCES 引数に追加します。モジュールのリソースは:/qt/qml/MyQmlLibraryModule/ の下にあります。

ディレクトリのインポートをQMLモジュールのインポートに置き換える

ディレクトリのインポートをQMLモジュールのインポートに置き換えます。例えば、以下のようになります、

import "content" // contains SomeType.qml
// becomes
import MyQmlModule // contains SomeType.qml

SomeType {
    ...
}

QMLモジュールの中にあるファイルは自動的にQMLモジュールをインポートします。この自己インポートは削除することができます。