search

hughsie / appstream-glib

This library provides objects and helper methods to help reading and writing AppStream metadata.
GNU Lesser General Public License v2.1
63 stars 102 forks source link

readme

⚠️ WARNING: appstream-glib is heavy maintenance mode, use appstream instead

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:

For more information about what AppStream is, please see the wiki here: https://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 \
            json-glib-devel libarchive-devel libcurl-devel \
            libuuid-devel libyaml-devel \
            meson rpm-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:

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 \
            libuuid-devel libyaml-devel \
            meson rpm-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:

Guidelines for applications

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

First, some key words:

The current rules of inclusion are thus:

Guidelines for fonts

License

LGPLv2+