/****************************************************************************
**
** Copyright (C) 2021 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
\page qt_deploy_runtime_dependencies.html
\ingroup cmake-commands-qtcore

\title qt_deploy_runtime_dependencies
\target qt_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.

\preliminarycmakecommand

\section1 Synopsis

\badcode
qt_deploy_runtime_dependencies(
    EXECUTABLE executable
    [MACOS_BUNDLE]
    [ADDITIONAL_EXECUTABLES files...]
    [ADDITIONAL_LIBRARIES files...]
    [ADDITIONAL_MODULES files...]
    [GENERATE_QT_CONF]
    [BIN_DIR bin_dir]
    [LIB_DIR lib_dir]
    [PLUGINS_DIR plugins_dir]
    [QML_DIR qml_dir]
    [VERBOSE]
    [NO_OVERWRITE]
    [NO_APP_STORE_COMPLIANCE]
)
\endcode

\section1 Description

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

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 libraries (both Qt and those provided by the project), plus an
appropriate set of Qt plugins.

This command only considers runtime dependencies for which linking
relationships exist in the underlying binaries. It does not deploy QML modules,
see \l{qt_deploy_qml_imports()} for that.

\section1 Arguments

The \c{EXECUTABLE} option must be provided. The \c{executable} argument should
be the path relative to the base install location. For macOS app bundles, the
\c{MACOS_BUNDLE} option should be given and the \c{executable} argument should
be the path to the executable in the \c{<bundle-name>.app/Contents/MacOS}
directory.

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

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 \c{BIN_DIR}, \c{LIB_DIR},
\c{PLUGINS_DIR}, and \c{QML_DIR} options, all of which are expected to be
relative to the base install location. 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.

\sa {qt6_generate_deploy_app_script}{qt_generate_deploy_app_script()},
    qt_deploy_qt_conf(), qt_deploy_qml_imports()

\section1 Example

\include cmake-deploy-runtime-dependencies.qdocinc
*/