Compatibilidad con 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 sólo en las últimas versiones. Esta guía está pensada principalmente para proyectos que buscan una migración gradual de una versión principal a otra.

Hasta Qt 5.14, todos los objetivos y comandos importados de las librerías Qt contenían el número de versión como parte del nombre, por ejemplo qt5_add_library. Esto hace que escribir código CMake que debería funcionar tanto con Qt 5 como con Qt 6 sea algo engorroso. Qt 5.15 por lo tanto introdujo objetivos y comandos sin versión, es decir qt_add_library, para permitir escribir código CMake que es en gran medida agnóstico a las diferentes versiones de Qt.

Objetivos sin versión

Además de los objetivos importados 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 snippet anterior primero intenta encontrar una instalación de Qt 6. Si eso falla, intenta encontrar una instalación de Qt 5.15. Si eso falla, intenta encontrar un paquete Qt 5.15. Independientemente de si se utiliza Qt 6 o Qt 5, podemos utilizar el objetivo importado Qt::Core. Para omitir la comprobación de Qt 6, establezca 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 Qt también proporcionan variantes sin versión de sus comandos. Por ejemplo, ahora puedes usar qt_add_translation para compilar ficheros de traducción, independientemente de si usas 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.

Mezclando Qt 5 y Qt 6

Puede haber proyectos que necesiten cargar Qt 5 y Qt 6 en un contexto CMake (aunque mezclar versiones de Qt en una librería o ejecutable no está soportado, así que ten cuidado).

En este caso, los objetivos y comandos sin versión se referirán implícitamente a la primera versión de Qt encontrada en find_package. Establezca la variable CMake QT_DEFAULT_MAJOR_VERSION antes de la primera llamada a find_package para hacer explícita la versión.

Soporte de versiones de Qt 5 anteriores a la 5.15

Si necesitas soportar también versiones de Qt 5 anteriores a Qt 5.15, puedes hacerlo almacenando la versión actual en una 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)

En comparación con el enfoque sin versión, los objetivos apuntan a Qt${QT_VERSION_MAJOR}::Core, que se resuelve a Qt5::Core o Qt6::Core durante la llamada a target_link_libraries.

Prácticas recomendadas

Utilice las variantes sin versión de los comandos CMake siempre que sea posible.

Use los objetivos versionados a menos que tenga que soportar Qt 5 y Qt 6 en el mismo proyecto.

Si tiene que utilizar objetivos sin versión, tenga en cuenta los Problemas al utilizar objetivos sin versión.

Usa las versiones versionadas de los comandos y objetivos CMake si necesitas soportar versiones de Qt 5 anteriores a Qt 5.15, o si no puedes controlar si tu código CMake se carga en un contexto donde QT_NO_CREATE_VERSIONLESS_FUNCTIONS o QT_NO_CREATE_VERSIONLESS_TARGETS podrían estar definidos. En este caso, aún puedes simplificar tu código determinando el comando real o el nombre del objetivo a través de una variable.

Problemas al utilizar objetivos sin versión

El uso de objetivos sin versión tiene varios inconvenientes.

Los objetivos sin versión suelen ser objetivos ALIAS y no se puede hacer que un objetivo ALIAS apunte a un objetivo ALIAS. En su lugar, utilice la propiedad ALIASED_TARGET propiedad target.

Para versiones anteriores de Qt 6, el objetivo importado Qt::Core no presentaba 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 librería que es consumida por otro proyecto no debe exportar objetivos que enlacen públicamente contra objetivos sin versión. De lo contrario, las dependencias transitivas podrían romperse, o el usuario de esa biblioteca mezclaría objetivos Qt5 y Qt6 involuntariamente.

Soporte Unicode en Windows

En Qt 6, las definiciones del compilador UNICODE y _UNICODE se establecen por defecto para los objetivos que enlazan contra módulos Qt. Esto está en línea con el comportamiento de qmake, pero es un cambio comparado con el comportamiento de la API CMake en Qt 5.

Llame 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)