Manifest Definition

Overview

The package manifest (or metadata) file is a YAML (version 1.1) file named info.yaml, consisting of exactly two YAML documents: the file-type header and the actual application manifest.

The application-manager architecture is flexible enough to support other file formats such as e.g. XML, but the only meta-data loader currently implemented is based on this YAML format.

Dynamically installed applications are described by a single manifest file in their root directory, called info.yaml. Built-in applications, that are shipped as part of the System-UI are allowed to optionally have multiple aliases: these are comparable to a Microsoft Windows shortcut, in that they allow to 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 main info.yaml file and need to be named info-<descriptive name>.yaml. See below for a description of these alias manifests.

Basic Manifest

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

%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'

The meaning of the fields within the info.yaml file header (first YAML document) is as follows:

Field nameTypeDescription
formatVersionintCurrently always 1. (Required)
formatTypestringAlways am-application. (Required)

The meaning of the fields within the info.yaml actual manifest data (second YAML document) is as follows:

Field nameTypeDescription
idstringThe unique id of an application represented as a string. This can be used to look up information about the application in the ApplicationManager model. Due to its use in the file-system, only a subset of the printable ASCII characters is allowed though: 0-9, a-z, A-Z as well as any of !#$%&'`^~_+-=.,;()[]{}. The maximum length of this id is 150 characters. If you are building a larger system with 3rd-party applications, it is good practice to use reverse-DNS notation for the application ids to help keep an overview in the long run. The helper function ApplicationInstaller::validateDnsName can help you with enforcing such a policy from the System-UI side.
iconstringThe filesystem path to the icon, relative to the info.yaml file. (Required)
name objectAn object containing language (string) to display name (string) mapppings. The language identifiers need to adhere to the standard POSIX locale definition. Please see the QLocale documentation for a detailed explanation. At least one mapping needs to be present. It is however good practice to supply at least the english (en) mapping as a fallback. (Required)
codestringThe main executable - interpreted by the runtime (see below). (Required)
categoriesarray<string>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.
runtimestringA runtime id, referencing a runtime plugin - currently qml, qml-inprocess and native are supported by the application-manager. (Required)

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

For the native runtime, the 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 QT_QPA_PLATFORM set to wayland. Please note, that the application is expected to be a valid Wayland client.

runtimeParametersobjectThis object can contain runtime specific parameters - those are directly handed down to the runtime plugin by the application-manager.

See below for a list of those parameters.

environmentVariablesobjectDeprecated. Moved to runtimeParameters - see below.
documentUrlstringAn optional default document URL that is used, if the application is started without specifying a document URL (see ApplicationManager::startApplication).
supportsApplicationInterfaceboolIf set to true the application must implement the ApplicationInterface API. In this case the ApplicationManager 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 qml runtime) this is not required as it defaults to true. Otherwise the default is false.
mimeTypes array<string>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: please see ApplicationManager::openUrl for more information.
capabilitiesarray<string>An optional, platform specific list of special access rights for the application - these capabilities can later be queried and verified by the middleware via the application-manager.
versionstringThe version of the application in string form.
openglobjectGives you the possibility to specify the required OpenGL version and/or profile. See the main configuration for more information on this subject. Please note that specifying an OpenGL configuration that is different from the default OpenGL configuration in the main application-manager configuration will disable the use of the quick-launch mechanism for this application.
applicationPropertiesobjectExports user-defined properties (key/value pairs) to the application and the System-UI. The actual properties must be listed under the private and protected access control tag (other properties will be ignored). The properties are exposed as ApplicationManager::application()::applicationProperties to the System-UI and as the ApplicationInterface::applicationProperties to the QML application:
  • The application has access to private and protected properties. Private keys will overwrite identical protected ones.
  • The System-UI has access to protected properties only.

The properties will just be converted to QVariantMaps, but the application-manager will not interpret them in any way.

preloadboolDeprecated. If needed, use applicationProperties and implement custom logic in your System-UI to load specific applications on startup.
importancerealDeprecated. Use applicationProperties if needed.
backgroundModestringDeprecated. Use applicationProperties if needed.

The runtimeParameters are specific to the actual runtimes, so the table below has an additional column specifying which runtime a configuration option applies to:

NameRuntimesTypeDescription
loadDummyDataqml, qml-in-processboolAutomatically load dummy-data for the application, using the same algorithm as Qt's qmlscene tool. By default no dummy-data is loaded.
importPathsqml, qml-in-processarray<string>A list of paths that should be added to the QML-engine's import paths - this is the same as setting QML2_IMPORT_PATH for a program started from the command line.
argumentsnativearray<string>A list of command line parameters that are used when starting the application's executable.
environmentVariablesnative, qmlobjectA 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 giving it a null value.

Please note, that this is intended to be a feature mostly for development and demos: you will have the following limitations/side-effects:

  • these variables are completely ignored, if you are running the application-manager with security checks enabled.
  • setting these will disable the use of the quick-launch mechanism for this application.

Alias Manifests

Here is an example of an alias manifest (info-am.yaml) for the info.yaml file in the chapter above. This way, you could have one single tuner application radio.qml running that can be started using two different entries (with different text and icons) in the application launcher. Starting an alias while the application is already running will not start another instance. Only if a documentUrl is set, the already running instance will receive the ApplicationInterface::openDocument signal containing the respective strings set via the documentUrl parameter and can then change its UI accordingly. The alias manifests have to be in the same folder as the application's main info.yaml file and need to be named info-<descriptive name>.yaml.

%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"

The meaning of the fields within the info-am.yaml file header (first YAML document) is as follows:

Field nameTypeDescription
formatVersionintCurrently always 1. (Required)
formatTypestringAlways am-application-alias. (Required)

The meaning of the fields within the alias manifest data (second YAML document) is as follows:

Field nameTypeDescription
aliasIdstringThe unique id of the base application (see Basic Manifest), followed by the @ sign and an unique tag for this alias. This tag has the same character restrictions as the main application id. (Required)
iconstringSee the icon field in Basic Manifest. (Required)
nameobjectSee the name field in Basic Manifest. (Required)
documentUrlstringSee the documentUrl in Basic Manifest

© 2018 Pelagicore AG. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.