1// Copyright (C) 2021 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
5\page qt-deploy-runtime-dependencies.html
6\ingroup cmake-commands-qtcore
8\title qt_deploy_runtime_dependencies
9\keyword qt6_deploy_runtime_dependencies
11\summary {Deploy Qt plugins, Qt and non-Qt libraries needed by an executable.}
13\include cmake-find-package-core.qdocinc
15Unlike most other CMake commands provided by Qt, \c{qt_deploy_runtime_dependencies()}
16can only be called from a deployment script. It cannot be called directly by the
17project during the configure stage.
20\note This command does not usually need to be called directly. It is used
21 internally by other higher level commands, but projects wishing to
22 implement more customized deployment logic may find it useful.
27qt_deploy_runtime_dependencies(
29 [ADDITIONAL_EXECUTABLES files...]
30 [ADDITIONAL_LIBRARIES files...]
31 [ADDITIONAL_MODULES files...]
34 [LIBEXEC_DIR libexec_dir]
36 [PLUGINS_DIR plugins_dir]
40 [NO_APP_STORE_COMPLIANCE]
44 [PRE_INCLUDE_REGEXES regexes...]
45 [PRE_EXCLUDE_REGEXES regexes...]
46 [POST_INCLUDE_REGEXES regexes...]
47 [POST_EXCLUDE_REGEXES regexes...]
48 [POST_INCLUDE_FILES files...]
49 [POST_EXCLUDE_FILES files...]
55When installing an application, it may be desirable to also install the
56libraries and plugins it depends on. When the application is a macOS app bundle
57or a Windows executable, \c{qt_deploy_runtime_dependencies()} can be called
58from an install-time script to deploy those dependencies. It will install
59non-system Qt libraries plus an appropriate set of Qt plugins.
61On Linux, the command will deploy additional libraries, beyond just those
62related to Qt, that are included with the project. However, when executed on
63macOS or Windows, the command will use either \c macdeployqt or \c windeployqt,
64which will only deploy libraries that are specific to Qt.
66This command only considers runtime dependencies for which linking
67relationships exist in the underlying binaries. It does not deploy QML modules,
68see \l{qt6_deploy_qml_imports}{qt_deploy_qml_imports()} for that.
72The \c{EXECUTABLE} option must be provided.
74The \c{executable} argument should be the path to the executable file in the
75build directory. For example, \c{${CMAKE_CURRENT_BINARY_DIR}/MyApp.exe}, or more
76dynamically \c{$<TARGET_FILE:MyApp>}. Specifying raw target names not wrapped in
77a generator expression like \c{<TARGET_FILE:>} is not supported.
79For macOS app bundles, the \c{executable} argument should be a path to the
80bundle directory, relative to the base install location.
81For example \c{MyApp.app}, or more dynamically
82\c{$<TARGET_FILE_NAME:MyApp>.app}.
83Specifying raw target names not wrapped in a generator epxression like
84\c{<TARGET_FILE_NAME:>} is not supported.
86It may also be desirable to install dependencies for other binaries related to
87the \c{executable}. For example, plugins provided by the project might have
88further dependencies, but because those plugins won't be linked directly to the
89executable, \c{qt_deploy_runtime_dependencies()} won't automatically discover
90them. The \c{ADDITIONAL_EXECUTABLES}, \c{ADDITIONAL_LIBRARIES}, and
91\c{ADDITIONAL_MODULES} options can be used to specify additional binaries
92whose dependencies should also be deployed (installing the named binaries
93themselves is still the project's responsibility). The naming of these keywords
94follows CMake's conventions, so Qt plugins would be specified using
95\c{ADDITIONAL_MODULES}.
96Each value should be a path relative to the base install location. The values
97can use generator expressions, same as with the \c{EXECUTABLE} option.
98Specifying raw target names not wrapped in a generator epxression like
99\c{<TARGET_FILE_NAME:>} is not supported.
101When installing a Windows application, it is common to need a
102\l{Using qt.conf}{qt.conf} file when following CMake's default install
103directory structure. If the \c{GENERATE_QT_CONF} option is given, an appropriate
104\c{qt.conf} file will be written to the same directory as the \c{executable}.
105The paths in that \c{qt.conf} file will be based on the \c{CMAKE_INSTALL_xxxDIR}
106variables, whose defaults are provided by CMake's \l{GNUInstallDirs} module.
108You can override some of those defaults with the parameters in the following
109table, all of which are expected to be relative to the base install location.
114 \li affected variable
118 \li \l QT_DEPLOY_BIN_DIR
122 \li \l QT_DEPLOY_LIBEXEC_DIR
126 \li \l QT_DEPLOY_LIB_DIR
130 \li \l QT_DEPLOY_PLUGINS_DIR
134 \li \l QT_DEPLOY_QML_DIR
138A \c{qt.conf} file is always written if \c{executable} is a macOS app bundle,
139regardless of whether or not \c{GENERATE_QT_CONF} is provided. The \c{..._DIR}
140options are also ignored in that case, since the directory layout of an app
141bundle is dictated by Apple's requirements.
143More verbose output about the deployment steps can be enabled by providing the
144\c{VERBOSE} option. Alternatively, the \l{QT_ENABLE_VERBOSE_DEPLOYMENT}
145variable can be set in the project before the first \c{find_package(Qt6)} call
146to make deployment output verbose by default.
148The \c{qt_deploy_runtime_dependencies()} command overwrites existing files by
149default (some warnings may still be issued). Use the \c{NO_OVERWRITE} option
150to prevent overwriting existing files. Note that this option currently only
151affects macOS and Windows deployments.
153By default, if \c{executable} is a macOS app bundle, only Qt plugins and Qt
154libraries that comply with Apple's app store requirements are deployed. The
155\c{NO_APP_STORE_COMPLIANCE} option can be given to disable that constraint.
157On platforms other than macOS, Qt translations are automatically deployed. To
158inhibit this behavior, specify \c{NO_TRANSLATIONS}. Use
159\l{qt6_deploy_translations}{qt_deploy_translations()} to deploy translations
162For Windows desktop applications, the required runtime files for the compiler
163are also installed by default. To prevent this, specify \c{NO_COMPILER_RUNTIME}.
165Since Qt 6.7, you can use \c{DEPLOY_TOOL_OPTIONS} to pass additional options to
166the underlying deployment tool. This only has an effect if the underlying
167deployment tool is either macdeployqt or windeployqt.
169On Linux, deploying runtime dependencies is based on CMake's
170\c{file(GET_RUNTIME_DEPENDENCIES)} command. The options \c{PRE_INCLUDE_REGEXES},
171\c{PRE_EXCLUDE_REGEXES}, \c{POST_INCLUDE_REGEXES}, \c{POST_EXCLUDE_REGEXES},
172\c{POST_INCLUDE_FILES}, and \c{POST_EXCLUDE_FILES} are only meaningful in this
173context and are forwarded unaltered to \c{file(GET_RUNTIME_DEPENDENCIES)}. See
174the documentation of that command for details.
176On Linux, runtime dependencies that are located in system library directories
177are not deployed by default. If \c{POST_EXCLUDE_REGEXES} is specified, this
178automatic exclusion is not performed.
180The default value of \c{POST_EXCLUDE_REGEXES} is constructed from the value of
181\l{QT_DEPLOY_IGNORED_LIB_DIRS}.
183\sa {qt6_generate_deploy_app_script}{qt_generate_deploy_app_script()},
184 {qt6_deploy_qt_conf}{qt_deploy_qt_conf()},
185 {qt6_deploy_qml_imports}{qt_deploy_qml_imports()}
189The following example shows how to deploy an application \c{MyApp}.
191\include cmake-deploy-runtime-dependencies.qdocinc
193The following example shows how to use the \c{DEPLOY_TOOL_OPTIONS} parameter to
194pass different options to macdeployqt and windeployqt.
196\include cmake-deploy-runtime-dependencies-deploy-tool-options.qdocinc