Miscellaneous | AppStream | AppStream 1.0
Description: This chapter describes additional features AppStream provides that are related to the metadata specification. 4.1 Version Comparison Algorithm #4.1.1 Introduction # The AppStream specification requires the presence of version numbers in various locations, and AppStream-using clients will occasionall…

Jump to content Jump to page navigation: previous page [access key p]/next page [access key n]
AppStream
AppStream › Miscellaneous
AppStream › Miscellaneous
Top
←→
Applies to AppStream 1.0

# 4 Miscellaneous #

This chapter describes additional features AppStream provides that are related to the metadata specification.

## 4.1 Version Comparison Algorithm #

### 4.1.1 Introduction #

The AppStream specification requires the presence of version numbers in various locations, and AppStream-using clients will occasionally need to compare version numbers in order to determine the latest version. This document describes how version comparisons should be performed.

### 4.1.2 Algorithm #

AppStream's version comparison algorithm is a compromise between the ones used by the Fedora and Debian Linux distributions (after RPM's algorithm was extended to handle the tilde character like Debian). It should compare most versions like DPKG/RPM, except for letters after a dot, so e.g. `1.0 << 1.a` (like in Debian, but unlike in RPM). Unfortunately due to differences between the RPM and DPKG worlds, this issue can not be resolved without breakage. The algorithm is described for Debian here (https://manpages.debian.org/unstable/dpkg-dev/deb-version.5.en.html#Sorting_algorithm), the description is also reproduced below:

The version strings are compared from left to right.

First the initial part of each string consisting entirely of non-digit characters is determined. These two parts (one of which may be empty) are compared lexically. If a difference is found it is returned. The lexical comparison is a comparison of ASCII values modified so that all the letters sort earlier than all the non-letters and so that a tilde sorts before anything, even the end of a part. For example, the following parts are in sorted order: `~~`, `~~a`, `~`, the empty part, `a`.

Then the initial part of the remainder of each string which consists entirely of digit characters is determined. The numerical values of these two parts are compared, and any difference found is returned as the result of the comparison. For these purposes an empty string (which can only occur at the end of one or both version strings being compared) counts as zero.

These two steps (comparing and removing initial non-digit strings and initial digit strings) are repeated until a difference is found or both strings are exhausted.

### 4.1.3 Recommendations #

For meaningful version numbers, consider following semantic versioning (https://semver.org/).

A version number should always start with a number. Do not start version numbers with a letter or make them consist entirely of letters, e.g. `BETA` is not a version number.

If you want to denote a prerelease, consider appending the prerelease identifier string after a tidle. For example use `1.0~alpha1` for an alpha release of the upcoming `1.0` release. The alpha release will then considered lower than the final release.

Avoid using any epochs (colons) in your upstream version numbers. Versions like `1:2.4` will cause problems with downstreams.

### 4.1.4 Implementation #

You can read AppStream's code for version comparisons here (https://github.com/ximion/appstream/blob/master/src/as-vercmp.c).

If you want to quickly test version comparisons for your software and arbitrary versions, consider using the `vercmp` subcommand of the `appstreamcli` utility.

Examples:

    $ appstreamcli vercmp 1.0 2.0
    1.0 << 2.0
    $ appstreamcli vercmp 2.0 2.0~a1
    2.0 >> 2.0~a1
    $ appstreamcli vercmp 2.4 lt 2.1
    false: 2.4 >> 2.1
    $ appstreamcli vercmp 1.2.4 gt 1.2.3
    true: 1.2.4 >> 1.2.3