This library provides objects and helper methods to help reading and writing AppStream metadata.
C Meson Other
Switch branches/tags
appstream_glib_0_7_12 appstream_glib_0_7_11 appstream_glib_0_7_10 appstream_glib_0_7_9 appstream_glib_0_7_8 appstream_glib_0_7_7 appstream_glib_0_7_6 appstream_glib_0_7_5 appstream_glib_0_7_4 appstream_glib_0_7_3 appstream_glib_0_7_2 appstream_glib_0_7_1 appstream_glib_0_7_0 appstream_glib_0_6_13 appstream_glib_0_6_12 appstream_glib_0_6_11 appstream_glib_0_6_10 appstream_glib_0_6_9 appstream_glib_0_6_8 appstream_glib_0_6_7 appstream_glib_0_6_6 appstream_glib_0_6_5 appstream_glib_0_6_4 appstream_glib_0_6_3 appstream_glib_0.6.2 appstream_glib_0.6.1 appstream_glib_0_5_19 appstream_glib_0_5_18 appstream_glib_0_5_17 appstream_glib_0_5_16 appstream_glib_0_5_15 appstream_glib_0_5_14 appstream_glib_0_5_13 appstream_glib_0_5_12 appstream_glib_0_5_11 appstream_glib_0_5_10 appstream_glib_0_5_9 appstream_glib_0_5_8 appstream_glib_0_5_7 appstream_glib_0_5_6 appstream_glib_0_5_5 appstream_glib_0_5_4 appstream_glib_0_5_3 appstream_glib_0_5_2 appstream_glib_0_5_1 appstream_glib_0_5_0 appstream_glib_0_4_1 appstream_glib_0_4_0 appstream_glib_0_3_6 appstream_glib_0_3_5 appstream_glib_0_3_4 appstream_glib_0_3_3 appstream_glib_0_3_2 appstream_glib_0_3_1 appstream_glib_0_3_0 appstream_glib_0_2_8 appstream_glib_0_2_7 appstream_glib_0_2_6 appstream_glib_0_2_5 appstream_glib_0_2_4 appstream_glib_0_2_3 appstream_glib_0_2_2 appstream_glib_0_2_1 appstream_glib_0_2_0 appstream_glib_0_1_7 appstream_glib_0_1_6 appstream_glib_0_1_5 appstream_glib_0_1_4 appstream_glib_0_1_3 appstream_glib_0_1_2 appstream_glib_0_1_1 appstream_glib_0_1_0
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

AppStream-Glib

This library provides GObjects and helper methods to make it easy to read and write AppStream metadata. It also provides a simple DOM implementation that makes it easy to edit nodes and convert to and from the standardized XML representation. It also supports reading of Debian-style DEP-11 metadata.

What this library allows you to do:

  • Read and write compressed AppStream XML files
  • Read compressed Debian YAML files
  • Add and search for applications in an application store
  • Get screenshot image data and release announcements
  • Easily retrieve the best application data for the current locale
  • Efficiently interface with more heavy-weight parsers like expat

For more information about what AppStream is, please see the wiki here: http://www.freedesktop.org/wiki/Distributions/AppStream/

Getting Started

To install the libappstream-glib library you either need to install the libappstream-glib package from your distributor, or you can build a local copy. To do the latter just do:

dnf install docbook-utils gettext-devel glib-devel \
            gobject-introspection-devel gperf gtk-doc gtk3-devel \
            libarchive-devel libsoup-devel \
            libstemmer-devel libuuid-devel libyaml-devel \
            meson rpm-devel sqlite-devel
mkdir build && cd build
meson .. --prefix=/opt -Dbuilder=false
ninja

Hacking

If you want a new feature, or have found a bug or a way to crash this library, please report as much information as you can to the issue tracker: https://github.com/hughsie/appstream-glib/issues -- patches very welcome.

New functionality or crash fixes should include a test in libappstream-builder/ as-self-test.c to ensure we don't regress in the future. New functionality should also be thread safe and also not leak any memory for success or failure cases.

Translations

Translations of the natural language strings are managed through a third party translation interface, transifex.com. Newly added strings will be periodically uploaded there for translation, and any new translations will be merged back to the project source code.

Please use https://www.transifex.com/projects/p/appstream-glib/ to contribute translations, rather than sending pull requests.

AppStream-Builder

appstream-builder is a tool that allows us to create AppStream metadata from a directory of packages. It is typically used when generating distribution metadata, usually at the same time as modifyrepo or createrepo.

What this tool does:

  • Searches a directory of packages and reads just the RPM header of each.
  • If a package contains an interesting file, just the relevant files are decompressed from the package archive.
  • A set of plugins are run on the extracted files, and if these match certain criteria AsbApplication objects are created.
  • Any screenshots referenced are downloaded to a local cache. This is optional and can be disabled with --nonet.
  • When all the packages are processed, some of the AsbApplication objects are merged into single applications. This is how fonts are collected.
  • The AsbApplication objects are serialized to XML and written to a compressed archive.
  • Any application icons or screenshots referenced are written to a .tar archive.

Getting Started

To run appstream-builder you either need to install the package containing the binary and data files, or you can build a local copy. To do the latter just do:

dnf install docbook-utils gettext-devel glib-devel \
            gobject-introspection-devel gperf gtk-doc gtk3-devel \
            libarchive-devel libsoup-devel \
            libstemmer-devel libuuid-devel libyaml-devel \
            meson rpm-devel sqlite-devel rpm-devel
mkdir build && cd build
meson .. --prefix=/opt -Dbuilder=true
ninja

To actually run the extractor you can do:

./client/appstream-builder --verbose   \
                  --max-threads=8 \
                  --log-dir=/tmp/logs \
                  --packages-dir=/mnt/archive/Megarpms/21/Packages \
                  --temp-dir=/mnt/ssd/AppStream/tmp \
                  --output-dir=./repodata \
                  --screenshot-url=http://megarpms.org/screenshots/ \
                  --basename="megarpms-21"

Note: it is possible to use "globs" like /mnt/archive/Megarpms/21/Packages* to match multiple directories or packages.

This will output a lot of progress text. Now, go and make a cup of tea and wait patiently if you have a lot of packages to process. After this is complete you should finally see:

Writing ./repodata/megarpms-21.xml.gz
Writing ./repodata/megarpms-21-failed.xml.gz
Writing ./repodata/megarpms-21-ignore.xml.gz
Writing ./repodata/megarpms-21-icons.tar
Done!

You now have two choices what to do with these files. You can either upload them with the rest of the metadata you ship (e.g. in the same directory as repomd.xml and primary.sqlite.bz2) which will work with Fedora 22 and later:

modifyrepo_c \
    --no-compress \
    /tmp/asb-md/appstream.xml.gz \
    /path/to/repodata/
modifyrepo_c \
    --no-compress \
    /tmp/asb-md/appstream-icons.tar.gz \
    /path/to/repodata/

You can then do something like this in the megarpms-release.spec file:

Source1:   http://www.megarpms.org/temp/megarpms-20.xml.gz
Source2:   http://www.megarpms.org/temp/megarpms-20-icons.tar.gz

%install
DESTDIR=%{buildroot} appstream-util install %{SOURCE1} %{SOURCE2}

This ensures that gnome-software can access both data files when starting up.

What is an application

Applications are defined in the context of AppStream as such:

  • Installs a desktop file and would be visible in a desktop
  • Has an metadata extractor (e.g. libappstream-builder/plugins/asb-plugin-gstre amer.c) and includes an AppData file

Guidelines for applications

These guidelines explain how we filter applications from a package set.

First, some key words:

  • SHOULD: The application should do this if possible
  • MUST: The application or addon must do this to be included
  • CANNOT: the application or addon must not do this

The current rules of inclusion are thus:

  • Icons MUST be installed in /usr/share/pixmaps/*, /usr/share/icons/*, /usr/share/icons/hicolor/*/apps/*, or /usr/share/${app_name}/icons/*
  • Desktop files MUST be installed in /usr/share/applications/ or /usr/share/applications/kde4/
  • Desktop files MUST have Name, Comment and Icon entries
  • Valid applications with NoDisplay=true MUST have an AppData file.
  • Applications with Categories=Settings, Categories=ConsoleOnly or Categories=DesktopSettings MUST have an AppData file.
  • Applications MUST have had an upstream release in the last 5 years or have an AppData file.
  • Application icon MUST be available in 48x48 or larger
  • Applications must have at least one main or additional category listed in the desktop file or supply an AppData file. See http://standards.freedesktop.org/menu-spec/latest/apa.html and http://standards.freedesktop.org/menu-spec/latest/apas02.html for the full Categories list.
  • Codecs MUST have an AppData file
  • Input methods MUST have an AppData file
  • If included, AppData files MUST be valid XML
  • AppData files MUST be installed into /usr/share/appdata
  • Application icons CANNOT use XPM or ICO format
  • Applications CANNOT use obsolete toolkits such as GTK+-1.2 or QT3
  • Applications that ship a desktop file SHOULD include an AppData file.
  • Screenshots SHOULD be in 16:9 aspect ratio
  • Application icons SHOULD have an alpha channel
  • Applications SHOULD ship a 256x256 PNG format icon or scalable SVG
  • Applications SHOULD ship a matching High Contrast icon
  • Applications SHOULD not depend on other applications
  • AppData files SHOULD include translations
  • Desktop files SHOULD include translations

Guidelines for fonts

  • Fonts MUST have a valid MetaInfo file installed to /usr/share/appdata
  • Fonts packaged in multiple packages SHOULD have multiple MetaInfo files
  • Fonts families SHOULD only have one description section
  • Fonts of different styles or weights of the same family SHOULD use <exte nds>
  • MetaInfo files SHOULD include translations where possible

License

LGPLv2+