diff options
Diffstat (limited to 'src/corelib/doc/src/cmake/qt_generate_deploy_app_script.qdoc')
-rw-r--r-- | src/corelib/doc/src/cmake/qt_generate_deploy_app_script.qdoc | 110 |
1 files changed, 110 insertions, 0 deletions
diff --git a/src/corelib/doc/src/cmake/qt_generate_deploy_app_script.qdoc b/src/corelib/doc/src/cmake/qt_generate_deploy_app_script.qdoc new file mode 100644 index 0000000000..31d9e4384b --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_generate_deploy_app_script.qdoc @@ -0,0 +1,110 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-generate-deploy-app-script.html +\ingroup cmake-commands-qtcore + +\title qt_generate_deploy_app_script +\keyword qt6_generate_deploy_app_script + +\summary {Generate a deployment script for an application.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 6.3 +\note This command is currently only supported on Windows, macOS, and Linux. + +\section1 Synopsis + +\badcode +qt_generate_deploy_app_script( + TARGET target + OUTPUT_SCRIPT <var> + [NO_TRANSLATIONS] + [NO_COMPILER_RUNTIME] + [NO_UNSUPPORTED_PLATFORM_ERROR] + [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 + +\versionlessCMakeCommandsNote qt6_generate_deploy_app_script() + +\section1 Description + +Installing an executable target with \l{install(TARGETS)} only installs the +target's executable (except for macOS app bundles, which will copy the whole +bundle). You need to explicitly install any other libraries or plugins the +executable depends on yourself. \c{qt_generate_deploy_app_script()} is a +convenience command intended to simplify that process. It expects the +application to follow Qt's recommended install directory structure fairly +closely. That structure is based on CMake's default install layout, as +determined by \l{GNUInstallDirs} (except for macOS app bundles, which follow +Apple's requirements instead). + +The command generates a script whose name will be stored in the variable named +by the \c{OUTPUT_SCRIPT} option. That script is only written at CMake +generation time. It is intended to be used with the \l{install(SCRIPT)} command, +which should come after the application's target has been installed using +\l{install(TARGETS)}. + +The deployment script will call \l{qt6_deploy_runtime_dependencies} +{qt_deploy_runtime_dependencies()} with a suitable set of options for the standard +install layout. Currently, this is only implemented for +\list + \li macOS app bundles built on a macOS host, + \li Linux executables built on a Linux host, + \li and Windows executables built on a Windows host. +\endlist +Cross-building a Windows executable on a Linux host, as well as similar +scenarios, are not currently supported. +Calling \c{qt_generate_deploy_app_script()} in such a case will result +in a fatal error, unless the \c{NO_UNSUPPORTED_PLATFORM_ERROR} option is given. + +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. + +For deploying a QML application, use +\l{qt6_generate_deploy_qml_app_script}{qt_generate_deploy_qml_app_script()} +instead. + +For generating a custom deployment script, use +\l{qt6_generate_deploy_script}{qt_generate_deploy_script}. + +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} can be specified to control the deployment of runtime +dependencies. These options do not apply to all platforms and are forwarded +unmodified to \l{qt6_deploy_runtime_dependencies}{qt_deploy_runtime_dependencies()}. + +\sa {qt6_standard_project_setup}{qt_standard_project_setup()}, + {qt6_generate_deploy_script}{qt_generate_deploy_script()}, + {qt6_generate_deploy_qml_app_script}{qt_generate_deploy_qml_app_script()} + +\section1 Example + +The following example shows how to deploy an application \c{MyApp}. + +\include cmake-generate-deploy-app-script.qdocinc + +The following example shows how to use the \c{DEPLOY_TOOL_OPTIONS} parameter to +pass different options to macdeployqt and windeployqt. + +\include cmake-generate-deploy-app-script-deploy-tool-options.qdocinc + +*/ |