Qt 5와 Qt 6 호환성

Qt 5와 Qt 6에서 CMake API의 의미는 대체로 호환됩니다. 그러나 Qt 5.14까지는 가져온 모든 Qt 라이브러리 타겟과 명령에 버전 번호가 이름에 포함되어 있었습니다. 이로 인해 Qt 5와 Qt 6 모두에서 작동해야 하는 CMake 코드를 작성하는 것이 다소 번거로웠습니다. 따라서 Qt 5.15에서는 버전리스 타겟과 명령어를 도입하여 다른 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 타깃을 사용할 수 있습니다.

버전리스 타겟은 기본적으로 정의되어 있습니다. 이를 비활성화하려면 첫 번째 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 버전 지원

Qt 5.15보다 오래된 Qt 5 버전도 지원해야 하는 경우 현재 버전을 CMake 변수에 저장하면 됩니다:

find_package(QT NAMES Qt6 Qt5 REQUIRED COMPONENTS Core)
find_package(Qt${QT_VERSION_MAJOR} REQUIRED COMPONENTS Core)

add_executable(helloworld
    ...
)

target_link_libraries(helloworld PRIVATE Qt${QT_VERSION_MAJOR}::Core)

여기서는 find_package(<PackageName>...) 이 먼저 Qt 6을 찾고, 실패하면 QT 이라는 이름으로 Qt 5를 찾도록 합니다. 둘 중 하나가 발견되면 find_package 이 성공하고 CMake 변수 QT_VERSION_MAJOR 는 5 또는 6 로 정의됩니다.

그런 다음 Qt${QT_VERSION_MAJOR} 라는 이름을 즉석에서 생성하여 결정된 Qt 버전에 대한 패키지를 다시 로드합니다. 이는 CMAKE_AUTOMOC 이 패키지 이름이 Qt5 또는 Qt6 일 것으로 예상하고 그렇지 않으면 오류를 출력하기 때문에 필요합니다.

동일한 패턴을 사용하여 가져온 라이브러리의 이름도 지정할 수 있습니다. target_link_libraries 을 호출하기 전에 CMake는 Qt${QT_VERSION_MAJOR}::Widgets 을 Qt5::Widgets 또는 Qt6::Widgets 으로 확인합니다.

권장 사례

가능하면 CMake 명령의 버전이 없는 변형을 사용하세요.

동일한 프로젝트에서 Qt 5와 Qt 6을 지원해야 하는 경우가 아니라면 버전이 있는 타깃을 사용하세요.

버전 없는 대상을 사용해야 하는 경우 버전 없는 대상을 사용할 때의 함정에 유의하세요.

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

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

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

버전리스 타깃은 ALIAS 타깃이며 버전이 있는 타깃의 타깃 속성이 없습니다.

프로젝트는 버전 없는 대상을 노출하는 대상을 내보내서는 안 됩니다. 예를 들어, 다른 프로젝트에서 사용하는 라이브러리는 버전 없는 대상에 공개적으로 링크되는 대상을 내보내서는 안 됩니다. 그렇지 않으면 전이 종속성이 깨지거나 해당 라이브러리 사용자가 무의식적으로 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)