// Copyright (C) 2021 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
\page cmake-qt6-am-add-systemui-wrapper.html
\ingroup cmake-macros-qtapplicationmanager

\title qt_am_add_systemui_wrapper
\keyword qt6_am_add_systemui_wrapper

\brief Creates a basic wrapper script to run a System UI using the appman binary.

\preliminarycmakecommand

\section1 Synopsis

\badcode
qt_am_add_systemui_wrapper(
    target
    [EXECUTABLE appman-executable]
    [MAIN_QML_FILE main.qml]
    [CONFIG_YAML config.yaml ...]
    [EXTRA_ARGS ...]
    [EXTRA_FILES ...]
    [EXTRA_FILES_GLOB ...]
    [INSTALL_DIR install-dir]
)
\endcode

\versionlessCMakeCommandsNote qt6_am_add_systemui_wrapper()

\section1 Description

Generates a \c .bat (Windows) or \c .sh (macOS, Linux) wrapper in the build directory to easily run
your QML based System UI referenced by \c target on the desktop or within Qt Creator. It will also
automatically copy the required files from the source to the build directory: these are the \c
MAIN_QML_FILE, any \c CONFIG_YAML files as well as all \c EXTRA_FILES.

Any directory in \c EXTRA_FILES will be recursively copied. By default the file types are limited
to \c {*.qml *.js qmldir *.json *.yaml *.png *.jpg *.svg}, but you can supply a custom glob pattern
via \c EXTRA_FILES_GLOB (see CMake's \c file(GLOB) command for details).

If you also want this command to automatically generate installation rules for all files, you can
specify the destination directory via \c INSTALL_DIR. By default, no installation rule is created.

If you want to use a custom build of the application manager, you can do that by using \c
EXECUTABLE. Otherwise, the \c appman binary of the current Qt build will be used.

All \c EXTRA_ARGS will be appended to the command line when running the \c EXECUTABLE from the
wrapper script.

For very simple setups, specifying just the \c MAIN_QML_FILE is enough. If you already have an \c
am-config.yaml, you can reference that via \c CONFIG_YAML. In case your main.qml is already set in
the YAML config file, you do not need to specify it here again.

\warning Please note that this command will not scale when your project is becoming more
sophisticated over time. It is only meant to help you get started without diving too deep into
CMake.

\section1 Examples

Here is a snippet showing how this function is used:

\badcode
qt_am_add_systemui_wrapper(minidesk
    INSTALL_DIR "${INSTALL_EXAMPLEDIR}"
    CONFIG_YAML am-config.yaml
    EXTRA_FILES apps system-ui
    EXTRA_ARGS --verbose
)
\endcode

*/

/*!
\page cmake-qt6_am_create_installable_package.html
\ingroup cmake-macros-qtapplicationmanager

\title qt_am_create_installable_package
\keyword qt6_am_create_installable_package

\brief Uses the appman-packager tool to package applications.

\preliminarycmakecommand

\section1 Synopsis

\badcode
qt_am_create_installable_package(
    target
    FILES ...
    [OUTPUT_DIRECTORY output_dir]
    [INSTALL_DIRECTORY install_dir]
    [PACKAGE_DIRECTORY package_dir]
    [PACKAGE_NAME package_name]
    [DEPENDENCIES ...]
)
\endcode

\versionlessCMakeCommandsNote qt6_am_create_installable_package()

\section1 Description

Adds a custom \c target that, when executed, uses the \l{Packager}{appman-packager} tool to create
a package for the application found in \c PACKAGE_DIRECTORY. The result is written to \c OUTPUT_DIRECTORY,
which defaults to ${CMAKE_CURRENT_BINARY_DIR}. The \c PACKAGE_NAME is used as the name of the package
and defaults to \c ${target}.ampkg.

The \c FILES argument is a list of files that will be copied to the package directory and needs
to at least contain an \c info.yaml file that describes the package.

Using the \c DEPENDENCIES argument, you can specify a list of targets this package depends on.

The \c INSTALL_DIRECTORY argument can be used to specify a directory where the package will be installed into.

\note This function will serve as an anchor for the application manager's QtCreator integration
      to discover the available packages in a System UI.

\section1 Examples

Here is a snippet from the \l applicationmanager/package-installation example, showing how this
function is used to create a simple installable package:

\quotefromfile applicationmanager/package-installation/CMakeLists.txt
\skipto qt_am_create_installable_package(installable-red
\printuntil )

An installable package using a compiled QML module looks like this:

\quotefromfile applicationmanager/package-installation/CMakeLists.txt
\skipto qt_add_qml_module(installable-pink-module
\printto qt_am_create_installable_package(installable-pink
\printuntil )

*/

/*!
\page cmake-qt6_am_create_builtin_package.html
\ingroup cmake-macros-qtapplicationmanager

\title qt_am_create_builtin_package
\keyword qt6_am_create_builtin_package

\brief Marks a directory containing a package as built-in.

\preliminarycmakecommand

\section1 Synopsis

\badcode
qt_am_create_builtin_package(
    target
    FILES ...
    [OUTPUT_DIRECTORY output_dir]
    [INSTALL_DIRECTORY install_dir]
    [DEPENDENCIES ...]
)
\endcode

\versionlessCMakeCommandsNote qt6_am_create_builtin_package()

\section1 Description

Adds a custom \c target that acts as a built-in package for the application-manager.
The supplied \c FILES need to contain at least an info.yaml file that describes the package.

If \c OUTPUT_DIRECTORY is specified, all files specified in \c FILES will be copied to this folder.

Using the \c DEPENDENCIES argument, you can specify a list of targets this package depends on.

The \c INSTALL_DIRECTORY argument can be used to specify a directory where all files specified in \c FILES
and all dependencies will be installed into.

See also \l qt_am_create_installable_package for packages which can be installed and uninstalled.

\note This function will serve as an anchor for the application manager's QtCreator integration
      to discover the available packages in a System UI.

\section1 Examples

Here is a snippet from the \l applicationmanager/hello-world example, showing how this
function is used to create a simple package:
\quotefromfile applicationmanager/hello-world/CMakeLists.txt
\skipto qt_am_create_builtin_package(hello-world.blue
\printuntil )

A builtin package using a compiled QML module looks like this:

\quotefromfile applicationmanager/application-features/apps/Twins/CMakeLists.txt
\skipto qt_add_qml_module
\printto qt_am_create_builtin_package
\printuntil )

*/