// 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
\target qt6_generate_deploy_app_script

\summary {Generate a deployment script for an application.}

\include cmake-find-package-core.qdocinc

\cmakecommandsince 6.3
\preliminarycmakecommand
\note This command is currently only supported on Windows and macOS.

\section1 Synopsis

\badcode
qt_generate_deploy_app_script(
    TARGET target
    FILENAME_VARIABLE var_name
    [NO_TRANSLATIONS]
    [NO_UNSUPPORTED_PLATFORM_ERROR]
)
\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{FILENAME_VARIABLE} 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{qt6_deploy_translations}{qt_deploy_translations} to deploy translations in a
customized way.

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}.

\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

\badcode
cmake_minimum_required(VERSION 3.16...3.22)
project(MyThings)

find_package(Qt6 REQUIRED COMPONENTS Core)
qt_standard_project_setup()

qt_add_executable(MyApp main.cpp)

install(TARGETS MyApp
    BUNDLE  DESTINATION .
    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
)

qt_generate_deploy_app_script(
    TARGET MyApp
    FILENAME_VARIABLE deploy_script
    NO_UNSUPPORTED_PLATFORM_ERROR
)
install(SCRIPT ${deploy_script})
\endcode
*/