MetaInfo/Components

 

Under Construction
This is a new page, currently under construction!

Introduction

Every project which provides interfaces for external projects to use can publish them in a metadata document. A software-center might show these components as "technical items", but more importantly, by specifying this information other tools gain the ability to install for example missing libraries without knowing their exact package name. It is also possible for developers to specify just the component names their project depends on and having a distribution-independent tool installing all missing packages, to greatly simplify building software for the first time. The component metadata is also used to match upstream projects with distribution packages, so even if your project does not provide public interfaces, you may consider adding this metadata to your project.

The AppStream project provides a metadata XML specification for projects to specify all necessary data.

Projects wanting to make use of the metadata file should ship one or more XML files in /usr/share/metainfo/%{id}.metainfo.xml.

File Specification

Sample File

The file should contain something like this:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Copyright 2014 First Lastname <[email protected]> -->
<component>
  <id>org.kde.frameworks.ThreadWeaver</id>
  <metadata_license>FSFAP</metadata_license>
  <project_license>LGPL-2.1+</project_license>
  <name>ThreadWeaver</name>
  <summary>ThreadWeaver Library for the KDE Platform</summary>
  <description>
    <p>
      ThreadWeaver is a helper for multithreaded programming.
      It uses a job-based interface to queue tasks and execute them in an efficient way.
      You simply divide the workload into jobs, state the dependencies between the jobs and ThreadWeaver
      will work out the most efficient way of dividing the work between threads
      within a set of resource limits. 
    </p>
  </description>
  <url type="homepage">http://kde.org/</url>
  <url type="bugtracker">https://bugs.kde.org/buglist.cgi?product=frameworks-threadweaver&amp;component=general</url>
  <project_group>KDE</project_group>
  <provides>
    <library>libthreadweaver.so.4</library>
  </provides>
</component>

Component type

The type property of the <component/> root node can be empty. If the component provides a special software-product, such as a graphical application, font, codec or input-method, you may set the property accordingly. See also the DesktopApp metadata.

<id/>

A unique identifier for the component you want to publish. After you have set an identifier, please do not change it in future releases! The identifier must be a reverse-DNS name, e.g. "org.kde.frameworks.MyProject"

<metadata_license/>

The <metadata_license> tag is indicating the content licence that you are releasing the one metadata XML file as. This is not typically the same as the project license. It is a good idea to choose a permissive license for your metadata, so distributions can easily bundle it with metadata from other projects. For more information, see the definition of the <project_license/> tag in the AppStream docs.

<project_license/>

The license your project is licensed under. This tag is the same as the tag defined in the AppStream docs, and the same rules for license names apply.

<name/>

A human-readable name of the published component.

<summary/>

A short summary of what your component is good for.

<description/>

The long description of your component. You may want to consider the following hints for a good component description:

• Include 2-3 paragraphs of interesting easy to read prose.
• Ensure you describe the purpose of the component
• Describe any important features.
• Explain which group of users (e.g. developers) might want to use your component primarily
• Break down each paragraph into easily translated paragraphs.
• Try not use more than 100 words.
• Only mention what the component does now, and not what it planned

Do not assume the format is HTML. Only paragraph, ordered list and unordered list are supported at this time.

<url/>

Links of type homepage should be a link to the upstream homepage for the component. The type bugtracker should be a link to the project's bugtracker, ideally an URL for the "Report New Bug" formular. More url types you might be interested in are specified in the AppStream specifications.

<project_group/>

If you include the <project_group> tag then this identifies your project with a specific upstream umbrella project. "Umbrella project" means that you use all infrastructure and policies, for instance string freezes dates, bugtracker and source control instance, of the umbrella project. KDE projects should obviously set their project-group to "KDE".

<provides/>

The <provides/> tag allows you to specify the public interfaces your project provides. Distributors must ensure that the package which contains the metadata file contains or at least depends on the items specified in the <provides> tag, Projects may install multiple metadata files specifying different components, to make it easier for distributors to split up the project's binaries into different packages. The <provides/> tag has multiple children, describing the interface types it provides. Known types are:

• library: For shared libraries in a public library directory. Do not add libraries used exclusively by your project, which don't have stable API/ABI.
• binary: For any executable which gets installed into a directory which is usually in the distribution's PATH environment variable.
• python2: The name of a Python2 module which is installed by this component.
• python3: The name of a Python2 module which is installed by this component.
• font: Name of a font installed by the component. The font's filename can be specified using the file property of this tag.

Other

There are some other tags you can use to describe your application. A full list is available at the documentation of generic components in the AppStream documentation.

Questions

See the more general questions at the main page on metadata.

Do you have some example patches on added metadata?

Yes. Take a look at this patch against KGraphViewer, where metadata for a library and an application was added. This also shows nicely how CMake can fill in missing fields in AppStream metadata.

Further Reading

The AppStream documentation also contains information about the meta-info files shipped in upstream projects.