diff options
Diffstat (limited to 'src/corelib/doc/src/cmake/qt_deploy_runtime_dependencies.qdoc')
-rw-r--r-- | src/corelib/doc/src/cmake/qt_deploy_runtime_dependencies.qdoc | 198 |
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 + +*/ |