AppStream MetaInfo in Terra packages

Terra supports AppStream MetaInfo, which enables your package to be picked up by graphical software 'store' applications, such as KDE Plasma's Discover (opens in a new tab) or GNOME's Software app (opens in a new tab). In Ultramarine, we encourage the use of these graphical store, so adding AppStream MetaInfo is great for discoverability. This page will cover creating and installing AppStream MetaInfo to your package, but we also highly encourage you to read over the documentation here (opens in a new tab).

If you have difficulty populating the .metainfo.xml file, hop into our Discord (opens in a new tab) server, or make a draft pull request asking for assistance.

When Should I Use AppStream MetaInfo?

Packages that fit any of the following cases SHOULD provide the metainfo file.

• If upstream already provides the metainfo file, you SHOULD install it instead of making your own
• Graphical apps
• TUI applications that make sense to be opened in a graphical environment

Other packages MAY also provide appstream metadata files.

Creating the metainfo.xml File

Before creating your metainfo.xml file, check out our AppStream helper macro, it can save a lot of effort.

Determine your package's app ID, then start with the template below. The metainfo file MUST be named app_id.metainfo.xml. For example, com.github.neohtop.metainfo.xml.

Determining the App ID

If your package has an app ID used in file names, or references an app ID in any way, you MUST use this as the app ID in your spec. See here to learn how to define the app ID in your spec file.

If you do not know what the app ID of the package is, determine it using reverse domain name notation (opens in a new tab).

• If your package is only hosted on GitHub (no website, not a GitHub mirror), then the app ID MUST be com.github.APP-NAME.
• If your package has its own website, or the organization that creates it does, you MUST use its website in the app ID. Using Microsoft Edit as an example, the app ID will be com.microsoft.Edit.

metainfo.xml Template

Everything in this template SHOULD be in your metainfo.xml, but there are many optional sections not included that you may want. We will go over the important ones in the next section.

<!-- All uppercase words MUST be replaced with the package-specific value. -->
<?xml version="1.0" encoding="UTF-8" ?>
<component type="TYPE">
  <id>APPID</id>
  <metadata_license>CC0-1.0</metadata_license> <!-- You SHOULD license your metainfo.xml as CC0-1.0 -->
  <project_license>LICENSE</project_license>
  <icon type="local">ICON DIRECTORY</icon> <!-- For now, the icon type MUST be local due to a bug where remote icon files do not work. This should be a .png or .svg application icon that gets installed by your package. -->
 
  <name>NAME</name>
  <summary>SUMMARY</summary> <!-- SHOULD be the same as the `Summary:` in your .spec file. -->
 
  <description> <!-- SHOULD be the same as the `%description` in your .spec file. -->
    <p>
        DESCRIPTION.
    </p>
  </description>
 
  <launchable type="desktop-id">NAME.desktop</launchable>
 
  <url type="homepage">URL</url> <!-- Can be the GitHub page, prefer a website though-->
 
  <releases>
    <release version="PACKAGE VERISON"/>
  </releases>
</component>

Optional metainfo.xml sections

These metainfo tags are optional, but it is RECOMMENDED to use as many as you can to properly flesh out the metainfo. Other tags exist that are not listed, you are free to use them, but they're generally not useful.

All information here is based on the freedesktop.org specification, and each section links to its respective Freedesktop page for more info. Again, we highly recommend you read through the entire spec here (opens in a new tab) and here (opens in a new tab).

Keywords

The <keywords/> tag¹ will make your package easier find when users search these terms:

<keywords>
  <keyword translate="no">IDE</keyword>
  <keyword>development</keyword>
  <keyword>programming</keyword>
  <keyword xml:lang="de">entwicklung</keyword>
  <keyword xml:lang="de">programmierung</keyword>
</keywords>

Developer

This tag² is to specify the developer/s of your package. This can be a person or group/organization.

Screenshots

This tag³ can be either a video or a picture, and is used to showcase the package in software stores. You can (and should) use full URLs to screenshots.

Freedesktop's example:

<screenshots>
  <screenshot type="default">
    <caption>The FooBar main window.</caption>
    <image type="source" width="1600" height="900">https://example.com/foobar/screenshot-1.png</image>
  </screenshot>
  <screenshot>
    <caption>Foobar showing the frobnicate functionality.</caption>
    <image type="source" width="1600" height="900">https://example.com/foobar/screenshot-2.png</image>
  </screenshot>
  <screenshot>
    <video codec="av1" width="1600" height="900">https://example.com/foobar/screencast.mkv</video>
  </screenshot>
 
  <screenshot environment="plasma-mobile">
    <caption>The FooBar main window, but on Plasma Mobile</caption>
    <image type="source" width="1600" height="900">https://example.com/foobar/screenshot-1_plasma-mobile.png</image>
  </screenshot>
 
  <screenshot environment="gnome:dark">
    <caption>The FooBar main window, on GNOME in dark mode</caption>
    <image type="source" width="1600" height="900">https://example.com/foobar/screenshot-1_gnome_dark.png</image>
  </screenshot>
 </screenshots>

Macros

%terra_appstream

%terra_appstream will add more sections to your metainfo.xml, or can generate your metainfo.xml file entirely. You SHOULD use it when installing your own metainfo.xml file. Review the Terra AppStream helper README (opens in a new tab) for more. You MAY need to add this line to your spec file: BuildRequires: terra-appstream-helper

%appid SHOULD be defined at the top of your spec file (preamble), and used in references to the metainfo file name, for example:

%{_metainfodir}/%appid.metainfo.xml

Other components may be defined, such as name_pretty, developer, org, etc.

Installing your Metainfo File

To properly install your metainfo file:

%global appid [your package's app ID]   # This defines a macro "appid" as your package's appid.
 
...
 
Source1: %appid.metainfo.xml   # This specifies your metainfo.xml file as a source in your spec file.
 
...
 
%install
...
%terra_appstream -o %{SOURCE1} # Runs the %terra_appstream macro on your metainfo.xml file.
 
%files
...
%{_metainfodir}/%appid.metainfo.xml # Lists your installed metainfo.xml file to be included in the package.

Footnotes