path: root/doc/manifest.qdoc

/****************************************************************************
**
** Copyright (C) 2020 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Application Manager.
**
** $QT_BEGIN_LICENSE:FDL-QTAS$
** Commercial License Usage
** Licensees holding valid commercial Qt Automotive Suite 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 manifest.html
\keyword info.yaml metadata manifest format
\title Manifest Definition

\note This page describes the current metadata format (\c am-package, version \c 1) that was
      introduced with the 5.14 release. For the old format - that is still supported - please see
      \l{Manifest Definition (pre 5.14)}{here}.

\section1 Overview

The package manifest or metadata file, \c info.yaml, is a \l {YAML syntax}
{YAML file following the same rules} as all the other YAML files used in the application manager.

While the application manager can support other file formats, such as XML, currently the only
metadata loader implemented is based on YAML.

All packages and their contained applications are described by a single \c info.yaml file, in the
root directory of the package.

\section1 Package Manifest

This is an example of a full-featured \c info.yaml file, that also shows how you can mix and match
classic YAML and JSON style in YAML 1.1 documents:

\badcode
%YAML 1.1
---
formatVersion: 1
formatType: am-package
---
id: 'com.pelagicore.radio'
icon: 'FM-Radio.png'
name:
  en: "FM Radio"
  de: "UKW-Rundfunk"

version: '1.2.1-alpha3'

applications:
- id: com.pelagicore.radio.app
  code: "radio.qml"

  runtime: qml
  runtimeParameters: { loadDummyData: true }

  capabilities:
  - cameraAccess
  - locationAccess
\endcode

The fields within the \c info.yaml file header (first YAML document) are as follows:

\table
\header
    \li Field Name
    \li Type
    \li Description
\row
    \li \c formatVersion
    \li int
    \li \e Required. Currently always \c 1.
\row
    \li \c formatType
    \li string
    \li \e Required. Always \c am-package.
\endtable

The fields within the \c info.yaml manifest data (second YAML document) are as follows:

\table
\header
    \li Field Name
    \li Type
    \li Description
\row
    \li \c id
    \li string
    \li The unique ID of the package represented as a string with a maximum length of 150
        characters. This ID can be used to look up information about the package in the
        \l{PackageManager}{PackageManager QML Type}. Since this ID is used in the file system, only
        a subset of the printable ASCII characters are allowed: \c{0-9}, \c{a-z}, \c{A-Z} as well as
        any of \c{!#$%&'`^~_+-=.,;()[]{}}. If you are building a larger system with third party
        applications, it is good practice to use reverse DNS notation for the package IDs to
        help keep track of your IDs in the long run. The helper function
        \l{PackageManager::validateDnsName} can help you to enforce this policy from the
        System UI.
\row
    \li \c icon
    \li string
    \li \e Required. The icon's file name. The file must be located in the same directory as
        \c info.yaml and can be in any image format that Qt supports.
\row
    \li \c name
    \target package-name-map
    \li object
    \li \e Required. An object containing language (\c string) to display name (\c string)
        mappings. The language identifiers need to adhere to the standard POSIX locale definition.
        For more information, see \l{QLocale}. At least one mapping needs to be present. However,
        it is good practice to supply the English (\c en) mapping, at least, as a fallback.
\row
    \li \c description
    \li object
    \li \e An optional object containing language (\c string) to descriptive name (\c string)
        mappings. This field uses the same syntax as the \c name field.
\row
    \li \c categories
    \li list<string>
    \li The list of category names the package should be associated with. This is mainly for
        the automated app-store uploads as well as displaying the packages's applications or
        intents within a fixed set of categories in the System UI.
\row
    \li \c version
    \li string
    \li The version of the package as a string.
\row
    \li \c applications
    \li list
    \li \e Required. The list of applications contained in this package. At least one application
        has to be defined.
\row
    \li \c intents
    \li list
    \li \e The list of intents provided by applications in this package.
\endtable

The fields used for each item within the \c applications list are as follows:

\table
\header
    \li Field Name
    \li Type
    \li Description
\row
    \li \c id
    \li string
    \li The unique ID of an application represented as a string with a maximum length of 150
        characters. This ID can be used to look up information about the application in the
        \l{ApplicationModel}{ApplicationModel QML Type}. Since this ID is used in the file system, only a subset of
        the printable ASCII characters are allowed: \c{0-9}, \c{a-z}, \c{A-Z} as well as any of
        \c{!#$%&'`^~_+-=.,;()[]{}}. If you are building a larger system with third party
        applications, it is good practice to use reverse DNS notation for the application IDs to
        help keep track of your IDs in the long run. The helper function
        \l{ApplicationInstaller::validateDnsName} can help you to enforce this policy from the
        System UI.
\row
    \li \c code
    \li string
    \li \e Required. The main executable - interpreted by the \c runtime.
\row
    \li \c runtime
    \li string
    \li \e Required. A runtime ID, referencing a runtime plugin. Currently, \c qml,
        \c qml-inprocess, and \c native are supported.

        For the QML runtimes, the \c code field needs to point to the main QML file, which should
        have an ApplicationManagerWindow as a root item.

        For the native runtime, the \c code field can point to an arbitrary executable, which is
        executed via QProcess::start(). The application manager will run the application with the
        environment variable \c QT_QPA_PLATFORM set to \c wayland.

        \note The application is expected to be a valid Wayland client.
\row
    \li \c runtimeParameters
    \li object
    \li This object can contain \c runtime specific parameters - those are directly handed down to
        the runtime plugin by the application manager.

        See \l{runtime-parameters-details}{runtime parameters} for a full list.
\row
    \li \c supportsApplicationInterface
    \li bool
    \li If set to \c true the application must implement the \l ApplicationInterface API.
        In this case the application manager will wait until the application is connected to the
        ApplicationInterface on the P2P D-Bus until it marks it as 'running'. For runtimes that
        support quick launching (like the \c qml runtime) this is not required as it defaults to
        \c true. Otherwise the default is \c false.
\row
    \li \c capabilities
    \li list<string>
    \li An optional, platform specific list of special access rights for the application. Later,
        the middleware can query these capabilities and verify them, via the application manager.

        \note The application manager itself does not attach any meaning to this list of strings.
              Instead, the application manager acts as a trustee between the (digitally signed)
              application manifest and the (customer specific) middleware; this middleware may
              require more information about the application it's communicating with and the
              application manager can act as a trusted source of application \e capabilities.
\row
    \li \c opengl
    \li object
    \li Gives you the possibility to specify the required OpenGL version and/or profile. For more
        information, see \l{OpenGL Specification}.
        \note Specifying an OpenGL configuration that is different from the default OpenGL
              configuration in the main application manager configuration, disables the use of
              the quick-launch mechanism for this application.
\row
    \li \c applicationProperties
    \li object
    \li Exports user-defined properties (key/value pairs) to the application and the System UI. The
        actual properties must be listed under the \c private and \c protected access control
        tag; other properties are ignored. These properties are exposed as
        ApplicationManager::application() to the System UI and as
        ApplicationInterface::applicationProperties to the QML application:
        \list
        \li The application has access to private and protected properties. Private keys overwrite
            identical protected ones.
        \li The System UI has access to protected properties only.
        \endlist
        While the properties are converted to QVariantMaps, the application manager won't interpret
        them in any way.
\row
    \li \c logging/dlt/id
    \li string
    \li If provided, this value is used as the automotive DLT application ID. The ID is limited to
        four characters, additional characters are discarded. If an ID is not provided, it defaults
        to 'A' followed by a three digit application number.

        \note For QML runtimes, the ID is "PCLQ" from the very start of the application process,
              until you change it as described.
\row
    \li \c logging/dlt/description
    \li string
    \li If provided, it is used as the automotive DLT application description, which allows to
        augment the short DLT application ID with a more verbose description. If not explicitly
        provided, a default description is used.
\endtable

\target manifest-intent
The fields used for each item within the \c intents list are as follows:

\table
\header
    \li Field Name
    \li Type
    \li Description
\row
    \li \c id
    \li string
    \li Required. The id of the intent. Make sure to only specify intent IDs that the applications
        in this package are actually handling.
\row
    \li \c visibility
    \li string
    \li The visibility of this intent outside of this package: Can be either \c private or \c public
        (which is the default, if this field is not specified at all). Private intents can only be
        requested by applications from this package, while public intents can also be requested by
        other applications in the system.
\row
    \li \c handlingApplicationId
    \li string
    \li If this package contains more than one application, then it is mandatory to specify which
        application is handling this intent; if there is only one application defined, then this
        application will be used as the default handler for all intents.
        The given application id has to be from within this package.
\row
    \li \c requiredCapabilities
    \li list<string>
    \li Limit the client applications that are able to call this intent to applications having at
        least one of the capabilities given in this list. An empty list or by simply not specifying
        this field at all will lead to no capability restrictions.
\row
    \li \c parameterMatch
    \li object
    \li Filter the intent based on the incoming parameters. This can be used to have multiple
        applications being able to handle the same intent, dependent on the actual parameters in
        the intent request. See the IntentObject::parameterMatch documentation for a detailed
        explanation for this field.
\row
    \li \c name
    \li object
    \li The name of the intent. It will default to the \c name field in the global section, but it
        can be overridden for each intent by specifying this field.
\row
    \li \c icon
    \li string
    \li The icon of the intent. It will default to the \c icon field in the global section, but it
        can be overridden for each intent by specifying this field.
\row
    \li \c description
    \li object
    \li The description of the intent. It will default to the \c description field in the global
        section, but it can be overridden for each intent by specifying this field.
\row
    \li \c categories
    \li object
    \li The list of categories for this intent. It will default to the \c categories field in the
        global section, but it can be overridden for each intent by specifying this field.
\endtable


\target runtime-parameters-details
The \c runtimeParameters are specific to the runtimes, so the table below has an additional column
that specifies which runtime a configuration option applies to:

\table
\header
    \li Name
    \li Runtimes
    \li Type
    \li Description
\row
    \li \c loadDummyData
    \li qml, qml-in-process
    \li bool
    \li Automatically load dummy data for the application, using the same algorithm as Qt's
        \c qmlscene and \c qml tools. By default no dummy data is loaded.
\row
    \li \c importPaths
    \li qml, qml-in-process
    \li list<string>
    \li A list of paths to add to the QML-engine's import paths. Use of this parameter is
        equivalent to setting \c QML2_IMPORT_PATH for a program started from the command line.
\row
    \li \c resources
    \li qml, qml-in-process
    \li list<string>
    \li Takes a list of \l{The Qt Resource System}{Qt resource} files (.rcc) or libraries that have
        resources \l{Compiled-In Resources}{compiled-in} and registers them within the application
        process. Resources can be accessed with the ":" or "qrc://" file path prefix.
\row
    \li \c pluginPaths
    \li qml, qml-in-process
    \li list<string>
    \li A list of paths to add to Qt's library paths, which are used to find plugins. Use of this
        parameter is equivalent to setting \c QT_PLUGIN_PATH for a program started from the command
        line.
\row
    \li \c arguments
    \li native
    \li list<string>
    \li A list of command line parameters to use when starting the application's executable.
\row
    \li \c environmentVariables
    \li native, qml
    \li object
    \li A simple string-to-string map, describing the environment variables that should be set when
        spawning the runtime process. You can remove a variable from the default environment by
        setting it to \c null.

        \note This feature is meant for development and demos only, as it has the following
              limitations and side-effects:
        \list
        \li These variables are completely ignored, if you are running the application manager
            with security checks enabled.
        \li Setting these variables disables the use of the quick launch mechanism for this
            application.
        \endlist
\row
    \li \c documentUrl
    \li string
    \li An optional default document URL to use if the application is started without
        specifying a document URL (see \l{ApplicationManager::startApplication}).
\endtable

*/