Manifest Definition

Note: This page describes the current metadata format (am-package, version 1) that was introduced with the 5.14 release. For the old format - that is still supported - please see here.

Overview

The package manifest or metadata file, info.yaml, is a 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 info.yaml file, in the root directory of the package.

Package Manifest

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

%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: { quitTime: 100 }

  capabilities:
  - cameraAccess
  - locationAccess

intents:
- id: setFrequency
  handlingApplicationId: com.pelagicore.radio.app
  name:
    en: "Change the radio frequency"
- id: systemAboutToShutDown # broadcast from the sys-ui
  handleOnlyWhenRunning: yes

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

Field Name	Type	Description
`formatVersion`	int	Required. Currently always `1`.
`formatType`	string	Required. Always `am-package`.

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

Field Name	Type	Description
`id`	string	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 PackageManager QML Type. Since this ID is used in the file system, only a subset of the printable ASCII characters are allowed: `0-9`, `a-z`, `A-Z` as well as any of !#$%&'`^~_+-=.,;()[]{}. 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 PackageManager::validateDnsName can help you to enforce this policy from the System UI.
`icon`	string	Required. The icon's file name. The file must be located in the same directory as `info.yaml` and can be in any image format that Qt supports.
`name`	object	An optional object containing language (`string`) to display name (`string`) mappings. The language identifiers need to adhere to the standard POSIX locale definition. For more information, see QLocale. It is good practice to supply at least the English (`en`) mapping, as a fallback. If not supplying any mapping at all, the name will be the same as the `id`.
`description`	object	An optional object containing language (`string`) to descriptive name (`string`) mappings. This field uses the same syntax as the `name` field.
`categories`	list<string>	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.
`version`	string	The version of the package as a string. This will also be used to set up QCoreApplication::applicationVersion for multi-process QML applications.
`applications`	list	Required. The list of applications contained in this package. At least one application has to be defined.
`intents`	list	The list of intents provided by applications in this package.

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

Field Name	Type	Description
`id`	string	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 ApplicationModel QML Type. Since this ID is used in the file system, only a subset of the printable ASCII characters are allowed: `0-9`, `a-z`, `A-Z` as well as any of !#$%&'`^~_+-=.,;()[]{}. 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 PackageManager::validateDnsName can help you to enforce this policy from the System UI. This ID will also be used to set up QCoreApplication::applicationName for multi-process QML applications. If you are using reverse DNS notation, the QCoreApplication::organizationName and QCoreApplication::organizationDomain properties will both be set to the domain part of the ID. Otherwise the organization name and domain will default to QtProject and qt-project.org respectively.
`code`	string	Required. The main executable - interpreted by the `runtime`.
`runtime`	string	Required. A runtime ID, referencing a runtime plugin. Currently, `qml`, `qml-inprocess`, and `native` are supported. 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`. Note: The application is expected to be a valid Wayland client.
`runtimeParameters`	object	This object can contain `runtime` specific parameters - those are directly handed down to the runtime plugin by the application manager. See runtime parameters for a full list.
`supportsApplicationInterface`	bool	If set to `true` the application must implement the ApplicationInterface D-Bus 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 `qml` runtime) this is not required as it defaults to `true`. Otherwise the default is `false`.
`capabilities`	list<string>	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 capabilities.
`opengl`	object	Gives you the possibility to specify the required OpenGL version and/or profile. For more information, see 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.
`applicationProperties`	object	Exports 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 are ignored. These properties are exposed as ApplicationManager::application() to the System UI and as ApplicationInterface::applicationProperties to the QML application: The application has access to private and protected properties. Private keys overwrite identical protected ones. The System UI has access to protected properties only. While the properties are converted to QVariantMaps, the application manager won't interpret them in any way.
`logging/dlt/id`	string	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.
`logging/dlt/description`	string	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.
`name`	object	The name of the application. It will default to the `name` field in the global package section, but it can be overwritten for each application by specifying this field.
`icon`	string	The icon of the application. It will default to the `icon` field in the global package section, but it can be overwritten for each application by specifying this field.
`description`	object	The description of the application. It will default to the `description` field in the global package section, but it can be overwritten for each application by specifying this field.
`categories`	list<string>	The list of categories for this application. It will default to the `categories` field in the global package section, but it can be overwritten for each application by specifying this field.
`watchdog`	object	Use this field to override the global watchdog settings for this application. This allows you to set different timeouts for this application, or to enable/disable the watchdog for this application specifically. See the Watchdog documentation for more information.

The fields used for each item within the intents list are as follows:

Field Name	Type	Description
`id`	string	Required. The id of the intent. Make sure to only specify intent IDs that the applications in this package are actually handling.
`visibility`	string	The visibility of this intent outside of this package: Can be either `private` or `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.
`handlingApplicationId`	string	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.
`handleOnlyWhenRunning`	bool	By default, applications are automatically started when a request is targeted at them, but they are not currently running. Setting the `handleOnlyWhenRunning` flag to `true` will prevent this behavior and any requests for this intent will only be forwarded to its handling application, if the application is actuallly running. This is useful for system-wide broadcasts that are only relevant if an application is active (e.g. changes in internet availability).
`requiredCapabilities`	list<string>	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.
`parameterMatch`	object	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.
`name`	object	The name of the intent. It will default to the `name` field in the global package section, but it can be overwritten for each intent by specifying this field.
`icon`	string	The icon of the intent. It will default to the `icon` field in the global package section, but it can be overwritten for each intent by specifying this field.
`description`	object	The description of the intent. It will default to the `description` field in the global package section, but it can be overwritten for each intent by specifying this field.
`categories`	list<string>	The list of categories for this intent. It will default to the `categories` field in the global package section, but it can be overwritten for each intent by specifying this field.

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

Name	Runtimes	Type	Description
`loadDummyData`	qml, qml-in-process	bool	Deprecated. Automatically load dummy data for the application, using the same algorithm as Qt's `qmlscene` and `qml` tools. By default no dummy data is loaded.
`importPaths`	qml, qml-in-process	list<string>	A list of paths to add to the QML-engine's import paths. Use of this parameter is equivalent to setting `QML2_IMPORT_PATH` for a program started from the command line.
`resources`	qml, qml-in-process	list<string>	Takes a list of Qt resource files (.rcc) or libraries that have resources compiled-in and registers them within the application process. Resources can be accessed with the ":" or "qrc://" file path prefix.
`pluginPaths`	qml, qml-in-process	list<string>	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 `QT_PLUGIN_PATH` for a program started from the command line.
`arguments`	native	list<string>	A list of command line parameters to use when starting the application's executable.
`environmentVariables`	native, qml	object	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 `null`. Note: This feature is meant for development and demos only, as it has the following limitations and side-effects: These variables are completely ignored, if you are running the application manager with security checks enabled. Setting these variables disables the use of the quick launch mechanism for this application.
`documentUrl`	native, qml, qml-in-process	string	An optional default document URL to use if the application is started without specifying a document URL (see ApplicationManager::startApplication).

© 2024 The Qt Company Ltd. 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.