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
212
213
214
215
216
|
<?xml version='1.0' encoding='ISO-8859-1'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!-- Please adjust the date whenever revising the manpage. -->
<!ENTITY date "<date>18 April,2016</date>">
<!-- SECTION should be 1-8, maybe w/ subsection other parameters are
allowed: see man(7), man(1). -->
<!ENTITY package "appstream-generator">
<!ENTITY gnu "<acronym>GNU</acronym>">
<!ENTITY gpl "&gnu; <acronym>GPL</acronym>">
]>
<refentry>
<refentryinfo>
<title>appstream-generator</title>
<copyright>
<year>2016-2022</year>
<holder>Matthias Klumpp</holder>
</copyright>
<productname>AppStream Generator</productname>
&date;
</refentryinfo>
<refmeta>
<refentrytitle>appstream-generator</refentrytitle>
<manvolnum>1</manvolnum>
</refmeta>
<refnamediv>
<refname>&package;</refname>
<refpurpose>Generate AppStream metadata from distribution repositories</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>&package;</command>
<group>
<option>COMMAND</option>
</group>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
This manual page documents briefly the <command>&package;</command> command.
</para>
<para>
<command>&package;</command> generates AppStream metadata from the repositories of a software distribution.
It currently supports the following repository formats / distributions: Debian, Ubuntu, Arch Linux, RPM-MD (Fedora,
Mageia).
</para>
<para>
The generator will produce AppStream catalog metadata files in the AppStream YAML or XML format to be shipped
to users, as well as detailed HTML reports about found components and HTML and JSON reports on issues found
while compiling the metadata. It reads .desktop files as well as metainfo files, renders fonts, scales images, caches
screenshots etc. to produce high-quality metadata for AppStream based software centers and other tools to consume.
Usually, <command>&package;</command> is integrated with the existing software build & delivery workflow of
a distribution.
</para>
<para>
The <command>&package;</command> tool is based on the <literal>libappstream</literal> library for metadata conversion and analysis.
If you just want to embed AppStream metadata processing into another tool, using <literal>libappstream</literal> directly is likely a
better choice. The generator tool does some heavy lifting like rendering fonts and scaling images, which might not be necessary
for simple cases.
</para>
<para>
To use <command>&package;</command>, a <filename>asgen-config.json</filename> file is required. Its format is described in detail
in <ulink url="https://github.com/ximion/appstream-generator/blob/master/docs/asgen-config.md">the asgen-config.json documentation</ulink>.
</para>
<para>
The generator supports a wide range of features that can individually configured to fit the needs of different projects and adjust the generated
metadata to specific use cases. Refer to the configuration file documentation for information on what options are available.
</para>
<para>
For more information about the AppStream project and the other components which are part of it, take a look at
the AppStream pages at <ulink url="http://www.freedesktop.org/wiki/Distributions/AppStream/">Freedesktop.org</ulink>.
</para>
</refsect1>
<refsect1>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>run <replaceable>SUITE</replaceable> <replaceable><optional>SECTION</optional></replaceable></option></term>
<listitem>
<para>
Process new metadata for the given distribution suite and publish it.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>cleanup</option></term>
<listitem>
<para>
Cleanup old/expired metadata and media files from the cache and directories.
It is recommended to run this command every week, or at least every month, depending
on how many changes happen in the software repository.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>publish <replaceable>SUITE</replaceable> <replaceable><optional>SECTION</optional></replaceable></option></term>
<listitem>
<para>
Export all metadata and publish reports in the export directories.
</para>
<para>
You usually do not want to run this task explicitly, because it is already automatically
performed by the <option>run</option> command.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>remove-found <replaceable>SUITE</replaceable></option></term>
<listitem>
<para>
Drop all valid processed metadata and hints from the selected suite.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>forget <replaceable>PKID</replaceable></option></term>
<listitem>
<para>
Drop all information we have about this (partial) package-id.
</para>
<para>
A package-id consists of a <literal>name/version/arch</literal> triplet.
For this command, the version and architecture can be omitted to forget
all packages that match a particular name or name-version combination.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>info <replaceable>PKID</replaceable></option></term>
<listitem>
<para>
Show information associated with this (full) package-id.
</para>
<para>
A package-id consists of a <literal>name/version/arch</literal> triplet.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-w|--workspace <replaceable>DIR</replaceable></option></term>
<listitem>
<para>Define the workspace location.</para>
<para>
If this flag is omitted, and no workspace directory is given in the generator
configuration file, the current directory is assumed as the workspace location.
</para>
<para>
This parameter, if given, overrides any workspace location defined elsewhere.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-c|--config <replaceable>FILE</replaceable></option></term>
<listitem>
<para>Define a configuration file.</para>
<para>
Explicitly set a generator configuration JSON file. If this flag is omitted, the <filename>asgen-config.json</filename> file
in the current workspace directory is used.
</para>
<para>
If no workspace directory is defined in the configuration file itself, the directory it is located in is used
as workspace. This can be overridden by defining a workspace explicitly with <option>-w</option>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--force</option></term>
<listitem>
<para>Enforce the command.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--verbose</option></term>
<listitem>
<para>Show extra debugging information.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--version</option></term>
<listitem>
<para>Display the version number of &package;.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>See Also</title>
<para>appstreamcli (1).</para>
</refsect1>
<refsect1>
<title>AUTHOR</title>
<para>
This manual page was written by Matthias Klumpp <email>matthias@tenstral.net</email>.
</para>
</refsect1>
</refentry>
|
