QT_DEPLOY_RUN타임_종속성

실행 파일에 필요한 Qt 플러그인, Qt 및 비 Qt 라이브러리를 배포합니다.

이 명령은 Qt6 패키지의 Core 컴포넌트에 정의되어 있으며, 다음과 같이 로드할 수 있습니다:

find_package(Qt6 REQUIRED COMPONENTS Core)

Qt에서 제공하는 대부분의 다른 CMake 명령과 달리 qt_deploy_runtime_dependencies() 은 배포 스크립트에서만 호출할 수 있습니다. 구성 단계에서는 프로젝트에서 직접 호출할 수 없습니다.

이 명령은 Qt 6.3에 도입되었습니다.

시놉시스

qt_deploy_runtime_dependencies(
    EXECUTABLE executable
    [ADDITIONAL_EXECUTABLES files...]
    [ADDITIONAL_LIBRARIES files...]
    [ADDITIONAL_MODULES files...]
    [GENERATE_QT_CONF]
    [BIN_DIR bin_dir]
    [LIBEXEC_DIR libexec_dir]
    [LIB_DIR lib_dir]
    [PLUGINS_DIR plugins_dir]
    [QML_DIR qml_dir]
    [VERBOSE]
    [NO_OVERWRITE]
    [NO_APP_STORE_COMPLIANCE]
    [NO_TRANSLATIONS]
    [NO_COMPILER_RUNTIME]
    [DEPLOY_TOOL_OPTIONS]
    [PRE_INCLUDE_REGEXES regexes...]
    [PRE_EXCLUDE_REGEXES regexes...]
    [POST_INCLUDE_REGEXES regexes...]
    [POST_EXCLUDE_REGEXES regexes...]
    [POST_INCLUDE_FILES files...]
    [POST_EXCLUDE_FILES files...]
)

설명

애플리케이션을 설치할 때 애플리케이션이 의존하는 라이브러리와 플러그인도 함께 설치하는 것이 바람직할 수 있습니다. 애플리케이션이 macOS 앱 번들이거나 Windows 실행 파일인 경우 설치 시간 스크립트에서 qt_deploy_runtime_dependencies() 을 호출하여 이러한 종속성을 배포할 수 있습니다. 이 명령은 비시스템 Qt 라이브러리와 적절한 Qt 플러그인 세트를 설치합니다.

Linux에서는 이 명령이 프로젝트에 포함된 Qt 관련 라이브러리 외에 추가 라이브러리를 배포합니다. 그러나 macOS나 Windows에서 실행할 때는 macdeployqt 또는 windeployqt 을 사용하며, 이 명령은 Qt에 특정한 라이브러리만 배포합니다.

이 명령은 기본 바이너리에 링크 관계가 존재하는 런타임 종속성만 고려합니다. QML 모듈은 배포하지 않습니다. 이에 대해서는 qt_deploy_qml_imports()를 참조하십시오.

인자

EXECUTABLE 옵션을 제공해야 합니다.

executable 인수는 빌드 디렉터리에 있는 실행 파일의 경로여야 합니다. 예를 들어 ${CMAKE_CURRENT_BINARY_DIR}/MyApp.exe 또는 더 동적으로 $<TARGET_FILE:MyApp> 입니다. <TARGET_FILE:> 와 같이 생성기 표현식으로 래핑되지 않은 원시 대상 이름을 지정하는 것은 지원되지 않습니다.

macOS 앱 번들의 경우 executable 인수는 기본 설치 위치를 기준으로 번들 디렉터리 경로여야 합니다. 예를 들어 MyApp.app 또는 더 동적으로 $<TARGET_FILE_NAME:MyApp>.app 입니다. <TARGET_FILE_NAME:> 와 같이 생성기 표현식으로 래핑되지 않은 원시 대상 이름을 지정하는 것은 지원되지 않습니다.

executable 과 관련된 다른 바이너리에 대한 종속성을 설치하는 것도 바람직할 수 있습니다. 예를 들어 프로젝트에서 제공하는 플러그인에는 추가 종속성이 있을 수 있지만 이러한 플러그인은 실행 파일에 직접 연결되지 않으므로 qt_deploy_runtime_dependencies() 에서 자동으로 검색되지 않습니다. ADDITIONAL_EXECUTABLES , ADDITIONAL_LIBRARIES, ADDITIONAL_MODULES 옵션을 사용하여 종속성을 배포해야 하는 추가 바이너리를 지정할 수 있습니다(명명된 바이너리 자체의 설치는 여전히 프로젝트의 책임입니다). 이러한 키워드의 명명은 CMake의 규칙을 따르므로 Qt 플러그인은 ADDITIONAL_MODULES 을 사용하여 지정할 수 있습니다. 각 값은 기본 설치 위치를 기준으로 한 경로여야 합니다. 값은 EXECUTABLE 옵션과 마찬가지로 생성기 표현식을 사용할 수 있습니다. <TARGET_FILE_NAME:> 와 같이 제너레이터 표현식으로 래핑되지 않은 원시 대상 이름을 지정하는 것은 지원되지 않습니다.

Windows 애플리케이션을 설치할 때 CMake의 기본 설치 디렉토리 구조를 따를 때 qt.conf 파일이 필요한 경우가 일반적입니다. GENERATE_QT_CONF 옵션이 주어지면 적절한 qt.conf 파일이 executable 과 같은 디렉터리에 작성됩니다. 해당 qt.conf 파일의 경로는 기본값은 CMake의 GNUInstallDirs 모듈에서 제공하는 CMAKE_INSTALL_xxxDIR 변수를 기반으로 합니다.

다음 표의 매개변수를 사용하여 이러한 기본값 중 일부를 재정의할 수 있으며, 모든 기본값은 기본 설치 위치에 상대적일 것으로 예상됩니다.

qt.conf 파일은 GENERATE_QT_CONF 제공 여부에 관계없이 executable 이 macOS 앱 번들인 경우 항상 작성됩니다. 이 경우 앱 번들의 디렉토리 레이아웃은 Apple의 요구 사항에 따라 결정되므로 ..._DIR 옵션도 무시됩니다.

VERBOSE 옵션을 제공하면 배포 단계에 대한 자세한 출력을 활성화할 수 있습니다. 또는 첫 번째 find_package(Qt6) 호출 전에 프로젝트에서 QT_ENABLE_VERBOSE_DEPLOYMENT 변수를 설정하여 기본적으로 배포 출력을 상세하게 표시하도록 할 수 있습니다.

qt_deploy_runtime_dependencies() 명령은 기본적으로 기존 파일을 덮어씁니다(일부 경고가 계속 표시될 수 있음). 기존 파일을 덮어쓰지 않으려면 NO_OVERWRITE 옵션을 사용하세요. 이 옵션은 현재 macOS 및 Windows 배포에만 영향을 줍니다.

기본적으로 executable 이 macOS 앱 번들인 경우, Apple의 앱 스토어 요구 사항을 준수하는 Qt 플러그인 및 Qt 라이브러리만 배포됩니다. NO_APP_STORE_COMPLIANCE 옵션을 지정하여 해당 제약 조건을 비활성화할 수 있습니다.

macOS 이외의 플랫폼에서는 Qt 번역이 자동으로 배포됩니다. 이 동작을 억제하려면 NO_TRANSLATIONS 을 지정하세요. 사용자 정의된 방식으로 번역을 배포하려면 qt_deploy_translations()를 사용합니다.

Windows 데스크톱 애플리케이션의 경우 컴파일러에 필요한 런타임 파일도 기본적으로 설치됩니다. 이를 방지하려면 NO_COMPILER_RUNTIME 을 지정하세요.

Qt 6.7부터는 DEPLOY_TOOL_OPTIONS 을 사용하여 기본 배포 도구에 추가 옵션을 전달할 수 있습니다. 이 옵션은 기본 배포 도구가 맥디플로이큐트 또는 윈디플로이큐트인 경우에만 적용됩니다.

Linux에서 런타임 종속성 배포는 CMake의 file(GET_RUNTIME_DEPENDENCIES) 명령을 기반으로 합니다. PRE_INCLUDE_REGEXES , PRE_EXCLUDE_REGEXES, POST_INCLUDE_REGEXES, POST_EXCLUDE_REGEXES, POST_INCLUDE_FILES, POST_EXCLUDE_FILES 옵션은 이 컨텍스트에서만 의미가 있으며 변경되지 않고 file(GET_RUNTIME_DEPENDENCIES) 으로 전달됩니다. 자세한 내용은 해당 명령의 설명서를 참조하세요.

Linux에서는 시스템 라이브러리 디렉터리에 있는 런타임 종속성은 기본적으로 배포되지 않습니다. POST_EXCLUDE_REGEXES 을 지정하면 이 자동 제외가 수행되지 않습니다.

기본값 POST_EXCLUDE_REGEXES 은 QT_DEPLOY_IGNORED_LIB_DIRS의 값으로 구성됩니다.

예제

다음 예는 애플리케이션을 배포하는 방법을 보여줍니다 MyApp.

cmake_minimum_required(VERSION 3.16...3.22)
project(MyThings)

find_package(Qt6 REQUIRED COMPONENTS Core)
qt_standard_project_setup()

qt_add_executable(MyApp main.cpp)

set_target_properties(MyApp PROPERTIES
    WIN32_EXECUTABLE TRUE
    MACOSX_BUNDLE TRUE
)

# App bundles on macOS have an .app suffix
if(APPLE)
    set(executable_path "$<TARGET_FILE_NAME:MyApp>.app")
else()
    set(executable_path "\${QT_DEPLOY_BIN_DIR}/$<TARGET_FILE_NAME:MyApp>")
endif()

# Helper app, not necessarily built as part of this project.
qt_add_executable(HelperApp helper.cpp)
set(helper_app_path "\${QT_DEPLOY_BIN_DIR}/$<TARGET_FILE_NAME:HelperApp>")

# Generate a deployment script to be executed at install time
qt_generate_deploy_script(
    TARGET MyApp
    OUTPUT_SCRIPT deploy_script
    CONTENT "
qt_deploy_runtime_dependencies(
    EXECUTABLE \"${executable_path}\"
    ADDITIONAL_EXECUTABLES \"${helper_app_path}\"
    GENERATE_QT_CONF
    VERBOSE
)")

# Omitting RUNTIME DESTINATION will install a non-bundle target to CMAKE_INSTALL_BINDIR,
# which coincides with the default value of QT_DEPLOY_BIN_DIR used above, './bin'.
# Installing macOS bundles always requires an explicit BUNDLE DESTINATION option.
install(TARGETS MyApp HelperApp    # Install to CMAKE_INSTALL_PREFIX/bin/MyApp.exe
                                   #                           and ./binHelperApp.exe
        BUNDLE  DESTINATION .      # Install to CMAKE_INSTALL_PREFIX/MyApp.app/Contents/MacOS/MyApp
)
install(SCRIPT ${deploy_script})    # Add its runtime dependencies

다음 예는 DEPLOY_TOOL_OPTIONS 매개 변수를 사용하여 macdeployqt 및 windeployqt에 다른 옵션을 전달하는 방법을 보여줍니다.

set(deploy_tool_options_arg "")
if(APPLE)
    set(deploy_tool_options_arg --hardened-runtime)
elseif(WIN32)
    set(deploy_tool_options_arg --no-compiler-runtime)
endif()

# Generate a deployment script to be executed at install time
qt_generate_deploy_script(
    TARGET MyApp
    OUTPUT_SCRIPT deploy_script
    CONTENT "
qt_deploy_runtime_dependencies(
    EXECUTABLE \"${executable_path}\"
    DEPLOY_TOOL_OPTIONS "${deploy_tool_options_arg}"
    GENERATE_QT_CONF
    VERBOSE
)")