qt_generate_deploy_app_script.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-generate-deploy-app-script.html
\ingroup cmake-commands-qtcore
 
\title qt_generate_deploy_app_script
\keyword qt_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]
    [NO_APP_STORE_COMPLIANCE]                     # since Qt 6.13
    [NO_PLUGINS]                                  # since Qt 6.10
    [EXCLUDE_PLUGIN_TYPES type_or_target...]      # since Qt 6.10
    [INCLUDE_PLUGIN_TYPES type_or_target...]      # since Qt 6.10
    [EXCLUDE_PLUGINS name...]                     # since Qt 6.10
    [INCLUDE_PLUGINS name...]                     # since Qt 6.10
    [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 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 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}.
 
For macOS app bundles, only Qt plugins and Qt libraries that comply with
Apple's app store requirements are deployed by default. Since Qt 6.13, the
\c{NO_APP_STORE_COMPLIANCE} option can be given to disable that constraint.
 
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 A value that contains whitespace, like a code signing identity, only reaches
the deployment tool unchanged if \l {QTP0007} is set to \c NEW. With the \c OLD
behavior, such a value is written to the generated script unquoted and gets split
at whitespace, which projects used to work around by adding another level of
quoting. Remove that extra quoting when setting the policy to \c NEW.
 
\note The version-less \c qt_generate_deploy_app_script() forwards its arguments
through either a function or a macro depending on the value of \l {QTP0008}.
With the \c OLD behavior a value that contains a backslash or a \c{${var}}
reference is evaluated at macro expansion time, so a regex like
\c{foo\\.dylib} loses a level of escaping.
This affects \c{DEPLOY_TOOL_OPTIONS} and the regex and file list arguments.
Calling \c qt6_generate_deploy_app_script() directly avoids this issue.
 
For deploying a QML application, use
\l qt_generate_deploy_qml_app_script()
instead.
 
For generating a custom deployment script, use
\l 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 qt_deploy_runtime_dependencies().
 
The options \c EXCLUDE_PLUGINS, \c EXCLUDE_PLUGIN_TYPES, \c INCLUDE_PLUGINS, and
\c INCLUDE_PLUGIN_TYPES are used to select Qt plugins. See
\l qt_deploy_runtime_dependencies() for their
documentation.
 
Static Qt builds link plugins into the application binary instead of deploying them as
separate files. In that case, \c EXCLUDE_PLUGINS and \c EXCLUDE_PLUGIN_TYPES exclude the
plugins from being linked into the binary.
 
You can turn off plugin deployment altogether with the \c NO_PLUGINS option.
 
\sa qt_standard_project_setup(),
    qt_generate_deploy_script(),
    qt_generate_deploy_qml_app_script(),
    {QTP0007},
    {QTP0008}
 
\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
 
*/