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 변수를 설정합니다.

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 버전을 지원해야 하거나 QT_NO_CREATE_VERSIONLESS_FUNCTIONS 또는 QT_NO_CREATE_VERSIONLESS_TARGETS가 정의될 수 있는 상황에서 CMake 코드의 로드 여부를 제어할 수 없는 경우 버전이 있는 버전의 CMake 명령과 타깃을 사용해야 합니다. 이 경우에도 변수를 통해 실제 명령 또는 대상 이름을 결정하여 코드를 단순화할 수 있습니다.

버전 없는 타깃 사용 시 위험 요소

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

버전 없는 타깃은 일반적으로 ALIAS 타깃이며 ALIAS 타깃이 ALIAS 타깃을 가리키도록 만들 수 없습니다. 대신 ALIASED_TARGET 대상 속성을 사용합니다.

이전 Qt 6 버전의 경우, 가져온 Qt::Core 타깃은 Qt6::Core 에 의해 노출된 모든 타깃 속성을 포함하지 않았습니다. 이 문제는 CMake 3.18 이상에서 Qt 6.8 이상으로 링크하는 경우 해결되었습니다.

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

윈도우에서 유니코드 지원

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)