debian-jessie-main.xml.gz
. For Fedora 20 (Heisenbug) updates it would be fedora-20-updates.xml.gz
. 3rd-party repositories use a vendor name and repository-name combination, for example Ubuntu PPAs might get ppa-ubuntu12.04-username-foobar.xml
.
/usr/share/app-info/xmls
stores all AppStream data which has been installed via software packages, while /var/cache/app-info/xmls
stores application data which was downloaded by the package manager or placed there by other tools (for example, Limba). The XML files can either be plain files or be compressed with gzip. It is always a good idea to compress the files, because they tend to become quite large.
<components>
tag as the root element. It has all the <component>
tags of different type
s as children.
<components>
element, no matter of which type they are, must at least have an id
, name
, summary
and pkgname
tag. For applications, a icon
tag is also required.
<components>
root node has these properties, where the first two are required:
type
property, every <component/>
tag in AppStream collection data may have a priority
property, defining the priority of this specific metadata over other metadata from different AppStream XML files (for example, from a different repository) which have the same component-id. The value of this tag is an integer, if the property is missing, a value of "0"
is assumed.
merge
property, assuming the values append
, replace
or remove-component
. If the value is append
, all data this component describes will be appended to data of the component with the same ID. If the value is replace
the fields of the target component will be replaced with the ones present in the merge component. If the merge type is remove-component
, the entore component matching the ID of the merge-component should be removed from the metadata pool. Merge-components with a higher priority take precedence. If a component has a merge
property, the only tag that must be present for it is the <id/>
tag, any other metadata is optional.
<id/>
tag is a short unique and usually lower-cases identifier for the component. Depending on the component's type, different naming conventions apply.
Important
pkgname
tags. They should only be used multiple times as a workaround or if there is no sensible way of creating a matching metapackage.
desktop-application
, the application name as defined in the application's desktop file is used.
<project_license/>
tag is indicating the license of the component. It should be a SPDX license expression. Possible values include:
desktop
, it is usually taken from a Desktop file, if the application does not ship an upstream metadata file.
<description> <p> Power Statistics is a program used to view historical and current battery information and will show programs running on your computer using power. </p> <p>Example list:</p> <ul> <li>First item</li> <li>Second item</li> </ul> <p> You probably only need to install this application if you are having problems with your laptop battery, or are trying to work out what programs are using significant amounts of power. </p> </description>
<description/>
tag itself has a language property and contain the translated paragraphs for the given language. This allows faster parsing of the Appstream XML file, and does not increase it's size much, as long as it is compressed.
<project_group>
tag identifies a project with a specific upstream umbrella project. Known values include GNOME, KDE, XFCE, LXDE, Mozilla
and MATE
, although other umbrella projects like Yorba
would make sense too.
Note
<icon/>
tag describes the component icon. It is mostly used for GUI applications (component-type desktop-application
). It can be of the type stock
, cached
, local
, or url
.
stock
icons are loaded from stock. The icon name should never include any file-extension or path.
cached
icons are loaded from the AppStream icon cache. The icon tag should contain the icon file name, including it's extension. It must not contain a full or relative path to the icon file.
local
icons are reserved for AppStream data installed by local applications or via 3rd-party application installers. They should specify a full file path. This icon type may have width
and height
properties.
remote
icons loaded from a remote URL. Currently, only HTTP urls are supported. This icon type should have width
and height
properties.
<icon type="stock">gimp</icon> <icon type="cached">firefox.png</icon> <icon type="remote" width="64" height="64">http://example.com/icons/foobar.png</icon> <icon type="local" width="64" height="64">/usr/share/pixmaps/foobar.png</icon>
<icon/>
tags might be combined for one application, for example to define a stock
icon and a cached
icon. Software-Centers should always prefer the stock icon, if it is available, and fall back to the other icon types if they can not find it. The libappstream library makes it easy to do that.
cached
over local
over remote
icons when setting the non-stock icon for the application.
<mimetype>
tags, describing the mime types this component supports. The data can usually be fetched from the Desktop files. Example:
<mimetypes> <mimetype>text/html</mimetype> <mimetype>image/jpeg</mimetype> <mimetype>application/rss+xml</mimetype> </mimetypes>
<category>
tags, describing the categories this component is located in. This tag is usually applied to components of type desktop-application
, although it might be used by others later. This data is usually taken from Desktop files, a list of categories can be found in the Freedesktop menu spec. Example:
<categories> <category>Science</category> <category>Network</category> <category>Telephony</category> </categories>
Deprecated Tags
<appcategories>
with its <appcategory>
child elements is deprecated API. AppStream parsers should handle these tags just like the category
tags, there is no difference except for the name.
<keyword>
tags, describing keywords for the component, to make it easier to find in a software center. In case of type desktop-application
components, this data is taken from .desktop files. For addon
components, the upstream metadata file usually provides this tag. For translated keyword lists, the root node (<keywords/>
) has the language property. Example:
<keywords> <keyword>IDE</keyword> <keyword>development</keyword> <keyword>programming</keyword> </keywords> <keywords xml:lang="de"> <keyword>IDE</keyword> <keyword>entwicklung</keyword> <keyword>programmierung</keyword> </keywords>
<screenshot>
tags, describing screenshots which are available for the software. A screenshot tag my have the attribute type="default"
, marking it as the software's default screenshot, which primarily represents it in a software center.
screenshots
tag is described for metainfo files in <screenshots/>. In collection metadata, the tag has the exact same format as in metainfo files. The metadata generator may add an arbitrary number of resized thumbnails though.
<screenshot>
is defined by several images of different sizes. All images should have their width and hight set as arguments. Also, one of the images should be marked as type="source"
, indicating that it is the unscaled version of the screenshot. Images of type="thumbnail"
define thumbnails of the screenshot.
<caption>
tag, describing the screenshot's caption. This is usually what the user can see on the image shown. The tag is translatable.
<screenshots> <screenshot type="default"> <caption>FooBar showing kitchen-sink functionality.</caption> <caption xml:lang="de">FooBar beim Ausführen der Spühlbecken-Funktion.</caption> <image type="source" width="800" height="600">http://www.example.org/en_US/main.png</image> <image type="thumbnail" width="752" height="423">http://www.example.org/en_US/main-large.png</image> <image type="thumbnail" width="112" height="63">http://www.example.org/en_US/main-small.png</image> </screenshot> <screenshot> .... </screenshot> </screenshots>
<compulsory_for_desktop>
tag indicates that the component which the metadata belongs to is essential for the functionality of the defined desktop environment. Examples for compulsory components are the GNOME-Shell
by the GNOME-Project, or the Plasma-Desktop
by KDE, as well as things like iBus
or the desktop login manager.
<compulsory_for_desktop>
tag are allowed, so a project can be essential for many desktops. The distributor decides which components should be made compulsory, however it is generally a good idea to follow upstream's recommendations on that matter.
pkgname
tag (or in dependencies of it).
<developer_name/>
tag as described in the specification for a generic component. See <developer_name/> for more information.
release
tag may have a description
tag as child, containing a brief description of what is new in the release. The description
tag is structured as described in <description/>. This also applies to its translation rules.
release
tags. It may also convert ISO 8601 date
properties of the metainfo file into an UNIX timestamp timestamp
property. It should avoid generating metadata containing both properties on a release
tag.
<releases> <release version="1.8" timestamp="1424116753"> <description> <p>This stable release fixes the following bug:</p> <ul> <li>CPU no longer overheats when you hold down spacebar</li> </ul> </description> <size type="download">12345678</size> <size type="installed">42424242</size> </release> <release version="1.2" timestamp="1397253600" /> <release version="1.0" timestamp="1345932000" /> </releases>
<release/>
tag has a <description/>
tag as parameter, describing the new release briefly, distributors are encouraged to provide 2-4 <release/>
release tags for every component. If no description is provided, one tag is enough.
<lang/>
child nodes, which have a language code as value. Each <lang/>
node may have a percentage
property, which describes the percentage value to which a component has been translated.
<languages> <lang percentage="96">gu</lang> <lang percentage="94">ca@valencia</lang> <lang percentage="91">de</lang> <lang percentage="93">eo</lang> </languages>
bundle
tag indicates that the described software is available as a software bundle via a 3rd-party application installer. The value of this tag is an identification string for the bundle.
bundle
tag can coexist with the pkgname
tag, in case a component is available from multiple sources.
type
property of this tag indicates which 3rd-party software installation solution the bundle belongs to. Currently supported solutions are:
limba
.
flatpak
.
appimage
.
snap
.
tarball
.
<bundle type="limba">foobar-1.0.2</bundle>
suggests
tag provides suggestions of other software made by this component. It follows the same schema as described for metainfo files in <suggests/>.
upstream
type allowed for metainfo files, the catalog data also allows a heuristic
type, which is added by automatic recommendation services, and might be based on the user's preferences. It is commonly injected into existing metadata via a merge
pseudo-component.
<suggests type="upstream"> <id>org.kde.gwenview.desktop</id> <id>org.inkscape.Inkscape</id> </suggests> <suggests type="heuristic"> <id>org.gimp.gimp.desktop</id> </suggests>
description
tags in its agreement_section
child tags now following the same translation rules as the toplevel <description/> tag in collection metadata.
<?xml version="1.0"?> <components version="0.10"> <component type="desktop-application"> <id>org.mozilla.Firefox</id> <pkgname>firefox-bin</pkgname> <name>Firefox</name> <name lang="en_GB">Firefoux</name> <summary>Web browser</summary> <summary lang="fr_FR">Navigateur web</summary> <project_license>MPL-2.0</project_license> <keywords> <keyword>internet</keyword> <keyword>web</keyword> <keyword>browser</keyword> <keyword lang="fr_FR">navigateur</keyword> </keywords> <icon type="stock">web-browser</icon> <icon type="cached">firefox.png</icon> <categories> <category>network</category> <category>web</category> </categories> <mimetypes> <mimetype>text/html</mimetype> <mimetype>text/xml</mimetype> <mimetype>application/xhtml+xml</mimetype> <mimetype>application/vnd.mozilla.xul+xml</mimetype> <mimetype>text/mml</mimetype> <mimetype>application/x-xpinstall</mimetype> <mimetype>x-scheme-handler/http</mimetype> <mimetype>x-scheme-handler/https</mimetype> </mimetypes> <url type="homepage">http://www.mozilla.com</url> <screenshots> <screenshot type="default"> <image type="source" width="800" height="600">http://www.awesomedistro.example.org/en_US/firefox.desktop/main.png</image> <image type="thumbnail" width="200" height="150">http://www.awesomedistro.example.org/en_US/firefox.desktop/main-small.png</image> </screenshot> </screenshots> <provides> <binary>firefox</binary> </provides> </component> <component> <id>org.freedesktop.PulseAudio</id> <name>PulseAudio</name> <summary>The PulseAudio sound server</summary> <url type="homepage">http://www.freedesktop.org/wiki/Software/PulseAudio/</url> <project_license>GPL-2.0+</project_license> <provides> <library>libpulse-simple.so.0</library> <library>libpulse.so.0</library> <binary>start-pulseaudio-kde</binary> <binary>start-pulseaudio-x11</binary> </provides> <release version="2.0"/> </component> <component type="font"> <id>org.linuxlibertine.LinuxLibertine</id> <name>Linux Libertine</name> <summary>Linux Libertine Open fonts</summary> <provides> <font>LinLibertine_M.otf</font> </provides> </component> <!-- more components here! --> </components>