More documentation - especially regarding the new PackageManager

Also had to fix a few things in the PackageManager<->ApplicationInstaller
compatibility layer, because it became obvious that things didn't work
as expected while writing the documentation.

Change-Id: I92de9a7142e9713fed0b60fd0b69c1a24ff8eb5e
Reviewed-by: Dominik Holland <dominik.holland@qt.io>

1 files changed, 395 insertions, 0 deletions

diff --git a/doc/manifest-old.qdoc b/doc/manifest-old.qdoc
new file mode 100644
index 00000000..84c07f01
--- /dev/null
+++ b/doc/manifest-old.qdoc
@@ -0,0 +1,395 @@
+/****************************************************************************
+**
+** Copyright (C) 2019 Luxoft Sweden AB
+** Copyright (C) 2018 Pelagicore AG
+** 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-old.html
+\keyword info.yaml metadata manifest format
+\title Manifest Definition (pre 5.14)
+
+\note This page describes the old metadata format (\c am-application, version \c 1) that was used
+      up until 5.14. For the current format, please see \l{Manifest Definition}{here}. The 5.14
+      application manager is still able to parse the old format, but \l{Alias Manifests} are not
+      supported anymore.
+
+\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.
+
+Dynamically installed applications are described by a single \c info.yaml file, in their root
+directory. Built-in applications, that are shipped as part of the System UI can optionally have
+multiple aliases. This behavior is similar to a Microsoft Windows shortcut, where you can start
+the same program using a different icon, name, and commandline arguments. These files have to be
+in the same folder as the application's basic \c info.yaml file and need to be named
+\c info-<descriptive name>.yaml. See \l{Alias Manifests}{below} for a description of these alias
+manifests.
+
+\section1 Basic 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-application
+---
+id: 'com.pelagicore.radio'
+icon: 'FM-Radio.png'
+name:
+  en: "FM Radio"
+  de: "UKW-Rundfunk"
+code: "radio.qml"
+
+runtime: qml
+runtimeParameters: { loadDummyData: true }
+documentUrl: "fm"
+
+mimeTypes: [ "x-scheme-handler/x-radio" ]
+
+capabilities:
+- cameraAccess
+- locationAccess
+
+version: '1.2.1-alpha3'
+
+\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-application.
+\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 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 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 application-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 code
+    \li string
+    \li \e Required. The main executable - interpreted by the \c runtime.
+\row
+    \li \c categories
+    \li array<string>
+    \li The list of category names the application should be associated with. This is mainly for
+        the automated app-store uploads as well as displaying the application within a fixed set
+        of categories in the System UI.
+\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 environmentVariables
+    \li object
+    \li \e Deprecated; moved to \l{runtime-parameters-details}{runtime parameters}.
+\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}).
+\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 mimeTypes
+    \target mimeTypes field
+    \li array<string>
+    \li An optional array of MIME types the application can handle. The application manager
+        supports the classic file name or content to MIME type matching, as well as URL scheme
+        matching. For more information, see \l{ApplicationManager::openUrl}.
+\row
+    \li \c capabilities
+    \li array<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 version
+    \li string
+    \li The version of the application as a string.
+\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.
+\row
+    \li \c importance
+    \li real
+    \li \e Deprecated. Use \c applicationProperties instead.
+\row
+    \li \c backgroundMode
+    \li string
+    \li \e Deprecated. Use \c applicationProperties instead.
+\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 array<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 array<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 array<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 array<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
+\endtable
+
+\section1 Alias Manifests
+
+\note This page describes the old metadata format (\c am-application, version \c 1) that was used
+      up until 5.14. For the current format, please see \l{Manifest Definition}{here}. The 5.14
+      application manager is still able to parse the old format, but \l{Alias Manifests} are not
+      supported anymore.
+
+This is an example of an alias manifest, \c info-am.yaml, for the \c info.yaml file in the
+\l{Basic Manifest}. This way, you can have one single tuner application \c radio.qml running,
+that can be started using two different entries, both with different text and icons, in the
+application launcher.
+
+\badcode
+%YAML 1.1
+---
+formatVersion: 1
+formatType: am-application-alias
+---
+aliasId: 'com.pelagicore.radio@am'
+icon: 'AM-Radio.png'
+name:
+  en: "AM Radio"
+  de: "Langwellenrundfunk"
+
+documentUrl: "x-radio://am"
+
+\endcode
+
+If you start an alias while the application is already running, it does not start another instance.
+Only if a \c documentUrl is set, then does the instance currently running receive the
+\l{ApplicationInterface::openDocument} signal, that contains the respective strings that
+were set via the \c documentUrl parameter. Then, the application can change its UI accordingly.
+The alias manifests have to be in the same folder as the application's \c info.yaml file and
+must be named \c info-<descriptive name>.yaml.
+
+The meaning of the fields within the \c info-am.yaml file header (first YAML document) is 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-application-alias.
+\endtable
+
+The meaning of the fields within the alias manifest data (second YAML document) is as follows:
+
+\table
+\header
+    \li Field Name
+    \li Type
+    \li Description
+\row
+    \li \c aliasId
+    \li string
+    \li \e Required. The unique ID for the base application, followed by the \c{@} sign and a
+        unique tag for this alias. This tag has the same character restrictions as the main
+        application ID. See the \c id field in \l{Basic Manifest}.
+\row
+    \li \c icon
+    \li string
+    \li \e Required. See the \c icon field in \l{Basic Manifest}.
+\row
+    \li \c name
+    \li object
+    \li \e Required. See the \c name field in \l{Basic Manifest}.
+\row
+    \li \c documentUrl
+    \li string
+    \li See the \c documentUrl in \l{Basic Manifest}.
+\endtable
+
+*/