Supporting "AppStream" is an almost impossible task.

**This issue should serve as a place to discuss all this mess that supporting the Freedesktop.org "standard" for AppStream metadata is for application developers as well as AppImage maintainers, and how (if at all) it can be solved or worked around...**

----

Here is a collection of stuff I encountered on a Debian Stretch system yesterday when I *`"--appimage-extract"`*-ed a perfectly working AppImage which had no AppStream metadata included and where I wanted to regenerate it after inclusion of just that info.

1. Let the application be called *foo*.
1. Provide an initial AppStream file as *usr/share/metainfo/foo.appdata.xml*.
1. Provide an initial .desktop file as *usr/share/applications/foo.desktop*.
1. Let the AppImage creation command be *`appimagetool foo-squashfs-root foo.AppImage`

## Presence of `appstream-util` on the system

When this utility is present, it chases the developer in circles. Be my witness with going through the following stages:

1. Say, your *`foo.appdata.xml`* file contains the line:

foo.desktop

You then get something posing as a *Warning* but which nevertheless stops creating the AppImage, and you'll read this message:

Using architecture x86_64
/home/kp/AppDirs/foo-squashfs-root should be packaged as ../foo.AppImage
W - foo.appdata.xml:foo.desktop:3
The component ID is not a reverse domain-name. Please update the ID and that of
the accompanying .desktop file to follow the latest version of the Desktop-Entry
and AppStream specifications and avoid future issues.

Validation failed: warnings: 1
Failed to validate AppStream information with appstreamcli

1. Next, you try to fix it and make the above line now read

org.oneapplication.foo.desktop

and rename your .desktop file accordingly to *usr/share/applications/org.oneapplication.foo.desktop*.

Now you still have no AppImage, but you successfully changed that "Warning" message to

Using architecture x86_64
/home/kp/AppDirs/foo-squashfs-root should be packaged as ../foo.AppImage
W - foo.appdata.xml:org.oneapplication.foo.desktop
The metainfo filename does not match the component ID.

Validation failed: warnings: 1
Failed to validate AppStream information with appstreamcli

1. Next, you try to fix that last issue and rename the .desktop file to now be *usr/share/metainfo/org.oneapplicaton.foo.appdata.xml*:

WARNING: AppStream upstream metadata is missing, please consider creating it
in usr/share/metainfo/foo.appdata.xml
Please see https://www.freedesktop.org/software/appstream/docs/chap-Quickstart.html#sect-Quickstart-DesktopApps
for more information or use the generator at http://output.jsbin.com/qoqukof.

(appstream-util:7983): GLib-CRITICAL **: g_ptr_array_set_size: assertion 'rarray' failed
AppStream template has been generated in in /home/kp/AppDirs/foo-squashfs-root/usr/share/metainfo/foo.appdata.xml, please edit it

**Bravo,** you've now turned full circle (and been sent to read some "quickstart" document on Freedesktop.org).

## Disabled `appstream-util` on the system

4. This ominous *`appstream-util:7983`* gave you the hint to temporarily knock out and disable that dear goody by running *`sudo mv /usr/bin/appstream-util{,___ko}`* and then try to create the AppImage one more time. Oh, beautiful:

````
AppStream upstream metadata found in usr/share/metainfo/foo.appdata.xml
W - foo.appdata.xml:foo.desktop:3
The component ID is not a reverse domain-name. Please update the ID and that of
the accompanying .desktop file to follow the latest version of the Desktop-Entry
and AppStream specifications and avoid future issues.

W - org.oneapplicaton.foo.appdata.xml:org.oneapplication.foo.desktop
The metainfo filename does not match the component ID.

E - foo.appdata.xml:foo.desktop
Component metadata refers to a non-existing .desktop file.

W - foo.appdata.xml:foo.desktop:16
SPDX license ID 'XXX: Insert SPDX value here' is unknown.

W - foo.appdata.xml:foo.desktop:15
The metadata itself does not seem to be licensed under a permissive license.
Please license the data under a permissive license, like FSFAP, CC-0-1.0 or MIT to
allow distributors to include it in mixed data collections without the risk of
license violations due to mutually incompatible licenses.

I - foo.appdata.xml:foo.desktop:8
First 'description/p' paragraph might be too short (< 100 characters).

Validation failed: errors: 1, warnings: 4, infos: 1
Failed to validate AppStream information with appstreamcli
````

^{**Oh, BTW: the metadata license which above warning complained about was set as `MIT`.** Just sayin'...}

1. Ah, ok... remove that AppStream template which was created before by the friendly *`appstream-util`* tool:

rm -rf usr/share/metainfo/foo.appdata.xml

1. Congratulations, your AppImage is being created -- however, it is missing the AppStream metadata:

````
Using architecture x86_64
/home/kp/AppDirs/foo-squashfs-root should be packaged as ../foo.AppImage
WARNING: AppStream upstream metadata is missing, please consider creating it
in usr/share/metainfo/foo.appdata.xml
Please see https://www.freedesktop.org/software/appstream/docs/chap-Quickstart.html#sect-Quickstart-DesktopApps
for more information or use the generator at http://output.jsbin.com/qoqukof.
Generating squashfs...
Parallel mksquashfs: Using 2 processors
Creating 4.0 filesystem on ../foo.AppImage, block size 131072.
[=========================================================\] 1130/1130 100%
[....]
Success
````

1. You've (almost) turned full circle now. Except, that your AppStream data is now provided as

ls -l usr/share/metainfo/
-rw-r--r-- 1 kp kp 1877 Dec 30 05:23 org.oneapplication.foo.appdata.xml

Let's rename it to *foo.appdata.xml* again:

mv usr/share/metainfo/{org.oneapplication.,}foo.appdata.xml

after all, this is what appimagetool seems to be looking for. You AppImage creation now is canceled and ends with this message:

````
Using architecture x86_64
/home/kp/AppDirs/foo-squashfs-root should be packaged as ../foo.AppImage
AppStream upstream metadata found in usr/share/metainfo/foo.appdata.xml
W - foo.appdata.xml:org.oneapplication.foo.desktop
The metainfo filename does not match the component ID.

Validation failed: warnings: 1
Failed to validate AppStream information with appstreamcli
````

## On the recommended *chap-Quickstart.html* resource

8. Next, read that document which had been hinted at before (https://www.freedesktop.org/software/appstream/docs/chap-Quickstart.html#sect-Quickstart-DesktopApps). You find a recommendation about a tag called **``**, which leads you to add the following line to your AppStream XML file:

org.oneapplication.foo.desktop

You go back to the situation in step 6, where at least an AppImage without AppStream metadata was created and run *`appimagetool`* one more time:

Thank goodness, the AppImage is still created...

1. Let's enable *`appstream-util`* again, just to see how it groks that line:

sudo mv /usr/bin/appstream-util{___ko,}

Fantastic!, now you *again* get no AppImage, but you are entertained with a different message:

````
Using architecture x86_64
/home/kp/AppDirs/foo-squashfs-root should be packaged as ../foo.AppImage
AppStream upstream metadata found in usr/share/metainfo/foo.appdata.xml
W - foo.appdata.xml:org.oneapplication.foo.desktop:35
Found invalid tag: 'launchable'. Non-standard tags must be prefixed with "x-".

W - foo.appdata.xml:org.oneapplication.foo.desktop
The metainfo filename does not match the component ID.

Validation failed: warnings: 2
Failed to validate AppStream information with appstreamcli
````

Don't you also love it, if you follow the Freedesktop recommendations for tag names, and then a Freedesktop-recommended tool tells you that you have to re-name the tag to prefix it with an "x-"?