qt_deploy_runtime_dependencies.qdoc

Go to the documentation of this file.

// Copyright (C) 2021 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
/*!
\page qt-deploy-runtime-dependencies.html
\ingroup cmake-commands-qtcore
 
\title qt_deploy_runtime_dependencies
\keyword qt_deploy_runtime_dependencies()
 
\summary {Deploy Qt plugins, Qt and non-Qt libraries needed by an executable.}
 
\include cmake-find-package-core.qdocinc
 
Unlike most other CMake commands provided by Qt, \c{qt_deploy_runtime_dependencies()}
can only be called from a deployment script. It cannot be called directly by the
project during the configure stage.
 
\cmakecommandsince 6.3
\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.
 
\section1 Synopsis
 
\badcode
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...]
)
\endcode
 
\section1 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, \c{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 \c macdeployqt or \c windeployqt.
\c macdeployqt only deploys libraries that are specific to Qt. \c windeployqt
additionally deploys the non-Qt libraries that the deployed binaries link
against, if those libraries are located in the Qt binary directory.
 
This command only considers runtime dependencies for which linking
relationships exist in the underlying binaries. It does not deploy QML modules,
see \l qt_deploy_qml_imports() for that.
 
\section1 Arguments
 
The \c{EXECUTABLE} option must be provided.
 
The \c{executable} argument should be the path to the executable file in the
build directory. For example, \c{${CMAKE_CURRENT_BINARY_DIR}/MyApp.exe}, or more
dynamically \c{$<TARGET_FILE:MyApp>}. Specifying raw target names not wrapped in
a generator expression like \c{$<TARGET_FILE:>} is not supported.
 
For macOS app bundles, the \c{executable} argument should be a path to the
bundle directory, relative to the base install location.
For example \c{MyApp.app}, or more dynamically
\c{$<TARGET_FILE_NAME:MyApp>.app}.
Specifying raw target names not wrapped in a generator expression like
\c{$<TARGET_FILE_NAME:>} is not supported.
 
It may also be desirable to install dependencies for other binaries related to
the \c{executable}. For example, plugins provided by the project might have
further dependencies, but because those plugins won't be linked directly to the
executable, \c{qt_deploy_runtime_dependencies()} won't automatically discover
them. The \c{ADDITIONAL_EXECUTABLES}, \c{ADDITIONAL_LIBRARIES}, and
\c{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
\c{ADDITIONAL_MODULES}.
Each value should be a path relative to the base install location. The values
can use generator expressions, same as with the \c{EXECUTABLE} option.
Specifying raw target names not wrapped in a generator expression like
\c{$<TARGET_FILE_NAME:>} is not supported.
 
When installing a Windows application, it is common to need a
\l{Using qt.conf}{qt.conf} file when following CMake's default install
directory structure. If the \c{GENERATE_QT_CONF} option is given, an appropriate
\c{qt.conf} file will be written to the same directory as the \c{executable}.
The paths in that \c{qt.conf} file will be based on the \c{CMAKE_INSTALL_xxxDIR}
variables, whose defaults are provided by CMake's \l{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.
 
\table
\header
    \li parameter
    \li affected variable
    \li notes
\row
    \li \c BIN_DIR
    \li \l QT_DEPLOY_BIN_DIR
    \li
\row
    \li \c LIBEXEC_DIR
    \li \l QT_DEPLOY_LIBEXEC_DIR
    \li since Qt 6.7
\row
    \li \c LIB_DIR
    \li \l QT_DEPLOY_LIB_DIR
    \li
\row
    \li \c PLUGINS_DIR
    \li \l QT_DEPLOY_PLUGINS_DIR
    \li
\row
    \li \c QML_DIR
    \li \l QT_DEPLOY_QML_DIR
    \li
\endtable
 
No \c{qt.conf} file is written if \c{executable} is a macOS app bundle, and
both \c{GENERATE_QT_CONF} and the \c{..._DIR} options are ignored in that
case. The directory layout of an app bundle is dictated by Apple's
requirements, and Qt finds libraries, plugins and resources at those
conventional locations without a \c{qt.conf}.
 
More verbose output about the deployment steps can be enabled by providing the
\c{VERBOSE} option. Alternatively, the \l{QT_ENABLE_VERBOSE_DEPLOYMENT}
variable can be set in the project before the first \c{find_package(Qt6)} call
to make deployment output verbose by default.
 
The \c{qt_deploy_runtime_dependencies()} command overwrites existing files by
default (some warnings may still be issued). Use the \c{NO_OVERWRITE} option
to prevent overwriting existing files. Note that this option currently only
affects macOS and Windows deployments.
 
By default, if \c{executable} is a macOS app bundle, only Qt plugins and Qt
libraries that comply with Apple's app store requirements are deployed. The
\c{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 \c{NO_TRANSLATIONS}. Use
\l 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 \c{NO_COMPILER_RUNTIME}.
 
Since Qt 6.7, you can use \c{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.
 
\note When this command is called from the \c {CONTENT} of
\l qt_generate_deploy_script(), the values of \c{DEPLOY_TOOL_OPTIONS} should
be wrapped into a single quoted string so that whitespace is preserved in the
generated deployment script. Additionally, each value that contains a space,
like a code signing identity, should be wrapped in backslash escaped quotes.
 
On Linux, deploying runtime dependencies is based on CMake's
\c{file(GET_RUNTIME_DEPENDENCIES)} command. The options \c{PRE_INCLUDE_REGEXES},
\c{PRE_EXCLUDE_REGEXES}, \c{POST_INCLUDE_REGEXES}, \c{POST_EXCLUDE_REGEXES},
\c{POST_INCLUDE_FILES}, and \c{POST_EXCLUDE_FILES} are only meaningful in this
context and are forwarded unaltered to \c{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 \c{POST_EXCLUDE_REGEXES} is specified, this
automatic exclusion is not performed.
 
The default value of \c{POST_EXCLUDE_REGEXES} is constructed from the value of
\l{QT_DEPLOY_IGNORED_LIB_DIRS}.
 
\sa qt_generate_deploy_app_script(),
    qt_deploy_qt_conf(),
    qt_deploy_qml_imports(),
    {QTP0007}
 
\section1 Controlling deployment of Qt plugins
 
Qt plugins are automatically deployed into \l QT_DEPLOY_PLUGINS_DIR.
 
You can turn off plugin deployment with the \c NO_PLUGINS argument.
 
You can include all plugins of a specific type with the \c INCLUDE_PLUGIN_TYPES
argument. You can exclude all plugins of a specific type with the \c
EXCLUDE_PLUGIN_TYPES argument. Both arguments take plugin types, e.g. \c
imageformats.
 
You can include or exclude specific plugins with the arguments \c
INCLUDE_PLUGINS and \c EXCLUDE_PLUGINS. Both arguments take plugin names, for
example \c qjpeg.
 
\note Plugin names must not be confused with plugin targets. For example, the \c
Qt6::QJpegPlugin target's plugin name is \c qjpeg.
 
\note The arguments \c EXCLUDE_PLUGINS, \c EXCLUDE_PLUGIN_TYPES, \c
INCLUDE_PLUGINS, and \c INCLUDE_PLUGIN_TYPES only work on Windows and Linux.
 
\section1 Example
 
The following example shows how to deploy an application \c{MyApp}.
 
\include cmake-deploy-runtime-dependencies.qdocinc
 
The following example shows how to use the \c{DEPLOY_TOOL_OPTIONS} parameter to
pass different options to macdeployqt and windeployqt.
 
\include cmake-deploy-runtime-dependencies-deploy-tool-options.qdocinc
 
*/