qt_deploy_runtime_dependencies

Deploy Qt plugins, Qt and non-Qt libraries needed by an executable.

The command is defined in the Core component of the Qt6 package, which can be loaded like so:

find_package(Qt6 REQUIRED COMPONENTS Core)

Unlike most other CMake commands provided by Qt, qt_deploy_runtime_dependencies() can only be called from a deployment script. It cannot be called directly by the project during the configure stage.

This command was introduced in Qt 6.3.

Synopsis

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...]
)

Description

When installing an application, it may be desirable to also install the libraries and plugins it depends on. When the application is a macOS app bundle or a Windows executable, qt_deploy_runtime_dependencies() can be called from an install-time script to deploy those dependencies. It will install non-system Qt libraries plus an appropriate set of Qt plugins.

On Linux, the command will deploy additional libraries, beyond just those related to Qt, that are included with the project. However, when executed on macOS or Windows, the command will use either macdeployqt or windeployqt, which will only deploy libraries that are specific to Qt.

This command only considers runtime dependencies for which linking relationships exist in the underlying binaries. It does not deploy QML modules, see qt_deploy_qml_imports() for that.

Arguments

The EXECUTABLE option must be provided.

The executable argument should be the path to the executable file in the build directory. For example, ${CMAKE_CURRENT_BINARY_DIR}/MyApp.exe, or more dynamically $<TARGET_FILE:MyApp>. Specifying raw target names not wrapped in a generator expression like <TARGET_FILE:> is not supported.

For macOS app bundles, the executable argument should be a path to the bundle directory, relative to the base install location. For example MyApp.app, or more dynamically $<TARGET_FILE_NAME:MyApp>.app. Specifying raw target names not wrapped in a generator epxression like <TARGET_FILE_NAME:> is not supported.

It may also be desirable to install dependencies for other binaries related to the executable. For example, plugins provided by the project might have further dependencies, but because those plugins won't be linked directly to the executable, qt_deploy_runtime_dependencies() won't automatically discover them. The ADDITIONAL_EXECUTABLES, ADDITIONAL_LIBRARIES, and ADDITIONAL_MODULES options can be used to specify additional binaries whose dependencies should also be deployed (installing the named binaries themselves is still the project's responsibility). The naming of these keywords follows CMake's conventions, so Qt plugins would be specified using ADDITIONAL_MODULES. Each value should be a path relative to the base install location. The values can use generator expressions, same as with the EXECUTABLE option. Specifying raw target names not wrapped in a generator epxression like <TARGET_FILE_NAME:> is not supported.

When installing a Windows application, it is common to need a qt.conf file when following CMake's default install directory structure. If the GENERATE_QT_CONF option is given, an appropriate qt.conf file will be written to the same directory as the executable. The paths in that qt.conf file will be based on the CMAKE_INSTALL_xxxDIR variables, whose defaults are provided by CMake's GNUInstallDirs module.

You can override some of those defaults with the parameters in the following table, all of which are expected to be relative to the base install location.

A qt.conf file is always written if executable is a macOS app bundle, regardless of whether or not GENERATE_QT_CONF is provided. The ..._DIR options are also ignored in that case, since the directory layout of an app bundle is dictated by Apple's requirements.

More verbose output about the deployment steps can be enabled by providing the VERBOSE option. Alternatively, the QT_ENABLE_VERBOSE_DEPLOYMENT variable can be set in the project before the first find_package(Qt6) call to make deployment output verbose by default.

The qt_deploy_runtime_dependencies() command overwrites existing files by default (some warnings may still be issued). Use the NO_OVERWRITE option to prevent overwriting existing files. Note that this option currently only affects macOS and Windows deployments.

By default, if executable is a macOS app bundle, only Qt plugins and Qt libraries that comply with Apple's app store requirements are deployed. The NO_APP_STORE_COMPLIANCE option can be given to disable that constraint.

On platforms other than macOS, Qt translations are automatically deployed. To inhibit this behavior, specify NO_TRANSLATIONS. Use qt_deploy_translations() to deploy translations in a customized way.

For Windows desktop applications, the required runtime files for the compiler are also installed by default. To prevent this, specify NO_COMPILER_RUNTIME.

Since Qt 6.7, you can use DEPLOY_TOOL_OPTIONS to pass additional options to the underlying deployment tool. This only has an effect if the underlying deployment tool is either macdeployqt or windeployqt.

On Linux, deploying runtime dependencies is based on CMake's file(GET_RUNTIME_DEPENDENCIES) command. The options PRE_INCLUDE_REGEXES, PRE_EXCLUDE_REGEXES, POST_INCLUDE_REGEXES, POST_EXCLUDE_REGEXES, POST_INCLUDE_FILES, and POST_EXCLUDE_FILES are only meaningful in this context and are forwarded unaltered to file(GET_RUNTIME_DEPENDENCIES). See the documentation of that command for details.

On Linux, runtime dependencies that are located in system library directories are not deployed by default. If POST_EXCLUDE_REGEXES is specified, this automatic exclusion is not performed.

The default value of POST_EXCLUDE_REGEXES is constructed from the value of QT_DEPLOY_IGNORED_LIB_DIRS.

Example

The following example shows how to deploy an application 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

The following example shows how to use the DEPLOY_TOOL_OPTIONS parameter to pass different options to macdeployqt and 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
)")