Package metadata guidelines

If you package software which could benefit from having AppStream metadata, or if your package already contains AppStream metadata, you can find some helpful advice on this page.

Finding information

If you ship a graphical application, it will need to conform to some standards before it will be included in the AppStream metadata that Debian and Ubuntu provide. New software centers such as GNOME software and KDE discover rely on AppStream to know which applications are available.

Visit https://appstream.debian.org/ or http://appstream.ubuntu.com/ to see the metadata status per package. Any errors will cause processing to stop and need to be rectified before your package will be included in the exported metadata.

General

AppStream metadata is to be placed in the /usr/share/metainfo/ directory and must be placed in the package which should be installed in order to get the software described by the respective metadata. This means that you might need to move the *.metainfo.xml or *.appdata.xml to the right (meta)package.

In case your AppStream metadata is describing a desktop-application (you can tell by the XML root-node having a type="desktop-application" or type="desktop" attribute), the .appdata.xml file must be placed in the same package as the .desktop file already is, which (as above) must be the package containing the application itself.

Metadata files can be validated for conformity with the specification using appstreamcli from the appstream package (appstreamcli validate <file>.xml)

Component naming

Each AppStream component has a unique identifier (the value of the <id/> tag), which is unique across all distributions. So if you add new metadata which does not originate from upstream, make sure that you contribute the changes back to your upstream project to make the ID really unique.

In case you want to add metadata to a GUI application, the naming rules are strict: The ID has to match the name of the .desktop file. In general, AppStream IDs follow a reverse URL scheme, with a <tld>.<vendor>.<product>.<type> scheme (where <type> is optional). To read more about AppStream IDs, consult the documentation.

/!\ If the file is named 'guiapp.desktop', the ID in the metainfo file must be 'guiapp' or 'guiapp.desktop', if it is 'org.example.guiapp.desktop', the ID must be 'org.example.guiapp' or 'org.example.guiapp.desktop'. If you want to be compatible with older AppStream versions, having the .desktop suffix is recommended.

Packaging Hints and Common Issues

Doing the minimal amount of work possible

The minimal thing you have to do to get your graphical application to appear in the extracted metadata and therefore software centers is to provide a desktop file with a description and a valid icon, following the below rules.

Writing a metainfo file

If you provide a metainfo file its information will be preferred over that in the .desktop file.

The quickstart guide tells you how to write an appstream metainfo file. These should be submitted and shipped by upstream, not kept locally in Debian packages.

Icon best practices

Your GUI application must ship (or reference, see below) an icon of at least 64x64px in size, which should be in /usr/share/icons/hicolor/%{size}/apps/. This avoids accidential upscaling of icons. Please avoid placing icons in /usr/share/pixmaps and place them in /usr/share/icons/hicolor/%{size}/apps/ instead.

Please do not ship icons in the .xpm format. Ideally have them available as .png bitmap and/or .svg vectorgraphic in their respective subdirectories under /usr/share/icons/hicolor. Applications with only .xpm icons will not be included in the metadata.

Only reference stock icons from default themes

In case the .desktop file of your GUI app is referencing a stock icon not available in your package but in the icon theme, make sure it is available in the default icon themes of GNOME or KDE (or Humanity on Ubuntu), adwaita-icon-theme or breeze-icon-theme/oxygen-icon-theme.

Hunting the right icon down is a really expensive process for the data generator, so we can not launch an archive-wide search. Also, with multiple icon-themes available in the archive, determining the right icon is hard. Having it in the default themes ensures your application will have an icon (unless it ships the icon on its own already, then it should be fine).

Since the AppStream Generator relies on packages' md5sums file to determine the contents of a package, symbolic links are not recognized. So please do not symlink .desktop files or icons from other places into /usr/share/pixmaps or the /usr/share/icons/hicolor subdirectories, because the generator will not see these files then. Relying on symbolic links in icon-theme packages is fine though.

Conflicts between packages

If there are two different packages providing the same application (e.g. in case there is a GTK+2 and GTK+3 version), only one package can provide the AppStream metadata. Having two different packages providing an AppStream component with the same ID is not allowed. In case of explicit metadata (in form of *.metainfo.xml files in /usr/share/metainfo), just move the metadata to the package which should provide the software component by default. In case of implicit metadata, e.g. via .desktop files, you can exclude a .desktop file from being added to the metadata, while still showing it when installing the package explicitly. See the hints on excluding .desktop files from the metadata.

Moving metadata between packages

If you move AppStream metadata from one package to another, the metadata generator might emit a warning message about metadata with the same ID being in two different packages. You can safely ignore issues like this, they will vanish as soon as the old package leaves the archive.

How to exclude .desktop files from the metadata

In some rare cases you might want to ship a .desktop file in /usr/share/applications and have it visible in normal desktop sessions, but explicitly want to exclude it from the AppStream metadata. This might for example be the case when adding compatibility .desktop files for renamed files (to preserve links the user has created), or when your package providing a .desktop file and conflicting with another package providing the same file should not be shown in the software overview (removing the "duplicate IDs" issue from the metadata error page). In that case, simply add an X-AppStream-Ignore=True key-value pair to the Desktop Entry section of that .desktop file. The generator will ignore it next time the file is processed.

Keep in mind that if your .desktop file already has a NoDisplay=True key or is not of Type=Application, it will always be ignored, unless a matching metainfo file exists in /usr/share/metainfo.

Announcing supported hardware

Packages can announce what kind of hardware and kernel modules they support, to allow tools to find relevant packages for a given piece of hardware. Isenkram is one such tool included in Debian. To do so one need to provide a metadata XML file where the component->provides->modalias XML tags are filled in. Here is an example for pymissile. In the Debian package a file debian/com.googlecode.pymissile.metainfo.xml is created with the following content:

<?xml version="1.0" encoding="UTF-8"?>
<component>
  <id>com.googlecode.pymissile</id>
  <metadata_license>MIT</metadata_license>
  <name>pymissile</name>
  <summary>Control original Striker USB Missile Launcher</summary>
  <description>
    <p>
      Pymissile provides a curses interface to control an original
      Marks and Spencer / Striker USB Missile Launcher, as well as a
      motion control script to allow a webcamera to control the
      launcher.
    </p>
  </description>
  <provides>
    <modalias>usb:v1130p0202d*</modalias>
  </provides>
</component>

Next, a file debian/pymissile.install is created with to make sure it is installed in /usr/share/metainfo/:

debian/com.googlecode.pymissile.metainfo.xml usr/share/metainfo

The modalias value is a file glob style expression matching the modalias values provided by the Linux kernel. Note, the modalias matching is case sensitive, and hex values are upper case, while field separators are lower case. The usb: one above is for USB dongles with vendor ID 1130 and product ID 0202. This one-liner can be used to get a complete list of all the modalias entries visible on the running machine (included some examples)

% find /sys/devices/ -name modalias -print0 | xargs -0 cat
dmi:bvnPhoenixTechnologiesLTD:bvr6.00:bd09/17/2015:svnVMware,Inc.:pnVMwareVirtualPlatform:pvrNone:rvnIntelCorporation:rn440BXDesktopReferencePlatform:rvrNone:cvnNoEnclosure:ct1:cvrN/A:
pci:v00008086d00007190sv000015ADsd00001976bc06sc00i00
x86cpu:vendor:0000:family:0006:model:002D:feature:,0000,0001,0002,0003,0004,0005,0006,0007,0008,0009,000B,000C,000D,000E,000F,0010,0011,0013,0015,0017,0018,0019,001A,001B,002B,0034,003B,003D,0068,006B,006C,006D,006F,0072,0076,0077,0078,007C,007D,0080,0081,0089,008D,0093,0094,0097,0099,009A,009B,009C,009F,00C0,00E0,00E1,00E5,00E6,00E7,
usb:v8087p0024d0000dc09dsc00dp01ic09isc00ip00in00
%

If you have the dongle inserted in your machine, you can use this to try to figure out the best way to recognize the dongle using modalias globbing rules.

In addition to the modalias values emitted by the kernel, the isenkram system recognize a special modalias type lkmodule: for Linux kernel modules. Packages working well with one or more specific kernel modules (say the ccipp RAID driver) can specify something like <modalias>lkmodule:cciss</modalias> to indicate that it is good to install on machines using this kernel module.

The appstreamcli what-provides modalias '<my-modalias>' command can be used to check if a given hardware modalias string matches the modalias matching rule included in the AppStream database. Note, the lkmodule modalias strings are not found under /sys/devices/.

Requests for adding hardware information in packages are tracked in the BTS using user tagging. Please use user pere@hungry.com and tag appstream-modalias if you submit a BTS report related to this topic. Please also XCC pere@debian.org.