CMake - Qt5 / Qt6の互換性のソースを表示

== 概要 ==
Qt 5およびQt 6のCMakeコマンドのセマンティクスは、ほぼ互換性がある。<br>
しかし、Qt 5.14以前では、インポートされたQtライブラリのターゲットとコマンドは、全て名前の一部としてバージョン番号を含んでいた。<br>
<br>
そのため、Qt 5とQt 6の両方で動作するCMakeコマンドを記述することは煩雑であった。<br>
<br>
Qt 5.15以降では、バージョンレスターゲットおよびバージョンレスとコマンドを導入しており、異なるQtのバージョンにほとんど依存しないCMakeコマンドが記述できるようになっている。<br>
<br><br>

== バージョンレスターゲット ==
既存のインポートターゲットに加えて、Qt 5.15以降ではバージョンレスターゲットが使用できる。<br>
例えば、Qt Coreライブラリとリンクする場合、Qt6::CoreとQt::Coreの両方を参照することができる。<br>
<br>
<u>バージョンレスターゲットはデフォルトで定義されている。</u><br>
もし、バージョンレスターゲットを無効にする場合は、最初の<code>find_package</code>コマンドの実行前に、<code>QT_NO_CREATE_VERSIONLESS_TARGETS</code>を設定する必要がある。<br>
<br>
* <code>QT_NO_CREATE_VERSIONLESS_TARGETS</code>
*: Qt::で始まるインポートされたターゲットを隠す。
*: 代わりに、Qt6::で始まるターゲットを使用する必要がある。
<br>
<u>※注意</u><br>
<u>例えば、インポートされたQt::Coreターゲットには、Qt6::Coreターゲットで利用可能なターゲットプロパティは無いことに注意する。</u><br>
<br>
以下の例では、まず、Qt 6ライブラリを検索する。<br>
Qt 6ライブラリの検索に失敗した場合は、Qt 5.15ライブラリを検索する。<br>
これにより、Qt 5 / Qt 6に関係なく、インポートされたQt::Coreターゲットを使用することができる。<br>
 <syntaxhighlight lang="cmake">
 # バージョンレスターゲットを有効にする場合
 # デフォルトで有効なため、設定は不要である
 find_package(Qt6 COMPONENTS Core)
 if (NOT Qt6_FOUND)
    find_package(Qt5 5.15 REQUIRED COMPONENTS Core)
 endif()
 
 add_executable(myApp
    # ...略
 )
 
 target_link_libraries(myApp PRIVATE
    Qt::Core
 )
 </syntaxhighlight>
<br>
 <syntaxhighlight lang="cmake">
 # バージョンレスターゲットを無効にする場合
 set(QT_NO_CREATE_VERSIONLESS_TARGETS OFF)
 find_package(Qt6 COMPONENTS Core)
 
 # ...略
 </syntaxhighlight>
<br><br>

== バージョンレスコマンド ==
Qt 5.15以降、Qtモジュールはバージョンレスのコマンドも提供している。<br>
例えば、Qt5とQt6のどちらを使用していても、<code>qt_add_translation</code>コマンドを使用して、翻訳ファイルをコンパイルすることができる。<br>
<br>
最初の<code>find_package</code>コマンドの実行の前に、<code>QT_NO_CREATE_VERSIONLESS_FUNCTIONS</code>を設定して、バージョンレスコマンドの作成を防ぐ。<br>
<br>
* <code>QT_NO_CREATE_VERSIONLESS_FUNCTIONS</code>
*: qt_で始まるコマンドを非表示にして、qt6_で始まるバージョン管理されたコマンドのみを残す。
<br>
このマクロを定義することで、Qtのバージョン付きのシンボルのみが使用されるようになる。<br>
これは、特にQtの異なるバージョンを混在させる場合や明示的にバージョン管理を行う場合に有用である。<br>
<br>
以下の例では、<code>find_package</code>コマンドの前に<code>set</code>コマンドで<code>QT_NO_CREATE_VERSIONLESS_FUNCTIONS</code>を<code>ON</code>または<code>TRUE</code>に設定している。<br>
これにより、Qtのバージョンなしのシンボルが生成されないようになる。<br>
CMake 3.16以降が必要な場合があるため、<code>cmake_minimum_required</code>コマンドを適切に設定する必要がある。<br>
 <syntaxhighlight lang="cmake">
 cmake_minimum_required(VERSION 3.16)
 
 # find_packageコマンドの前にQT_NO_CREATE_VERSIONLESS_FUNCTIONSを設定する
 set(QT_NO_CREATE_VERSIONLESS_FUNCTIONS ON)
 
 project(MyQtProject)
 
 # 使用するQtライブラリ
 find_package(Qt6 REQUIRED COMPONENTS Core Widgets)
 
 # 実行ファイルのソースファイルおよびヘッダファイル
 add_executable(MyApp main.cpp)
 
 # Qtライブラリのリンク
 target_link_libraries(MyApp Qt6::Core Qt6::Widgets)
 </syntaxhighlight>
<br><br>

== Qt 5とQt 6の混在 ==
Qt 5およびQt 6の両方を1つのCMakeファイルに記述する場合、バージョンレスターゲットおよびバージョンレスコマンドは、<code>find_package</code>コマンドで検索された最初のQtバージョンが暗黙的に参照される。<br>
ただし、1つのライブラリや実行ファイルにQtのバージョンを混在させることはサポートされていない。<br>
<br>
バージョンを明示的にするには、最初の<code>find_package</code>コマンドを実行する前に、CMake変数<code>QT_DEFAULT_MAJOR_VERSION</code>を設定する必要がある。<br>
<br>
* <code>QT_DEFAULT_MAJOR_VERSION</code>
*: Qt 5プロジェクトとQt 6プロジェクトが混在している場合、qt_コマンドで進むQtのバージョンを指定する。
*: <code>find_package</code>コマンドを実行する前に、Qt 5かQt 6のいずれかに設定する必要がある。
*: <br>
*: 5に設定する場合、qt_で始まるコマンドはqt5_で始まるコマンドを呼び出す。
*: 6に設定する場合、qt_で始まるコマンドはqt6_で始まるコマンドを呼び出す。
*: <br>
*: 設定されていない場合、最初の<code>find_package</code>コマンドを実行すると、デフォルトのバージョンが定義される。
<br><br>

== レガシーなQt 5のサポート ==
Qt 5.14以前のバージョンもサポートする必要がある場合は、CMake変数に現在のバージョンを格納することで対応することができる。<br>
<br>
以下の例では、find_package(QT NAMES Qt6 Qt5 REQUIRED COMPONENTS Core)では、まず、Qt 6を検索、見つからない場合はQt 5をQTという名前で検索している。<br>
いずれかの検索に成功した場合は、CMake変数<code>QT_VERSION_MAJOR</code>は5または6のいずれかに定義される。<br>
<br>
次に、Qt${QT_VERSION_MAJOR}という名前をオンザフライで作成することにより、決定されたQtバージョンのパッケージを再度読み込む。<br>
これは、CMAKE_AUTOMOCがパッケージ名がQt5あるいはQt6であることを期待しており、異なる場合はエラーを表示するためである。<br>
 <syntaxhighlight lang="cmake">
 find_package(QT NAMES Qt6 Qt5 REQUIRED COMPONENTS Core)
 find_package(Qt${QT_VERSION_MAJOR} REQUIRED COMPONENTS Core)
 
 add_executable(myApp
    # ...略
 )
 
 target_link_libraries(myApp PRIVATE
    Qt${QT_VERSION_MAJOR}::Core
 )
 </syntaxhighlight>
<br>
同様に、インポートするQtライブラリ名も指定することができる。<br>
<code>target_link_libraries</code>コマンドにQt${QT_VERSION_MAJOR}::Widgetsと記述することにより、Qt5::WidgetsまたはQt6::Widgetsのいずれかのライブラリをリンクすることができる。<br>
<br><br>

== 推奨事項 ==
* 可能であれば、CMakeコマンドのバージョンレスバリアントを使用する。
* 同じプロジェクトでQt 5およびQt 6をサポートする必要がある場合を除き、バージョン付きのターゲットを使用する。
* バージョンレスターゲットを使用しなければならない場合は、[[CMake_-_Qt5_/_Qt6の互換性#バージョンレスターゲットのデメリット|バージョンレスターゲットを使用する際のデメリット]]に注意する。
* Qt 5.15より古いバージョンのQt 5をサポートする必要がある場合や、<br><code>QT_NO_CREATE_VERSIONLESS_FUNCTIONS</code>や<code>QT_NO_CREATE_VERSIONLESS_TARGETS</code>が定義されているコンテキストでCMakeコードがロードされるかどうかを制御できない場合は、<br>バージョン管理されたバージョンのCMakeコマンドやターゲットを使用する。<br><br>この場合でも、変数を通して実際のコマンド名やターゲット名を決定することにより、コードを簡素化することができる。
<br><br>

== バージョンレスターゲットのデメリット ==
バージョンレスターゲットには、いくつかのデメリットがある。<br>
<br>
バージョンレスターゲットはALIASターゲットであり、バージョン付きターゲットのターゲットプロパティが無い。<br>
<br>
プロジェクトは、バージョンレスターゲットを公開するターゲットをエクスポートしてはならない。<br>
例えば、他のプロジェクトにより消費されるライブラリは、バージョンレスターゲットに対して公にリンクするターゲットをエクスポートしてはならない。<br>
これは、推移的依存関係が壊れたり、そのライブラリのユーザがQt 5とQt 6のターゲットを不本意に混在させたりする可能性がある。<br>
<br><br>

== WindowsのUnicodeサポート ==
Qt 6では、Qtモジュールに対してリンクするターゲットに対して、<code>UNICODE</code>と<code>_UNICODE</code>コンパイラ定義がデフォルトで有効化されている。<br>
これは、qmakeコマンドの動作と同様であるが、Qt 5のCMake APIの動作と差異がある。<br>
<br>
ターゲット上において、[[CMake_-_Qtコマンド#qt_disable_unicode_definesコマンド|<code>qt_disable_unicode_defines</code>]]コマンドを実行して、<code>UNICODE</code>と<code>_UNICODE</code>コンパイラ定義を無効にする。<br>
 <syntaxhighlight lang="cmake">
 find_package(Qt6 COMPONENTS Core)
 
 add_executable(myApp
    # ...略
 )
 
 qt_disable_unicode_defines(myApp)
 </syntaxhighlight>
<br><br>


__FORCETOC__
[[カテゴリ:Qt]]