systemd/docs/APPSTREAM_BUNDLE.md

title	category	layout	SPDX-License-Identifier
Appstream Bundle	Interfaces	default	LGPL-2.1-or-later

Appstream Bundle

NOTE: This document is a work-in-progress.

NOTE: This isn't yet implemented in libappstream and the software centers.

Appstream catalogs are a standardized way to expose metadata about system components, apps, and updates to software centers (i.e. GNOME Software and KDE Discover). The <bundle/> tag links an appstream component to a packaging format. This is used by the software centers to decide which code path (or plugin) should handle the component. For instance: components with a <bundle type="package">...</bundle> will be handled by PackageKit, and components with a <bundle type="flatpak">...</bundle> will be handled by libflatpak. This document will define how to format an appstream component's <bundle> tag such that software centers will know to manage it using systemd. The following syntax will be supported:

A type="systemd" attribute. This tells the software center that it should treat the bundle tag as described in this document.

A class="" attribute, with the following possible values: sysupdate, extension, confext, or portable. These correspond to sysupdate components, sysexts, confexts, and portable services respectively.

The value of the tag will be used as the name of the image (corresponding to the class= attribute). So for instance, <bundle type="systemd" class="extension">foobar</bundle> corresponds to a sysext named "foobar". For class="sysupdate", there is a special case: if the value is empty, then the bundle actually refers to the host system.

Examples

<component type="addon">
	<id>com.example.Devel</id>
	<extends>com.example.OS</extends>
	<name>Development Tools</name>
	<summary>Tools essential to develop Example OS</summary>
	<provides>
		<binary>gcc</binary>
		<binary>g++</binary>
		<binary>make</binary>
		<binary>autoconf</binary>
		<binary>cmake</binary>
		<binary>meson</binary>
		<binary>ninja</binary>
	</provides>
	<developer_name>Example, inc.</developer_name>
	<releases>
		<release version="45" date="2024-01-15" />
		<release version="44" date="2023-12-08" />
		<release version="43" date="2023-11-10" />
	</releases>
	<bundle type="systemd" class="extension">devel</bundle>
</component>

defines a sysext named devel to be presented by the software center. It will be updated via systemd-sysupdated's extension:devel target. It will be treated as a plugin for the operating system itself.

<component merge="append">
	<id>com.example.OS</id>
	<releases>
		<release version="45" date="2024-01-15" urgency="high">
			<description>
				<p>This release includes various bug fixes and performance improvements</p>
			</description>
		</release>
	</releases>
	<bundle type="systemd" class="sysupdate" />
</component>

extends existing appstream metadata for the host OS with a changelog. It also tells the software center that the host OS should be updated using the host target for systemd-sysupdated.

<component type="service">
	<id>com.example.Foobar</id>
	<name>Foobar Service</name>
	<summary>Service that does foo to bar</summary>
	<icon type="remote">https://example.com/products/foobar/logo.svg</icon>
	<url type="homepage">https://example.com/products/foobar</url>
	<provides>
		<dbus type="system">com.example.Foobar</dbus>
	</provides>
	<developer_name>Example, inc.</developer_name>
	<releases>
		<release version="1.0.1" date="2024-02-16" urgency="critical">
			<description>
				<p>This release fixes a major security vulnerability. Please update ASAP.</p>
			</description>
			<issues>
				<issue type="cve">CVE-2024-28153</issue>
			</issues>
		</release>
		<release version="1.1-beta" date="2024-01-08" type="development" />
		<release version="1.0" date="2023-11-23">
			<description>
				<p>Initial release!</p>
			</description>
		</release>
	</releases>
	<bundle type="systemd" class="portable">foobar</bundle>
</component>

defines a portable service named foobar to be presented by the software center. It will be updated via systemd-sysupdated's portable:foobar target. It will be marked as an urgent update. It will be presented to the user with a display name, a description, and a custom icon.