Compatibilité Qt 5 et Qt 6

La sémantique de l'API CMake dans Qt 5 et Qt 6 est largement compatible, bien que quelques différences existent dans le comportement de ces commandes et des interfaces supplémentaires uniquement dans ces dernières versions. Ce guide est principalement destiné aux projets qui envisagent une migration progressive d'une version majeure à l'autre.

Jusqu'à Qt 5.14, toutes les cibles et commandes importées de la bibliothèque Qt contenaient le numéro de version dans leur nom, par exemple qt5_add_library. Cela rend l'écriture de code CMake qui devrait fonctionner à la fois avec Qt 5 et Qt 6 quelque peu encombrante. Qt 5.15 a donc introduit des cibles et des commandes sans version, c'est-à-dire qt_add_library, pour permettre l'écriture de code CMake qui est largement agnostique aux différentes versions de Qt.

Cibles sans version

En plus des cibles importées existantes, Qt 5.15 a introduit des cibles sans version. En d'autres termes, pour établir un lien avec Qt Core on peut à la fois référencer Qt6::Core, ou 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)

L'extrait ci-dessus tente d'abord de trouver une installation de Qt 6. En cas d'échec, il tente de trouver un paquetage Qt 5.15. Indépendamment de l'utilisation de Qt 6 ou Qt 5, nous pouvons utiliser la cible importée Qt::Core. Pour ignorer la vérification de Qt 6, mettez CMAKE_DISABLE_FIND_PACKAGE_Qt6 avant l'appel à find_package.

Les cibles sans version sont définies par défaut. Définissez QT_NO_CREATE_VERSIONLESS_TARGETS avant le premier appel à find_package() pour les désactiver.

Commandes sans version

Depuis Qt 5.15, les modules Qt fournissent également des variantes sans version de leurs commandes. Vous pouvez par exemple utiliser qt_add_translation pour compiler les fichiers de traduction, indépendamment du fait que vous utilisiez Qt 5 ou Qt 6.

Définissez QT_NO_CREATE_VERSIONLESS_FUNCTIONS avant le premier appel à find_package() pour empêcher la création de commandes sans version.

Mélanger Qt 5 et Qt 6

Il peut y avoir des projets qui ont besoin de charger à la fois Qt 5 et Qt 6 dans un contexte CMake (bien que le mélange des versions de Qt dans une bibliothèque ou un exécutable ne soit pas supporté, donc soyez prudent).

Dans une telle configuration, les cibles et les commandes sans version feront implicitement référence à la première version de Qt trouvée via find_package. Définissez la variable CMake QT_DEFAULT_MAJOR_VERSION avant le premier appel à find_package pour rendre la version explicite.

Prise en charge des versions de Qt 5 antérieures à la version 5.15

Si vous avez besoin de supporter également les versions de Qt 5 antérieures à Qt 5.15, vous pouvez le faire en stockant la version actuelle dans une variable 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)

Par rapport à l'approche sans version, les cibles pointent vers Qt${QT_VERSION_MAJOR}::Core, qui est résolu en Qt5::Core ou Qt6::Core lors de l'appel de target_link_libraries.

Pratiques recommandées

Utilisez les variantes sans version des commandes CMake dans la mesure du possible.

Utilisez les cibles avec version sauf si vous devez supporter Qt 5 et Qt 6 dans le même projet.

Si vous devez utiliser des cibles sans version, soyez conscient des pièges liés à l'utilisation de cibles sans version.

Utilisez les versions versionnées des commandes et cibles CMake si vous devez supporter des versions de Qt 5 antérieures à Qt 5.15, ou si vous ne pouvez pas contrôler si votre code CMake est chargé dans un contexte où QT_NO_CREATE_VERSIONLESS_FUNCTIONS ou QT_NO_CREATE_VERSIONLESS_TARGETS pourrait être défini. Dans ce cas, vous pouvez toujours simplifier votre code en déterminant le nom de la commande ou de la cible à l'aide d'une variable.

Pièges liés à l'utilisation des cibles sans version

L'utilisation des cibles sans version présente plusieurs inconvénients.

Les cibles sans version sont généralement des cibles ALIAS et vous ne pouvez pas faire pointer une cible ALIAS vers une cible ALIAS. Au lieu de cela, utilisez la propriété ALIASED_TARGET target.

Pour les anciennes versions de Qt 6, la cible importée Qt::Core ne comportait pas toutes les propriétés de cible exposées par Qt6::Core. Ce problème est corrigé si vous créez un lien avec Qt 6.8 ou une version plus récente, avec CMake 3.18 ou une version plus récente.

Les projets ne doivent pas exporter des cibles qui exposent les cibles sans version. Par exemple, une bibliothèque qui est consommée par un autre projet ne doit pas exporter de cibles qui se lient publiquement à des cibles sans version. Dans le cas contraire, les dépendances transitives pourraient être rompues, ou l'utilisateur de cette bibliothèque mélangerait involontairement des cibles Qt5 et Qt6.

Prise en charge de l'Unicode dans Windows

Dans Qt 6, les définitions des compilateurs UNICODE et _UNICODE sont définies par défaut pour les cibles qui se lient aux modules Qt. Cela correspond au comportement de qmake, mais c'est un changement par rapport au comportement de l'API CMake dans Qt 5.

Appelez qt_disable_unicode_defines() sur la cible pour ne pas définir les définitions.

find_package(Qt6 COMPONENTS Core)

add_executable(helloworld
    ...
)

qt_disable_unicode_defines(helloworld)