qt_deploy_runtime_dependencies

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

이 명령은 Qt6 패키지의 Core 구성 요소에 정의되어 있으며, 다음과 같이 불러올 수 있습니다:

find_package(Qt6 REQUIRED COMPONENTS Core)

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

이 명령어는 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_PLUGINS]                                  # since Qt 6.10
    [EXCLUDE_PLUGIN_TYPES type...]                # since Qt 6.10
    [INCLUDE_PLUGIN_TYPES type...]                # since Qt 6.10
    [EXCLUDE_PLUGINS name...]                     # since Qt 6.10
    [INCLUDE_PLUGINS name...]                     # since Qt 6.10
    [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 모듈은 배포하지 않으므로, 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 옵션을 지정하면, executable 파일과 동일한 디렉터리에 적절한 qt.conf 파일이 작성됩니다. 해당 qt.conf 파일의 경로는 CMAKE_INSTALL_xxxDIR 변수를 기반으로 하며, 이 변수들의 기본값은 CMake의 GNUInstallDirs 모듈에서 제공됩니다.

다음 표에 나열된 매개변수를 사용하여 이러한 기본값 중 일부를 재정의할 수 있으며, 모든 매개변수는 기본 설치 경로를 기준으로 합니다.

executable 가 macOS 앱 번들인 경우 qt.conf 파일이 작성되지 않으며, 이 경우 GENERATE_QT_CONF 및 ..._DIR 옵션은 모두 무시됩니다. 앱 번들의 디렉터리 구조는 Apple의 요구 사항에 따라 정해지며, Qt는 qt.conf 없이도 해당 표준 위치에서 라이브러리, 플러그인 및 리소스를 찾습니다.

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 `을 사용하여 기본 배포 도구에 추가 옵션을 전달할 수 있습니다. 이 기능은 기본 배포 도구가 `macdeployqt` 또는 `windeployqt`인 경우에만 적용됩니다.

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) 로 전달됩니다. 자세한 내용은 해당 명령의 문서를 참조하십시오.

리눅스에서는 시스템 라이브러리 디렉터리에 위치한 런타임 종속성이 기본적으로 배포되지 않습니다. POST_EXCLUDE_REGEXES 가 지정된 경우, 이러한 자동 제외 처리는 수행되지 않습니다.

POST_EXCLUDE_REGEXES 의 기본값은 QT_DEPLOY_IGNORED_LIB_DIRS의 값을 기반으로 생성됩니다.

Qt 플러그인 배포 제어

Qt 플러그인은 QT_DEPLOY_PLUGINS_DIR에 자동으로 배포됩니다.

NO_PLUGINS 인수를 사용하여 플러그인 배포를 비활성화할 수 있습니다.

INCLUDE_PLUGIN_TYPES 인수를 사용하여 특정 유형의 모든 플러그인을 포함할 수 있습니다. EXCLUDE_PLUGIN_TYPES 인수를 사용하여 특정 유형의 모든 플러그인을 제외할 수 있습니다. 두 인수 모두 플러그인 유형(예: imageformats)을 받습니다.

INCLUDE_PLUGINS 및 EXCLUDE_PLUGINS 인수를 사용하여 특정 플러그인을 포함하거나 제외할 수 있습니다. 두 인수 모두 플러그인 이름을 매개변수로 받습니다(예: qjpeg).

예

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

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

find_package(Qt6 REQUIRED COMPONENTS Core)
qt_standard_project_setup()

# Keep the QT_DEPLOY_* references below for the generated script to expand,
# see \l {QTP0008}.
qt_policy(SET QTP0008 NEW)

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)
    # The CONTENT below is parsed when the generated script runs.
    # To preserve the code signing identity, it needs to be wrapped in escaped quotes.
    # In addition, all the options need to be wrapped into a single quoted string,
    # so that CMake doesn't replace each space with a semicolon in the generated text.
    set(deploy_tool_options_arg
        "-hardened-runtime \"-codesign=Developer ID Application: Joe Developer (1234567890)\""
    )
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
)")