qt_deploy_runtime_dependencies | Qt Core 6.4.1

- Qt 6.4
- Qt Core
- CMake Commands in Qt6 Core
- qt_deploy_runtime_dependencies
- Qt 6.4.1 Reference Documentation

# 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.

Note: This command is in technology preview and may change in future releases.

Note: This command does not usually need to be called directly. It is used internally by other higher level commands, but projects wishing to implement more customized deployment logic may find it useful.

## Synopsis

     qt_deploy_runtime_dependencies(
         EXECUTABLE executable
         [ADDITIONAL_EXECUTABLES files...]
         [ADDITIONAL_LIBRARIES files...]
         [ADDITIONAL_MODULES files...]
         [GENERATE_QT_CONF]
         [BIN_DIR bin_dir]
         [LIB_DIR lib_dir]
         [PLUGINS_DIR plugins_dir]
         [QML_DIR qml_dir]
         [VERBOSE]
         [NO_OVERWRITE]
         [NO_APP_STORE_COMPLIANCE]
     )

## 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 libraries (both Qt and those provided by the project), plus an appropriate set of Qt plugins.

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 a path to the executable file, relative to the base install location. For example, `bin/MyApp.exe`, or more dynamically `\${QT_DEPLOY_BIN_DIR}/$<TARGET_FILE_NAME:MyApp>`. Specifying raw target names not wrapped in a generator epxression like `<TARGET_FILE_NAME:>` 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 `BIN_DIR`, `LIB_DIR`, `PLUGINS_DIR`, and `QML_DIR` options, 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.

## Example

     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>")

     # The following script must only be executed at install time
     set(deploy_script "${CMAKE_CURRENT_BINARY_DIR}/deploy_MyApp.cmake")

     file(GENERATE OUTPUT ${deploy_script} CONTENT "
     # Including the file pointed to by QT_DEPLOY_SUPPORT ensures the generated
     # deployment script has access to qt_deploy_runtime_dependencies()
     include(\"${QT_DEPLOY_SUPPORT}\")
     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

See also qt_generate_deploy_app_script(), qt_deploy_qt_conf(), and qt_deploy_qml_imports().