Compatibilité entre Qt 5 et Qt 6

La sémantique de l’API CMake dans Qt 5 et Qt 6 est largement compatible, bien qu’il existe certaines différences dans le comportement de ces commandes et des interfaces supplémentaires propres aux versions les plus récentes. Ce guide s’adresse principalement aux projets envisageant une migration progressive d’une version majeure à une autre.

Jusqu’à Qt 5.14, toutes les cibles et commandes des bibliothèques Qt importées comportaient le numéro de version dans leur nom, par exemple qt5_add_library. Cela rendait quelque peu fastidieuse l’écriture de code CMake censé fonctionner à la fois avec Qt 5 et Qt 6. Qt 5.15 a donc introduit des cibles et des commandes sans version, c'est-à-dire qt_add_library, afin de permettre l'écriture de code CMake largement indépendant des différentes versions de Qt.

Cibles sans version

En plus des cibles importées existantes, Qt 5.15 a introduit des cibles sans version. Ainsi, pour lier à Qt Core , on peut aussi bien faire référence à Qt6::Core qu’à 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 de code ci-dessus tente d'abord de trouver une installation de Qt 6. En cas d'échec, il tente de trouver un paquet Qt 5.15. Que l'on utilise Qt 6 ou Qt 5, on peut utiliser la cible importée Qt::Core. Pour ignorer la vérification de Qt 6, définissez 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 désormais utiliser `qt_add_translation()` pour compiler des fichiers de traduction, 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élange de Qt 5 et Qt 6

Certains projets peuvent nécessiter de charger à la fois Qt 5 et Qt 6 dans un même contexte CMake (sachez toutefois que le mélange de versions de Qt au sein d’une même bibliothèque ou d’un même exécutable n’est pas pris en charge ; soyez donc vigilant à ce sujet).

Dans une telle configuration, les cibles et commandes sans version feront implicitement référence à la première version de Qt détecté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 devez également prendre en charge les versions de Qt 5 antérieures à la version 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ésolue soit en ` Qt5::Core `, soit en ` Qt6::Core ` lors de l'appel de ` target_link_libraries`.

Bonnes pratiques

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

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

Si vous devez utiliser des cibles sans version, tenez compte des pièges liés à leur utilisation.

Utilisez les versions avec numéro de version des commandes et cibles CMake si vous devez prendre en charge 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 pourraient être définis. Dans ce cas, vous pouvez tout de même simplifier votre code en déterminant le nom réel de la commande ou de la cible via une variable.

Pièges à éviter lors de l’utilisation de cibles sans version

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

Les cibles sans version sont généralement des cibles de type « ALIAS » et vous ne pouvez pas créer une cible « ALIAS » pointant vers une cible « ALIAS ». Utilisez plutôt la ALIASED_TARGET propriété « target ».

Dans les anciennes versions de Qt 6, la cible d Qt::Core importée ne disposait pas de toutes les propriétés de cible exposées par Qt6::Core. Ce problème est résolu si vous effectuez la liaison 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 de cibles exposant les cibles sans version. Par exemple, une bibliothèque utilisée par un autre projet ne doit pas exporter de cibles qui s’enchaînent publiquement à des cibles sans version. Sinon, les dépendances transitives pourraient être rompues, ou l’utilisateur de cette bibliothèque risquerait de mélanger involontairement des cibles Qt5 et Qt6.

Prise en charge d'Unicode sous Windows

Dans Qt 6, les définitions du compilateur ` UNICODE ` et ` _UNICODE ` sont activées par défaut pour les cibles qui se lient aux modules Qt. Cela correspond au comportement de qmake, mais constitue 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 ces définitions.

find_package(Qt6 COMPONENTS Core)

add_executable(helloworld
    ...
)

qt_disable_unicode_defines(helloworld)