diff --git a/docs/sources/metainfo/MetaInfo.xml b/docs/sources/metainfo/MetaInfo.xml index d18af29b8..893d34e9f 100644 --- a/docs/sources/metainfo/MetaInfo.xml +++ b/docs/sources/metainfo/MetaInfo.xml @@ -29,6 +29,7 @@ + diff --git a/docs/sources/metainfo/component.xml b/docs/sources/metainfo/component.xml index 9bf76a1f7..e8fe40d42 100644 --- a/docs/sources/metainfo/component.xml +++ b/docs/sources/metainfo/component.xml @@ -253,17 +253,55 @@ <launchable/> - This optional tag indicates a possible method to launch the software described in this component. At time, it only supports launching software by their desktop-id. - - - The <launchable/> tag has a essential type property indicating the system that is used to launch the application. At time, only - desktop-id is allowed as value, indicating that an application can be launched via a desktop file. The value of the tag is a - desktop-file id in that case. - - - The <launchable/> tag is allowed to appear multiple times in the metainfo data. In case a software component has multiple launchable entries, - the software center might display a dialog to choose which entry to launch. If possible though, it should be avoided to add multiple launchable tags. - + This optional tag indicates possible methods to launch the software described in this component. + It is allowed to appear multiple times in the metainfo data. + + + + The <launchable/> tag has a essential type property indicating the system that is used to launch the component. The following types are allowed: + + + + desktop-id + + + The application can be launched via a desktop file. The value of the tag is a + desktop-file id. + + + In case a software component has multiple launchable entries, + the software center might display a dialog to choose which entry to launch. + If possible though, it should be avoided to add multiple launchable tags of type desktop-id. + + + + + service + + + The software can be started, stopped, and monitored by the OS "init" + facility, such as systemd. The value of the tag is a name that can be + used with that facility, such as a systemd unit name. + + + Multiple launchable tags of type service are not + alternatives to start the same service, but the + component does contain multiple services that might all need to be + started. + + + Only those services should be listed as launchables that the user is + actually expected to start and stop manually. Services that are + started/stopped indirectly via dependencies of other services should + not be listed. + + + For systemd units, the services listed as launchables are expected to + support enabling and disabling. + + + + Example: diff --git a/docs/sources/metainfo/service.xml b/docs/sources/metainfo/service.xml new file mode 100644 index 000000000..26cd14541 --- /dev/null +++ b/docs/sources/metainfo/service.xml @@ -0,0 +1,110 @@ + + +%BOOK_ENTITIES; +]> + +
+ Services + +
+ Introduction + + A service component is any software that is started and supervised by + the Operating Systems "init" facility, such as systemd. + + + The metadata described in this document is built upon the generic component metadata with fields specific for services (see ). + All tags valid for a generic component are valid for a service component as well. + + + In order to enhance the available metadata about their services, projects shipping a service can ship one or more metainfo files + in /usr/share/metainfo/%{id}.metainfo.xml. + + +
+ +
+ File specification + + + The basic structure for a generic component as described at applies. + Note that the XML root must have the type property set to service, while in a generic component this + property can be omitted. This clearly identified this metainfo document as describing a service. + + + + The following list describes tags for service upstream metadata and provides some additional information about the values + the tags are expected to have. + If no information is given about a tag, refer to the respective tag in . + + + + + <id/> + + + For services, the <id/> tag value must follow the AppStream ID naming conventions (it should be a reverse-DNS name). + + + + + + <metadata_license/> + + + The <metadata_license/> tag as described in must be present. + + + + + + <name/> + + + A name must be present for services. See for a detailed description of this tag. + + + + + + <summary/> + + + A summary must be present for services. See for a detailed description of this tag. + + + + + + <provides/> ↪ <service/> + + + This tag is described in detail for generic components at . + + + + + + <launchable/> + + + This tag is described in detail for generic components at . + + + At least one launchable element with type "service" must be present. + The value is a name that can be used with the OS init facility to + start/stop and monitor the service. + + + + + + + + For a component of type service, the following tags are required and must always be present: , + , , , . + + +
+