Qt 5 및 Qt 6 호환성

Qt 5와 Qt 6의 CMake API 의미론은 대체로 호환되지만, 일부 명령어의 동작에는 차이가 있으며 후자 버전에만 추가된 인터페이스도 존재합니다. 이 가이드는 주로 한 주요 릴리스에서 다른 주요 릴리스로 점진적인 마이그레이션을 고려 중인 프로젝트를 대상으로 합니다.

Qt 5.14까지, 가져온 모든 Qt 라이브러리 타깃과 명령어에는 이름의 일부로 버전 번호가 포함되어 있었습니다(예: qt5_add_library). 이로 인해 Qt 5와 Qt 6 모두에서 작동해야 하는 CMake 코드를 작성하는 것이 다소 번거로웠습니다. 따라서 Qt 5.15에서는 버전 정보가 없는 타겟 및 명령어(예: qt_add_library)를 도입하여, 서로 다른 Qt 버전에 크게 구애받지 않는 CMake 코드를 작성할 수 있도록 했습니다.

버전 미지정 타깃

기존의 임포트된 타깃 외에도, Qt 5.15에서는 버전 독립적 타깃이 도입되었습니다. 즉, Qt CoreQt6::Core 나 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)

위의 코드 조각은 먼저 Qt 6 설치본을 찾으려고 시도합니다. 실패할 경우 Qt 5.15 패키지를 찾으려고 시도합니다. Qt 6을 사용하든 Qt 5를 사용하든 상관없이, 임포트된 Qt::Core 타깃을 사용할 수 있습니다. Qt 6 확인 단계를 건너뛰려면 CMAKE_DISABLE_FIND_PACKAGE_Qt6find_package 호출 전에 설정하십시오.

버전 정보가 없는 타깃은 기본적으로 정의되어 있습니다. 이를 비활성화하려면 첫 번째 find_package() 호출 전에 QT_NO_CREATE_VERSIONLESS_TARGETS를 설정하십시오.

버전 없는 명령어

Qt 5.15부터 Qt 모듈은 명령어의 버전 미지정 변형도 제공합니다. 예를 들어, 이제 Qt 5를 사용하든 Qt 6을 사용하든 상관없이 qt_add_translation()을 사용하여 번역 파일을 컴파일할 수 있습니다.

버전 독립적인 명령어의 생성을 방지하려면 첫 번째 ` find_package() ` 호출 전에 ` QT_NO_CREATE_VERSIONLESS_FUNCTIONS `를 설정하십시오.

Qt 5와 Qt 6의 혼합 사용

하나의 CMake 컨텍스트에서 Qt 5와 Qt 6을 모두 불러와야 하는 프로젝트가 있을 수 있습니다(단, 하나의 라이브러리나 실행 파일 내에서 Qt 버전을 혼합하는 것은 지원되지 않으므로 주의해야 합니다).

이러한 설정에서는 버전 정보가 없는 타깃과 명령이 find_package 를 통해 발견된 첫 번째 Qt 버전을 암시적으로 참조하게 됩니다. 버전을 명시적으로 지정하려면 첫 번째 find_package 호출 전에 QT_DEFAULT_MAJOR_VERSION CMake 변수를 설정하십시오.

Qt 5.15보다 오래된 Qt 5 버전 지원

Qt 5.15보다 오래된 Qt 5 버전도 지원해야 하는 경우, 현재 버전을 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)

버전을 명시하지 않는 방식과 비교하여, 타깃은 Qt${QT_VERSION_MAJOR}::Core 을 가리키며, 이는 target_link_libraries 호출 시 Qt5::Core 또는 Qt6::Core 중 하나로 해결됩니다.

권장 사항

가능한 경우 CMake 명령어의 버전 미지정 변형을 사용하십시오.

동일한 프로젝트에서 Qt 5와 Qt 6을 모두 지원해야 하는 경우가 아니라면, 버전이 지정된 타깃을 사용하십시오.

버전 정보가 없는 타깃을 사용해야 하는 경우, 버전 정보가 없는 타깃 사용 시 주의해야 할 사항을 숙지하십시오.

Qt 5.15보다 오래된 Qt 5 버전을 지원해야 하는 경우, 또는 CMake 코드가 QT_NO_CREATE_VERSIONLESS_FUNCTIONS 또는 QT_NO_CREATE_VERSIONLESS_TARGETS가 정의될 수 있는 컨텍스트에서 로드되는지 여부를 제어할 수 없는 경우에는 CMake 명령어 및 타깃의 버전 지정 버전을 사용하십시오. 이 경우에도 변수를 통해 실제 명령어나 타겟 이름을 결정함으로써 코드를 간소화할 수 있습니다.

버전 없는 타겟 사용 시 주의할 점

버전 없는 타깃을 사용하면 몇 가지 단점이 있습니다.

버전 없는 타깃은 대개 ` ALIAS ` 타깃이며, ` ALIAS ` 타깃을 가리키는 ` ALIAS ` 타깃을 만들 수 없습니다. 대신, ALIASED_TARGET 타깃 속성을 사용하십시오.

이전 버전의 Qt 6에서는, 가져온 ` Qt::Core ` 타깃이 ` Qt6::Core`에서 노출하는 모든 타깃 속성을 지원하지 않았습니다. 이 문제는 CMake 3.18 이상 버전을 사용하여 Qt 6.8 이상에 링크할 경우 해결됩니다.

프로젝트는 버전 정보가 없는 타깃을 노출하는 타깃을 내보내서는 안 됩니다. 예를 들어, 다른 프로젝트에서 사용되는 라이브러리는 버전 정보가 없는 타깃에 대해 공개적으로 링크되는 타깃을 내보내서는 안 됩니다. 그렇지 않으면 전이적 의존성이 깨지거나, 해당 라이브러리 사용자가 의도치 않게 Qt5와 Qt6 타깃을 혼용하게 될 수 있습니다.

Windows에서의 유니코드 지원

Qt 6에서는 Qt 모듈에 링크되는 타깃에 대해 UNICODE 및 _UNICODE 컴파일러 정의가 기본적으로 설정됩니다. 이는 qmake의 동작과 일치하지만, Qt 5의 CMake API 동작과는 다른 변경 사항입니다.

정의가 설정되지 않도록 하려면 대상에서 qt_disable_unicode_defines()를 호출하십시오.

find_package(Qt6 COMPONENTS Core)

add_executable(helloworld
    ...
)

qt_disable_unicode_defines(helloworld)