Qt 5 および Qt 6 の互換性

Qt 5 および Qt 6 における CMake API のセマンティクスは概ね互換性がありますが、これらのコマンドの動作には若干の違いがあり、後者のバージョンにのみ追加されたインターフェースも存在します。このガイドは、主に、あるメジャーリリースから別のメジャーリリースへの段階的な移行を検討しているプロジェクトを対象としています。

Qt 5.14 までは、インポートされたすべての Qt ライブラリターゲットおよびコマンドの名前にはバージョン番号が含まれていました（例：qt5_add_library ）。このため、Qt 5 と Qt 6 の両方で動作する CMake コードを書くのは少々面倒でした。 そこでQt 5.15では、バージョン番号を含まないターゲットやコマンド（例：qt_add_library ）が導入され、異なるQtバージョンにほとんど依存しないCMakeコードの記述が可能になりました。

バージョン非依存のターゲット

既存のインポート済みターゲットに加え、Qt 5.15 ではバージョンレスターゲットが導入されました。つまり、 Qt CoreQt6::Core またはQt::Core のどちらを参照しても構いません：

find_package(Qt6 COMPONENTS Core)
if (NOT Qt6_FOUND)
    find_package(Qt5 5.15 REQUIRED COMPONENTS Core)
endif()

add_executable(helloworld
    ...
)

target_link_libraries(helloworld PRIVATE Qt::Core)

上記のスニペットは、まずQt 6のインストール環境を探します。それが失敗した場合は、Qt 5.15のパッケージを探します。Qt 6とQt 5のどちらが使用されるかに関係なく、インポートされたQt::Core ターゲットを使用できます。Qt 6のチェックをスキップするには、 CMAKE_DISABLE_FIND_PACKAGE_Qt6find_package の呼び出しの前に設定してください。

バージョンレスなターゲットはデフォルトで定義されています。これらを無効にするには、最初のfind_package() 呼び出しの前にQT_NO_CREATE_VERSIONLESS_TARGETSを設定してください。

バージョンレスコマンド

Qt 5.15 以降、Qt モジュールはコマンドのバージョンレス版も提供しています。例えば、Qt 5 を使用しているか Qt 6 を使用しているかに関係なく、qt_add_translation()を使用して翻訳ファイルをコンパイルできるようになりました。

バージョンレスなコマンドの作成を防ぐには、最初の `find_package() ` の呼び出しの前に `QT_NO_CREATE_VERSIONLESS_FUNCTIONS` を設定してください。

Qt 5 と Qt 6 の混在

1つのCMakeコンテキスト内でQt 5とQt 6の両方を読み込む必要があるプロジェクトがあるかもしれません（ただし、1つのライブラリや実行ファイル内でQtのバージョンを混在させることはサポートされていないため、その点には注意が必要です）。

このような設定では、バージョン指定のないターゲットおよびコマンドは、find_package によって最初に検出されたQtバージョンを暗黙的に参照することになります。バージョンを明示的に指定するには、最初のfind_package 呼び出しの前に、CMake変数QT_DEFAULT_MAJOR_VERSIONを設定してください。

Qt 5.15より古いQt 5バージョンのサポート

Qt 5.15 より古い Qt 5 バージョンもサポートする必要がある場合は、現在のバージョンを CMake 変数（QT_VERSION_MAJOR ）に格納することで対応できます：

find_package(Qt6 COMPONENTS Core)
if(Qt6_FOUND)
    set(QT_VERSION_MAJOR 6)
else()
    find_package(Qt5 REQUIRED COMPONENTS Core)
    set(QT_VERSION_MAJOR 5)
endif()

add_executable(helloworld
    ...
)

target_link_libraries(helloworld PRIVATE Qt${QT_VERSION_MAJOR}::Core)

バージョンを指定しないアプローチと比較して、ターゲットはQt${QT_VERSION_MAJOR}::Core を指し、これはtarget_link_libraries の呼び出し中にQt5::Core またはQt6::Core のいずれかに解決されます。

推奨される手法

可能な限り、CMake コマンドのバージョンなしのバリエーションを使用してください。

同じプロジェクトで Qt 5 と Qt 6 を両方サポートする必要がない限り、バージョン指定のあるターゲットを使用してください。

バージョン指定のないターゲットを使用する必要がある場合は、「バージョン指定のないターゲットを使用する際の注意点」に留意してください。

Qt 5.15 より古いバージョンの Qt をサポートする必要がある場合、 、あるいは、CMake コードがQT_NO_CREATE_VERSIONLESS_FUNCTIONSまたはQT_NO_CREATE_VERSIONLESS_TARGETS が定義されている可能性のあるコンテキストで読み込まれるかどうかを制御できない場合は、バージョン指定のある CMake コマンドおよびターゲットを使用してください。 この場合でも、変数を通じて実際のコマンド名やターゲット名を特定することで、コードを簡素化することは可能です。

バージョンレス・ターゲット使用時の注意点

バージョンレスターゲットの使用には、いくつかの欠点があります。

バージョンレスターゲットは通常、ALIAS ターゲットであり、ALIAS ターゲットを指すALIAS ターゲットを作成することはできません。その代わりに、 ALIASED_TARGET ターゲットプロパティを使用してください。

古いバージョンの Qt 6 では、インポートされた `Qt::Core ` ターゲットには、`Qt6::Core` で公開されているすべてのターゲットプロパティが含まれていませんでした。これは、CMake 3.18 以降を使用し、Qt 6.8 以降に対してリンクを行うことで修正されます。

プロジェクトは、バージョン指定のないターゲットを公開するターゲットをエクスポートしてはなりません。たとえば、別のプロジェクトで使用されるライブラリは、バージョン指定のないターゲットに対してパブリックにリンクするターゲットをエクスポートしてはなりません。そうしないと、推移的な依存関係が破綻したり、そのライブラリのユーザーが意図せずに Qt5 と Qt6 のターゲットを混在させてしまう可能性があります。

Windows における Unicode サポート

Qt 6 では、Qt モジュールに対してリンクするターゲットに対して、デフォルトで `UNICODE ` および `_UNICODE ` コンパイラ定義が設定されます。これは qmake の動作と一致していますが、Qt 5 の CMake API の動作とは異なります。

定義を設定しないようにするには、ターゲットに対してqt_disable_unicode_defines() を呼び出してください。

find_package(Qt6 COMPONENTS Core)

add_executable(helloworld
    ...
)

qt_disable_unicode_defines(helloworld)