1 files changed, 198 insertions, 0 deletions
diff --git a/src/corelib/doc/src/cmake/qt_deploy_runtime_dependencies.qdoc b/src/corelib/doc/src/cmake/qt_deploy_runtime_dependencies.qdoc
new file mode 100644
index 0000000000..f64960492a
--- /dev/null
+++ b/src/corelib/doc/src/cmake/qt_deploy_runtime_dependencies.qdoc
@@ -0,0 +1,198 @@
+// 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 qt6_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_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,
+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 \l{qt6_deploy_qml_imports}{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 epxression 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 epxression 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
+
+A \c{qt.conf} file is always written if \c{executable} is a macOS app bundle,
+regardless of whether or not \c{GENERATE_QT_CONF} is provided. The \c{..._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
+\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{qt6_deploy_translations}{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.
+
+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 {qt6_generate_deploy_app_script}{qt_generate_deploy_app_script()},
+    {qt6_deploy_qt_conf}{qt_deploy_qt_conf()},
+    {qt6_deploy_qml_imports}{qt_deploy_qml_imports()}
+
+\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
+
+*/