MetaInfo/DesktopApps: Difference between revisions

From KDE TechBase
No edit summary
Line 57: Line 57:
=== <metadata_license/> ===
=== <metadata_license/> ===
The '''<metadata_license>''' tag is indicating the content licence that you are releasing the one AppData XML file as. This is not typically the same as the project licence. By ommitting the licence value would probably mean your data would not be incorporated into the distribution metadata. Permissible licence codes include:
The '''<metadata_license>''' tag is indicating the content licence that you are releasing the one AppData XML file as. This is not typically the same as the project licence. By ommitting the licence value would probably mean your data would not be incorporated into the distribution metadata. Permissible licence codes include:
* CC0
* CC0
* CC-BY
* CC-BY
* CC-BY-SA
* CC-BY-SA
* GFDL
* GFDL
* MIT
* MIT
The licence codes correspond to the full licence texts as given by the [http://spdx.org/licenses/ SPDX OpenSource License Registry].
The licence codes correspond to the full licence texts as given by the [http://spdx.org/licenses/ SPDX OpenSource License Registry].
It is a good idea to choose a permissive license for your metadata, so distributions can easily bundle it with metadata from other projects.
It is a good idea to choose a permissive license for your metadata, so distributions can easily bundle it with metadata from other projects.

Revision as of 11:05, 17 April 2014

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

Introduction

Every software center that exists allows the user to look at screenshots and a long description of the application before it is installed. For most users it allows them to answer the question Do I want to install this application?

Traditionally in Linux distributions, we have none of this data for the vast majority of our desktop user-installable applications. To solve this, the AppStream project provides a metadata XML specification for projects to specify this data. For applications, these files are also called "AppData" files.

Applications wishing to have long descriptions, screenshots and other useful things are required to ship one or more files in /usr/share/appdata/%{id}.appdata.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 type="desktop">
  <id>ark.desktop</id>
  <metadata_license>CC-BY-SA</metadata_license>
  <project_license>GPL-2+</project_license>
  <name>Ark</name>
  <summary>Archiving Tool</summary>
  <description>
    <p>
      Ark is a graphical file compression/decompression utility with support for multiple formats,
      including tar, gzip, bzip2, rar and zip, as well as CD-ROM images.
      Ark can be used to browse, extract, create, and modify archives. 
    </p>
    <p>Features:</p>
    <ul>
      <li>Several forums supported: gzip, bzip2, zip, rar, 7z and more</li>
      <li>Preview file contents without extracting files</li>
    </ul>
    <p>
      Additional information on why the user wants this application....
    </p>
  </description>
  <screenshots>
    <screenshot type="default" width="834" height="651">http://kde.org/images/screenshots/ark.png</screenshot>
    <screenshot width="800" height="600">http://kde.org/images/screenshots/ark-feature2.png</screenshot>
  </screenshots>
  <url type="homepage">http://kde.org/applications/utilities/ark/</url>
  <url type="bugtracker">https://bugs.kde.org/enter_bug.cgi?format=guided&amp;product=ark</url>
  <project_group>KDE</project_group>
  <provides>
    <binary>ark</binary>
    <library>libkerfuffle.so.4</library>
  </provides>
</component>

Component type

The type property of the <component/> root node must be set to desktop in order for the application to show up in software-centers.

<id/>

The %{id} is the same name as the installed .desktop file for the application.

<metadata_license/>

The <metadata_license> tag is indicating the content licence that you are releasing the one AppData XML file as. This is not typically the same as the project licence. By ommitting the licence value would probably mean your data would not be incorporated into the distribution metadata. Permissible licence codes include:

  • CC0
  • CC-BY
  • CC-BY-SA
  • GFDL
  • MIT

The licence codes correspond to the full licence texts as given by the SPDX OpenSource License Registry. 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/>

You can omit this tag if you want the software center to have the same strings as the desktop menu. In some cases it might be required to have a different name in the software-center, but most appdata.xml files will not need to explicitly define this.

<summary/>

You can omit this tag if you want the software center to have the same strings as the desktop menu. In some cases it might be required to have a different name in the software-center, but most appdata.xml files will not need to explicitly define this.

~TODO

Further Reading

The AppStream documentation also contains information about the meta-info files shipped in upstream projects. Our friends at GNOME also have their own version of a short application-metadata howto, where the instructions on this page are derived from. You can check it out here.