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
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
|
AppStream-Glib
==============
This library provides GObjects and helper methods to make it easy to read and
write AppStream metadata. It also provides a simple DOM implementation that
makes it easy to edit nodes and convert to and from the standardized XML
representation. It also supports reading of Debian-style DEP-11 metadata.
What this library allows you to do:
* Read and write compressed AppStream XML files
* Read compressed Debian YAML files
* Add and search for applications in an application store
* Get screenshot image data and release announcements
* Easily retrieve the best application data for the current locale
* Efficiently interface with more heavy-weight parsers like expat
For more information about what AppStream is, please see the wiki here:
https://www.freedesktop.org/wiki/Distributions/AppStream/
Getting Started
---------------
To install the libappstream-glib library you either need to install the
`libappstream-glib` package from your distributor, or you can build a local
copy. To do the latter just do:
dnf install docbook-utils gettext-devel glib-devel \
gobject-introspection-devel gperf gtk-doc gtk3-devel \
json-glib-devel libarchive-devel libcurl-devel \
libstemmer-devel libuuid-devel libyaml-devel \
meson rpm-devel
mkdir build && cd build
meson .. --prefix=/opt -Dbuilder=false
ninja
Hacking
-------
If you want a new feature, or have found a bug or a way to crash this library,
please report as much information as you can to the issue tracker:
https://github.com/hughsie/appstream-glib/issues -- patches very welcome.
New functionality or crash fixes should include a test in `libappstream-builder/
as-self-test.c`
to ensure we don't regress in the future. New functionality should also be
thread safe and also not leak *any* memory for success or failure cases.
Translations
------------
Translations of the natural language strings are managed through a
third party translation interface, transifex.com.
Newly added strings will be periodically uploaded there for translation,
and any new translations will be merged back to the project source code.
Please use [https://www.transifex.com/projects/p/appstream-glib/](https://www.transifex.com/projects/p/appstream-glib/) to contribute translations,
rather than sending pull requests.
AppStream-Builder
=================
appstream-builder is a tool that allows us to create AppStream metadata from a
directory of packages.
It is typically used when generating distribution metadata, usually at the same
time as modifyrepo or createrepo.
What this tool does:
* Searches a directory of packages and reads just the RPM header of each.
* If a package contains an interesting file, just the relevant files are
decompressed from the package archive.
* A set of plugins are run on the extracted files, and if these match certain
criteria `AsbApplication` objects are created.
* Any screenshots referenced are downloaded to a local cache.
This is optional and can be disabled with `--nonet`.
* When all the packages are processed, some of the `AsbApplication` objects are
merged into single applications. This is how fonts are collected.
* The `AsbApplication` objects are serialized to XML and written to a
compressed archive.
* Any application icons or screenshots referenced are written to a .tar archive.
Getting Started
---------------
To run appstream-builder you either need to install the package containing the
binary and data files, or you can build a local copy. To do the latter just do:
dnf install docbook-utils gettext-devel glib-devel \
gobject-introspection-devel gperf gtk-doc gtk3-devel \
libarchive-devel libsoup-devel \
libstemmer-devel libuuid-devel libyaml-devel \
meson rpm-devel rpm-devel
mkdir build && cd build
meson .. --prefix=/opt -Dbuilder=true
ninja
To actually run the extractor you can do:
./client/appstream-builder --verbose \
--max-threads=8 \
--log-dir=/tmp/logs \
--packages-dir=/mnt/archive/Megarpms/21/Packages \
--temp-dir=/mnt/ssd/AppStream/tmp \
--output-dir=./repodata \
--screenshot-url=http://megarpms.org/screenshots/ \
--basename="megarpms-21"
Note: it is possible to use "globs" like `/mnt/archive/Megarpms/21/Packages*` to
match multiple directories or packages.
This will output a lot of progress text. Now, go and make a cup of tea and wait
patiently if you have a lot of packages to process. After this is complete
you should finally see:
Writing ./repodata/megarpms-21.xml.gz
Writing ./repodata/megarpms-21-failed.xml.gz
Writing ./repodata/megarpms-21-ignore.xml.gz
Writing ./repodata/megarpms-21-icons.tar
Done!
You now have two choices what to do with these files. You can either upload
them with the rest of the metadata you ship (e.g. in the same directory as
`repomd.xml` and `primary.sqlite.bz2`) which will work with Fedora 22 and later:
modifyrepo_c \
--no-compress \
/tmp/asb-md/appstream.xml.gz \
/path/to/repodata/
modifyrepo_c \
--no-compress \
/tmp/asb-md/appstream-icons.tar.gz \
/path/to/repodata/
You can then do something like this in the megarpms-release.spec file:
Source1: http://www.megarpms.org/temp/megarpms-20.xml.gz
Source2: http://www.megarpms.org/temp/megarpms-20-icons.tar.gz
%install
DESTDIR=%{buildroot} appstream-util install %{SOURCE1} %{SOURCE2}
This ensures that gnome-software can access both data files when starting up.
What is an application
----------------------
Applications are defined in the context of AppStream as such:
* Installs a desktop file and would be visible in a desktop
* Has an metadata extractor (e.g. libappstream-builder/plugins/asb-plugin-gstre
amer.c)
and includes an AppData file
Guidelines for applications
---------------------------
These guidelines explain how we filter applications from a package set.
First, some key words:
* **SHOULD**: The application should do this if possible
* **MUST**: The application or addon must do this to be included
* **CANNOT**: the application or addon must not do this
The current rules of inclusion are thus:
* Icons **MUST** be installed in `/usr/share/pixmaps/*`, `/usr/share/icons/*`,
`/usr/share/icons/hicolor/*/apps/*`, or `/usr/share/${app_name}/icons/*`
* Desktop files **MUST** be installed in `/usr/share/applications/`
or `/usr/share/applications/kde4/`
* Desktop files **MUST** have `Name`, `Comment` and `Icon` entries
* Valid applications with `NoDisplay=true` **MUST** have an AppData file.
* Applications with `Categories=Settings`, `Categories=ConsoleOnly` or
`Categories=DesktopSettings` **MUST** have an AppData file.
* Applications **MUST** have had an upstream release in the last 5 years or
have an AppData file.
* Application icon **MUST** be available in 48x48 or larger
* Applications must have at least one main or additional category listed
in the desktop file or supply an AppData file.
See https://specifications.freedesktop.org/menu-spec/latest/apa.html and
https://specifications.freedesktop.org/menu-spec/latest/apas02.html for the
full `Categories` list.
* Codecs **MUST** have an AppData file
* Input methods **MUST** have an AppData file
* If included, AppData files **MUST** be valid XML
* AppData files **MUST** be installed into `/usr/share/metainfo`
* Application icons **CANNOT** use XPM or ICO format
* Applications **CANNOT** use obsolete toolkits such as GTK+-1.2 or QT3
* Applications that ship a desktop file **SHOULD** include an AppData file.
* Screenshots **SHOULD** be in 16:9 aspect ratio
* Application icons **SHOULD** have an alpha channel
* Applications **SHOULD** ship a 256x256 PNG format icon or scalable SVG
* Applications **SHOULD** ship a matching High Contrast icon
* Applications **SHOULD** not depend on other applications
* AppData files **SHOULD** include translations
* Desktop files **SHOULD** include translations
Guidelines for fonts
--------------------
* Fonts **MUST** have a valid MetaInfo file installed to /usr/share/appdata
* Fonts packaged in multiple packages **SHOULD** have multiple MetaInfo files
* Fonts families **SHOULD** only have one description section
* Fonts of different styles or weights of the same family **SHOULD** use `<exte
nds>`
* MetaInfo files **SHOULD** include translations where possible
License
-------
LGPLv2+
|
