Compatibilidad entre Qt 5 y Qt 6
La semántica de la API de CMake en Qt 5 y Qt 6 es en gran medida compatible, aunque existen algunas diferencias en el comportamiento de estos comandos e interfaces adicionales que solo están presentes en las últimas versiones. Esta guía está dirigida principalmente a proyectos que pretenden realizar una migración gradual de una versión principal a otra.
Hasta Qt 5.14, todos los objetivos y comandos de las bibliotecas Qt importadas incluían el número de versión como parte del nombre, por ejemplo, qt5_add_library. Esto hace que escribir código CMake que funcione tanto con Qt 5 como con Qt 6 resulte algo engorroso. Por ello, Qt 5.15 introdujo objetivos y comandos sin versión, es decir, qt_add_library, para permitir escribir código CMake que sea en gran medida independiente de las diferentes versiones de Qt.
Objetivos sin versión
Además de los objetivos importados ya existentes, Qt 5.15 introdujo objetivos sin versión. Es decir, para enlazar con Qt Core se puede hacer referencia tanto a Qt6::Core como a 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)El fragmento de código anterior intenta primero encontrar una instalación de Qt 6. Si eso falla, intenta encontrar un paquete de Qt 5.15. Independientemente de si se utiliza Qt 6 o Qt 5, podemos usar el objetivo importado Qt::Core. Para omitir la comprobación de Qt 6, establece CMAKE_DISABLE_FIND_PACKAGE_Qt6 antes de la llamada a ` find_package `.
Los objetivos sin versión están definidos por defecto. Establece QT_NO_CREATE_VERSIONLESS_TARGETS antes de la primera llamada a find_package() para desactivarlos.
Comandos sin versión
Desde Qt 5.15, los módulos de Qt también ofrecen variantes sin versión de sus comandos. Por ejemplo, ahora puedes utilizar qt_add_translation() para compilar archivos de traducción, independientemente de si utilizas Qt 5 o Qt 6.
Establece QT_NO_CREATE_VERSIONLESS_FUNCTIONS antes de la primera llamada a find_package() para evitar la creación de comandos sin versión.
Mezcla de Qt 5 y Qt 6
Puede haber proyectos que necesiten cargar tanto Qt 5 como Qt 6 en un mismo contexto de CMake (aunque no se admite mezclar versiones de Qt en una misma biblioteca o ejecutable, así que hay que tener cuidado con esto).
En tal configuración, los objetivos y comandos sin versión harán referencia implícita a la primera versión de Qt que se haya encontrado mediante ` find_package`. Establece la variable de CMake ` QT_DEFAULT_MAJOR_VERSION ` antes de la primera llamada a ` find_package ` para que la versión sea explícita.
Compatibilidad con versiones de Qt 5 anteriores a la 5.15
Si necesitas dar soporte también a versiones de Qt 5 anteriores a la 5.15, puedes hacerlo almacenando la versión actual en una variable de 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)En comparación con el enfoque sin versión, los objetivos apuntan a Qt${QT_VERSION_MAJOR}::Core, que se resuelve como Qt5::Core o Qt6::Core durante la llamada a target_link_libraries.
Prácticas recomendadas
Utiliza las variantes sin versión de los comandos de CMake siempre que sea posible.
Utiliza los objetivos con versión, a menos que tengas que dar soporte a Qt 5 y Qt 6 en el mismo proyecto.
Si tienes que utilizar objetivos sin versión, ten en cuenta los riesgos que conlleva su uso.
Utiliza las versiones con número de versión de los comandos y objetivos de CMake si necesitas dar soporte a versiones de Qt 5 anteriores a la 5.15, o si no puedes controlar si tu código CMake se carga en un contexto en el que puedan estar definidas las opciones QT_NO_CREATE_VERSIONLESS_FUNCTIONS o QT_NO_CREATE_VERSIONLESS_TARGETS. En este caso, aún puede simplificar su código determinando el nombre real del comando o del objetivo mediante una variable.
Inconvenientes al utilizar objetivos sin versión
El uso de los objetivos sin versión presenta varias desventajas.
Los objetivos sin versión suelen ser objetivos « ALIAS » y no se puede crear un objetivo « ALIAS » que apunte a un objetivo « ALIAS ». En su lugar, utiliza la ALIASED_TARGET propiedad «target».
En versiones anteriores de Qt 6, el objetivo « Qt::Core » importado no incluía todas las propiedades de objetivo expuestas por « Qt6::Core ». Esto se soluciona si se enlaza con Qt 6.8 o posterior, con CMake 3.18 o posterior.
Los proyectos no deben exportar objetivos que expongan los objetivos sin versión. Por ejemplo, una biblioteca utilizada por otro proyecto no debe exportar objetivos que se enlacen públicamente con objetivos sin versión. De lo contrario, las dependencias transitivas podrían romperse, o el usuario de esa biblioteca podría mezclar involuntariamente objetivos de Qt5 y Qt6.
Compatibilidad con Unicode en Windows
En Qt 6, las definiciones del compilador UNICODE y _UNICODE se establecen por defecto para los objetivos que se vinculan con módulos de Qt. Esto se ajusta al comportamiento de qmake, pero supone un cambio con respecto al comportamiento de la API de CMake en Qt 5.
Llama a ` qt_disable_unicode_defines()` en el objetivo para no establecer las definiciones.
find_package(Qt6 COMPONENTS Core)
add_executable(helloworld
...
)
qt_disable_unicode_defines(helloworld)© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.