Jump to content Jump to page navigation: previous page [access key p]/next page [access key n]
AppStream
AppStream › Metadata Quickstart › For upstream projects providing addons
AppStream › Metadata Quickstart › For upstream projects providing addons
Top
←→

## 5.2 For upstream projects providing addons #

### 5.2.1 Introduction #

Some software installed on the system is extensible via addons. To allow the user to install addons for software that is already available on the system, AppStream defines an `addon` component type. Software centers will usually group these components together with their host component and display them for installation. Extensible software may also access the AppStream data pool provided by the distribution or other software source directly, to offer installing missing addons from within the application.

Software which provides addons can ship one or more files in `/usr/share/metainfo/%{id}.metainfo.xml`.

###### Tip

To get you started quickly, the AppStream project provides a web-based form to quickly generate valid metainfo XML for some of the most common use cases. Check it out on freedesktop.org/software/appstream/metainfocreator (https://www.freedesktop.org/software/appstream/metainfocreator/#/).

### 5.2.2 Example file #

The file should contain something like this:

    <?xml version="1.0" encoding="UTF-8"?>
    <component type="addon">
      <id>org.gnome.gedit.gedit_bookmarks</id>
      <extends>org.gnome.gedit</extends>
      <name>Bookmarks</name>
      <summary>Easy document navigation with bookmarks</summary>
      <url type="homepage">https://wiki.gnome.org/Apps/Gedit/ShippedPlugins</url>
      <url type="bugtracker">https://bugzilla.gnome.org/enter_bug.cgi?product=gedit&amp;component=Plugins</url>
      <metadata_license>FSFAP</metadata_license>
      <project_license>GPL-2.0+</project_license>
    </component>

### 5.2.3 Metadata file contents #

This is a list of tags you might want to define for your application. For a full list of possible tags, take a look at the definition of a generic component (Section 2.1.3, “XML Specification”) and an addon component (Section 2.7.3, “File specification”).

<id/>

  For addons, there is no strict rule for the component-ID. You should just ensure that you pick a unique name.

  It is highly recommended to apply a `application_name-plugin_name` naming scheme for your addon-id.

<extends/>

  This tag is refers to the ID of the component this addon is extending. For desktop applications, this is usually the name of their `.desktop` file.

  This tag is described in detail for addon components at <extends/>.

<name/>

  Each addon component needs a `<name/>` tag, giving the addon a human-readable name.

  ###### Note

  Don't put the application name you are extending in the `<name/>` - so you want to use `Bookmarks` rather than `GEdit Bookmarks`

<summary/>

  The `<summary/>` tag follows the basic structure of a <summary/> as described in the specification. It is a required tag for an addon component.

  Some useful hints for finding a good addon summary:

  - Don't put the application name you are extending in the `<summary/>` - so you want to use `Easy document navigation with bookmarks` rather than `Easy document navigation with bookmarks in GEdit`.

  - Don't use long or short descriptions. Ideally `<summmary/>` should be less than `101` and more than `8`.

<url/>

  It is recommended to include links of types `homepage` and `bugtracker`. You can omit the `<url/>` if it's the same as the upstream project.

  Links of type `homepage` should be a link to the upstream homepage for the addon.

  Links of type `bugtracker` should be a link to the upstream bugtracker.

  ###### Note

  It is highly recommended to be a link to the upstream bugzilla with filed component and product.

  ###### Warning

  It might be necessary to escape URLs. For example replacing of `&` with `&amp;`.

  For other possible values, take a look at the tag's description in <url/>.

<metadata_license/>

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

  The license codes correspond to the identifiers found at the SPDX OpenSource License Registry (http://spdx.org/licenses/). Take a look at <metadata_license/> for more details about this tag.

<project_license/>

  The `<project_license/>` tag is indicating the license(s) this addon is released under. Take a look at the specification of the <project_license/> tag for details on how to properly use it.

<update_contact/>

  You might want to include an update-contact email address. Take a look at the specification of the <update_contact/> tag for more details on how to use this tag.