// 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

*/