Kompatibilität zwischen Qt 5 und Qt 6

Die Semantik der CMake-API in Qt 5 und Qt 6 ist weitgehend kompatibel, allerdings gibt es einige Unterschiede im Verhalten dieser Befehle sowie zusätzliche Schnittstellen, die nur in den neueren Versionen vorhanden sind. Dieser Leitfaden richtet sich in erster Linie an Projekte, die eine schrittweise Migration von einer Hauptversion zur nächsten planen.

Bis einschließlich Qt 5.14 enthielten alle importierten Qt-Bibliotheksziele und -Befehle die Versionsnummer als Teil des Namens, zum Beispiel qt5_add_library. Dies macht das Schreiben von CMake-Code, der sowohl mit Qt 5 als auch mit Qt 6 funktionieren soll, etwas umständlich. Mit Qt 5.15 wurden daher versionslose Ziele und Befehle eingeführt, d. h. qt_add_library, um das Schreiben von CMake-Code zu ermöglichen, der weitgehend unabhängig von den verschiedenen Qt-Versionen ist.

Versionsunabhängige Ziele

Zusätzlich zu den bereits vorhandenen importierten Zielen wurden in Qt 5.15 versionsunabhängige Ziele eingeführt. Das heißt, um gegen Qt Core kann man sowohl auf Qt6::Core als auch auf Qt::Core verweisen:

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)

Der obige Codeausschnitt versucht zunächst, eine Qt-6-Installation zu finden. Gelingt dies nicht, wird versucht, ein Qt-5.15-Paket zu finden. Unabhängig davon, ob Qt 6 oder Qt 5 verwendet wird, können wir das importierte Ziel „ Qt::Core “ nutzen. Um die Qt-6-Prüfung zu überspringen, setzen Sie CMAKE_DISABLE_FIND_PACKAGE_Qt6 vor dem Aufruf von ` find_package ` ein.

Die versionslosen Ziele sind standardmäßig definiert. Setzen Sie QT_NO_CREATE_VERSIONLESS_TARGETS vor dem ersten Aufruf von „ find_package() “, um sie zu deaktivieren.

Versionsunabhängige Befehle

Seit Qt 5.15 bieten die Qt-Module auch versionsunabhängige Varianten ihrer Befehle an. Sie können nun beispielsweise qt_add_translation() verwenden, um Übersetzungsdateien zu kompilieren, unabhängig davon, ob Sie Qt 5 oder Qt 6 verwenden.

Setzen Sie QT_NO_CREATE_VERSIONLESS_FUNCTIONS vor dem ersten Aufruf von ` find_package() `, um die Erstellung versionsloser Befehle zu verhindern.

Kombination von Qt 5 und Qt 6

Es kann Projekte geben, bei denen sowohl Qt 5 als auch Qt 6 in einem CMake-Kontext geladen werden müssen (allerdings wird die Vermischung von Qt-Versionen in einer Bibliothek oder einem ausführbaren Programm nicht unterstützt, seien Sie hier also vorsichtig).

In einer solchen Konfiguration beziehen sich die versionslosen Ziele und Befehle implizit auf die erste Qt-Version, die über ` find_package` gefunden wurde. Setzen Sie die CMake-Variable `QT_DEFAULT_MAJOR_VERSION` vor dem ersten Aufruf von ` find_package `, um die Version explizit festzulegen.

Unterstützung von Qt-5-Versionen älter als 5.15

Wenn Sie auch Qt-5-Versionen unterstützen müssen, die älter als Qt 5.15 sind, können Sie dies tun, indem Sie die aktuelle Version in einer CMake-Variablen (QT_VERSION_MAJOR) speichern:

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)

Im Vergleich zum versionlosen Ansatz verweisen die Ziele auf ` Qt${QT_VERSION_MAJOR}::Core`, das beim Aufruf von ` target_link_libraries` entweder zu ` Qt5::Core ` oder ` Qt6::Core ` aufgelöst wird.

Empfohlene Vorgehensweisen

Verwenden Sie nach Möglichkeit die versionslosen Varianten der CMake-Befehle.

Verwenden Sie die versionierten Ziele, es sei denn, Sie müssen Qt 5 und Qt 6 im selben Projekt unterstützen.

Wenn Sie versionslose Ziele verwenden müssen, beachten Sie die Fallstricke bei der Verwendung versionsloser Ziele.

Verwenden Sie die versionsabhängigen Versionen der CMake-Befehle und -Ziele, wenn Sie Qt-5-Versionen unterstützen müssen, die älter sind als Qt 5.15, oder wenn Sie nicht kontrollieren können, ob Ihr CMake-Code in einem Kontext geladen wird, in dem möglicherweise QT_NO_CREATE_VERSIONLESS_FUNCTIONS oder QT_NO_CREATE_VERSIONLESS_TARGETS definiert sind. In diesem Fall können Sie Ihren Code dennoch vereinfachen, indem Sie den tatsächlichen Befehls- oder Zielnamen über eine Variable ermitteln.

Fallstricke bei der Verwendung versionsloser Ziele

Die Verwendung der versionslosen Ziele hat mehrere Nachteile.

Die versionslosen Ziele sind in der Regel „ ALIAS “-Ziele, und Sie können kein „ ALIAS “-Ziel erstellen, das auf ein „ ALIAS “-Ziel verweist. Verwenden Sie stattdessen die ALIASED_TARGET Ziel-Eigenschaft.

Bei älteren Qt-6-Versionen verfügte das importierte Ziel „ Qt::Core “ nicht über alle Ziel-Eigenschaften, die von „ Qt6::Core “ bereitgestellt wurden. Dies ist behoben, wenn Sie mit Qt 6.8 oder neuer und CMake 3.18 oder neuer verknüpfen.

Projekte dürfen keine Ziele exportieren, die die versionslosen Ziele bereitstellen. Beispielsweise darf eine Bibliothek, die von einem anderen Projekt genutzt wird, keine Ziele exportieren, die öffentlich gegen versionslose Ziele verknüpft sind. Andernfalls könnten transitive Abhängigkeiten unterbrochen werden oder der Nutzer dieser Bibliothek mischt unbeabsichtigt Qt5- und Qt6-Ziele.

Unicode-Unterstützung unter Windows

In Qt 6 werden die Compiler-Definitionen „ UNICODE “ und „ _UNICODE “ standardmäßig für Ziele gesetzt, die gegen Qt-Module verknüpft sind. Dies entspricht dem Verhalten von qmake, stellt jedoch eine Änderung gegenüber dem Verhalten der CMake-API in Qt 5 dar.

Rufen Sie ` qt_disable_unicode_defines()` für das Ziel auf, um die Definitionen nicht zu setzen.

find_package(Qt6 COMPONENTS Core)

add_executable(helloworld
    ...
)

qt_disable_unicode_defines(helloworld)