// Copyright (C) 2021 The Qt Company Ltd.
// Copyright (C) 2019 Luxoft Sweden AB
// Copyright (C) 2018 Pelagicore AG
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!

\page appman-packager.html
\title Packager
\brief A command-line utility to create and sign application packages.
\ingroup qtappman-tools

The \c{appman-packager} is a command-line utility that can be used by the developer to manage
installation packages. This utility can also be used as a signing and verification tool on an
app-store backend server. This tool is meant for use on the developer's desktop machine or
packaging server, but \b not on the target device.

Currently, the application manager supports unsigned packages, packages that are signed by the
developer only (development mode), and packages that are signed by a trusted app-store. The
\c{appman-packager} can create all these variations with the following commands:

Please also see the \l{Package Installation} documentation for more in-depth information about
package installations.

\table
\header
    \li Command
    \li Arguments
    \li Description
\row
    \li \span {style="white-space: nowrap"} {\c create-package}
    \li \c{<package>}

        \c{<source directory>}
    \li Creates a new package named \a package from the application in \a{source directory}. The
        directory needs to at least contain an \l{Manifest definition}{\c info.yaml} as well as an
        \c{icon.png} file.
        The tool will do a sanity-check on the \c info.yaml file before actually creating the
        package.
        All normal files and directories in the source directory will be copied into package. The
        only meta-data that is copied from the filesystem is the filename, and the user's
        eXecutable-bit. The following options are supported:

        \c{--verbose}: Dump the package's meta-data header and footer information to stdout.

        \c{--json}: Output in JSON format instead of YAML.

        \c{--extra-metadata} or \c{-m}: Add the given YAML snippet on the command line to the
            packages's \c extra meta-data (see also ApplicationInstaller::taskRequestingInstallationAcknowledge).

        \c{--extra-metadata-file} or \c{-M}: Add the given YAML file to the
            packages's \c extra meta-data (see also ApplicationInstaller::taskRequestingInstallationAcknowledge)

        \c{--extra-signed-metadata} or \c{-s}: Add the given YAML snippet on the command line to the
            packages's \c extraSigned meta-data (see also ApplicationInstaller::taskRequestingInstallationAcknowledge)

        \c{--extra-signed-metadata-file} or \c{-S}: Add the given YAML file to the
            packages's \c extra meta-data (see also ApplicationInstaller::taskRequestingInstallationAcknowledge)

        All of the extra-meta-data options are merged together, so all options can be used together
        and each option can also be given multiple times. The signed fields are added to the
        package's digest, so that they cannot be changed once the package has been signed. The
        normal fields can however be changed even after package signing: an example would be an
        appstore-server adding custom tags.
\row
    \li \span {style="white-space: nowrap"} {\c dev-sign-package}
    \li \c{<package>}

        \c{<signed-package>}

        \c{<certificate>}

        \c{<password>}
    \li Takes the input \c package, adds a developer signature and writes the output to \c signed-package.
        You need to supply a \c certificate in P12 format together with a \c password matching the
        certificate. The following options are supported:

        \c{--verbose}: Dump the package's meta-data header and footer information to stdout.

        \c{--json}: Output in JSON format instead of YAML.
\row
    \li \span {style="white-space: nowrap"} {\c dev-verify-package}
    \li \c{<package>}

        \c{<ca-certificates...>}
    \li Reads the input \c package and tries to verify the developer signature using the given \c
        ca-certificates. The following options are supported:

        \c{--verbose}: Print details regarding the verification to stdout.
\row
    \li \span {style="white-space: nowrap"} {\c store-sign-package}
    \li \c{<package>}

        \c{<signed-package>}

        \c{<certificate>}

        \c{<password>}

        \c{<device-id>}
    \li Takes the input \c package, adds a store signature and writes the output to \c signed-package.
        You need to supply a \c certificate in P12 format together with a \c password matching the
        certificate. If you don't leave the \c device-id empty, the resulting package can only be
        installed on this specific device. The following options are supported:

        \c{--verbose}: Dump the package's meta-data header and footer information to stdout.

        \c{--json}: Output in JSON format instead of YAML.
\row
    \li \span {style="white-space: nowrap"} {\c store-verify-package}
    \li \c{<package>}

        \c{<ca-certificates...>}

        \c{<device-id>}
    \li Reads the input \c package and tries to verify the store signature using the given \c
        ca-certificates. The following options are supported:

        \c{--json}: Output in JSON format instead of YAML.
\endtable

The \c{appman-packager} naturally supports the standard Unix \c{--help} command-line option.

*/