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

/*!
\page qt-set-harmonyos-app-metadata.html
\ingroup cmake-commands-qtcore

\title qt_set_harmonyos_app_metadata
\keyword qt_set_harmonyos_app_metadata()

\summary {Sets HarmonyOS application-level metadata on the target.}

\include cmake-find-package-core.qdocinc

\cmakecommandsince 6.12
\preliminarycmakecommand
\cmakecommandharmonyosonly

\section1 Synopsis

\badcode
qt_set_harmonyos_app_metadata(target
    [VENDOR <string>]
    [VERSION_CODE <integer>]
    [VERSION_NAME <string>]
    [LABEL <label>]
    [ICON <icon>]
    [COMPATIBLE_SDK_VERSION <string>]
    [TARGET_SDK_VERSION <string>]
    [COMPILE_SDK_VERSION <string>]
)
\endcode

\versionlessCMakeCommandsNote qt6_set_harmonyos_app_metadata()

\section1 Description

The command sets application-level metadata for the HarmonyOS \c {target}
executable. The values are conceptually app-scoped (one application maps to one
bundle) and are baked into \c {AppScope/app.json5} and
\c {entry/build-profile.json5} when the HAP package is built. Module-scoped
metadata, such as the description or orientation, is set with
\l qt_set_harmonyos_module_metadata()
instead.

\section1 Arguments

\c VENDOR is the name of the application vendor.

\c VERSION_CODE is the integer version code of the application. It is an
internal version number that is not shown to the user.

\c VERSION_NAME is the human-readable version string of the application, for
example \c {1.0.0}.

\c LABEL is the application name shown to the user. It accepts either a literal
string or a \c {$string:<name>} resource reference that resolves to a localized
string from the application's resource files.

\c ICON is the application icon. It accepts either a path to an image file or a
\c {$media:<name>} resource reference. A relative path is resolved against the
\c CMAKE_CURRENT_SOURCE_DIR of the calling directory. When a file path is given,
the image is copied into the bundle's media resources and a \c {$media:}
reference is generated for it.

\c COMPATIBLE_SDK_VERSION, \c TARGET_SDK_VERSION, and \c COMPILE_SDK_VERSION set
the corresponding SDK version fields in \c {entry/build-profile.json5}. The
values are substituted verbatim, so they must use the format expected by the
HarmonyOS toolchain, for example \c {COMPATIBLE_SDK_VERSION "5.0.0(12)"} and
\c {TARGET_SDK_VERSION "14"}.

An option that is not specified is not written to the manifest. The
corresponding field then keeps the value defined by the package template, so
the effective default for each option is whatever that template provides. See
\l{cmake-target-property-QT_HARMONYOS_PACKAGE_SOURCE_DIR}
{QT_HARMONYOS_PACKAGE_SOURCE_DIR} for how to inspect or replace that template.

\section1 Example

\snippet cmake-macros/examples.cmake qt_set_harmonyos_app_metadata

\sa qt_set_harmonyos_module_metadata(),
    {Qt for HarmonyOS CMake API}
*/
