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
|
<?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-Metadata-Runtime">
<title>Runtime</title>
<section id="spec-runtime-introduction">
<title>Introduction</title>
<para>
Components of type <literal>runtime</literal> describe a collection of interdependent software components that are
required to run other software. They set a baseline of dependencies that other software can rely on and link against.
A very simple runtime may for example be a chroot environment of a minimal Linux system bootstrap.
Runtimes are often employed by software distribution systems such as <ulink url="https://flatpak.org/">Flatpak</ulink> or Valve's Steam, but may be
used by others and may even be directly distributed as part of tranditional Linux distributions.
</para>
<para>
Runtimes can ship metainfo files in <filename>/usr/share/metainfo/%{id}.metainfo.xml</filename>.
</para>
</section>
<section id="spec-runtime-example">
<title>Example file</title>
<para>
A <literal>runtime</literal> metainfo file can look like this:
</para>
<programlisting language="XML">
<![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<component type="runtime">
<id>org.freedesktop.Platform</id>
<metadata_license>FSFAP</metadata_license>
<project_license>LicenseRef-free=https://freedesktop-sdk.gitlab.io/</project_license>
<name>Freedesktop Platform</name>
<summary>Basic libraries to run Linux desktop applications</summary>
<description>
<p>
The Freedesktop Platform is a runtime that contains the most basic libraries
and files needed to run a Linux desktop application.
...
</p>
</description>
<url type="homepage">https://freedesktop-sdk.gitlab.io/</url>
<releases>
<release version="10.0" />
<release version="9.0" date="2020-01-12" />
...
</releases>
</component>]]></programlisting>
</section>
<section id="spec-runtime-filespec">
<title>File specification</title>
<para>
Note that the XML root must have the <literal>type</literal> property set to <code>runtime</code>.
This clearly identifies this metainfo document as describing a runtime.
</para>
<variablelist>
<varlistentry id="tag-id-runtime">
<term><id/></term>
<listitem>
<para>
For runtimes, the value of the <code><id/></code> tag must follow the AppStream ID naming conventions (it should be a reverse-DNS name).
</para>
</listitem>
</varlistentry>
<varlistentry id="tag-runtime-requires">
<term><requires/></term>
<listitem>
<para>
The <literal>requires</literal> tag may be used if multiple runtimes are based on top of each other, or if the runtime actually describes
a software development kit (SDK) that wants to require its base runtime.
See <xref linkend="tag-relations"/> for a detailed description of this tag.
</para>
<para>
In order to depend on other runtimes, their component-ID should be referenced in a <literal>requires</literal> tag. Example:
</para>
<programlisting language="XML"><![CDATA[<requires>
<id version="1.0" compare="ge">org.freedesktop.Sdk</id>
</requires>]]></programlisting>
</listitem>
</varlistentry>
<varlistentry id="tag-runtime-project_license">
<term><project_license/></term>
<listitem>
<para>
The <code><project_license/></code> tag usually indicates the license of the component
(refer to <xref linkend="tag-project_license"/> for details).
This is tricky for runtimes, as they are usually comprised of many individual pieces of software under
different licenses, which would create a very long and complex SPDX license expression.
It is therefore recommended to have the tool that builds the runtime collect all the licenses and generate a document
or website containing. This document can then be linked using <code>LicenseRef-free=URL</code> if the runtime is free software,
or <code>LicenseRef-proprietary=URL</code> in case it contains non-free elements.
</para>
<para>
Example:
</para>
<programlisting language="XML"><![CDATA[<project_license>LicenseRef-free=https://example.com/licenses.html</project_license>]]></programlisting>
</listitem>
</varlistentry>
<varlistentry id="tag-runtime-provides">
<term><provides/></term>
<listitem>
<para>
This tag is described in detail for generic components at <xref linkend="tag-provides"/>.
</para>
<para>
The runtime may use the <code><provides/></code> tag to denote the individual modules it is comprised of,
using their component IDs.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
For a component of type <literal>runtime</literal>, the following tags are required and must be present for a valid document:
<xref linkend="tag-id-runtime"/>, <xref linkend="tag-name"/>, <xref linkend="tag-summary"/>,
<xref linkend="tag-metadata_license"/>, <xref linkend="tag-project_license"/>.
</para>
</section>
</section>
|
