1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
|
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "AppStream.ent">
%BOOK_ENTITIES;
]>
<section id="sect-Quickstart-Addons">
<title>For upstream projects providing addons</title>
<section id="qsr-addon-introduction">
<title>Introduction</title>
<para>
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 <literal>addon</literal> 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.
</para>
<para>
Software which provides addons can ship one or more files in <filename>/usr/share/metainfo/%{id}.metainfo.xml</filename>.
</para>
<tip>
<para>
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 <ulink url="https://www.freedesktop.org/software/appstream/metainfocreator/#/">freedesktop.org/software/appstream/metainfocreator</ulink>.
</para>
</tip>
</section>
<section id="qsr-addon-example">
<title>Example file</title>
<para>
The file should contain something like this:
</para>
<programlisting language="XML"><![CDATA[<?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&component=Plugins</url>
<metadata_license>FSFAP</metadata_license>
<project_license>GPL-2.0+</project_license>
</component>]]></programlisting>
</section>
<section id="qsr-addon-content">
<title>Metadata file contents</title>
<para>
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 (<xref linkend="spec-component-filespec"/>) and an addon component (<xref linkend="spec-addondata-filespec"/>).
</para>
<variablelist>
<varlistentry>
<term><id/></term>
<listitem>
<para>
For addons, there is no strict rule for the component-ID. You should just ensure that you pick a unique name.
</para>
<para>
It is highly recommended to apply a <code>application_name-plugin_name</code> naming scheme for your addon-id.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><extends/></term>
<listitem>
<para>
This tag is refers to the ID of the component this addon is extending. For desktop applications, this is usually the name of their <filename>.desktop</filename> file.
</para>
<para>
This tag is described in detail for addon components at <xref linkend="tag-extends"/>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><name/></term>
<listitem>
<para>
Each addon component needs a <literal><name/></literal> tag, giving the addon a human-readable name.
</para>
<note>
<para>
Don't put the application name you are extending in the <literal><name/></literal> - so you want to use <code>Bookmarks</code> rather than <code>GEdit Bookmarks</code>
</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term><summary/></term>
<listitem>
<para>
The <literal><summary/></literal> tag follows the basic structure of a <xref linkend="tag-summary"/> as described in the specification. It is a required tag for an addon component.
</para>
<para>
Some useful hints for finding a good addon summary:
</para>
<itemizedlist>
<listitem>
<para>
Don't put the application name you are extending in the <literal><summary/></literal> - so you want to use <code>Easy document navigation with bookmarks</code>
rather than <code>Easy document navigation with bookmarks in GEdit</code>.
</para>
</listitem>
<listitem>
<para>
Don't use long or short descriptions.
Ideally <literal><summmary/></literal> should be less than <code>101</code> and more than <code>8</code>.
</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term><url/></term>
<listitem>
<para>
It is recommended to include links of types <code>homepage</code> and <code>bugtracker</code>.
You can omit the <literal><url/></literal> if it's the same as the upstream project.
</para>
<para>
Links of type <code>homepage</code> should be a link to the upstream homepage for the addon.
</para>
<para>
Links of type <code>bugtracker</code> should be a link to the upstream bugtracker.
</para>
<note>
<para>
It is highly recommended to be a link to the upstream bugzilla with filed component and product.
</para>
</note>
<warning>
<para>
It might be necessary to escape URLs. For example
replacing of <code>&</code> with <code>&amp;</code>.
</para>
</warning>
<para>
For other possible values, take a look at the tag's description in <xref linkend="tag-url"/>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><metadata_license/></term>
<listitem>
<para>
The <code><metadata_license/></code> 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:
</para>
<para>
The license codes correspond to the identifiers found at the <ulink url="http://spdx.org/licenses/">SPDX OpenSource License Registry</ulink>.
Take a look at <xref linkend="tag-metadata_license"/> for more details about this tag.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><project_license/></term>
<listitem>
<para>
The <literal><project_license/></literal> tag is indicating the license(s) this addon is released under.
Take a look at the specification of the <xref linkend="tag-project_license"/> tag for details on how to properly use it.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><update_contact/></term>
<listitem>
<para>
You might want to include an update-contact email address. Take a look at the specification of the <xref linkend="tag-update_contact"/> tag
for more details on how to use this tag.
</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
|
