ParseVersionString

Defines the following functions related to handling possibly non-CMake-compliant version strings:

cet_compare_versions()

Compare versions semantically, taking account of Greek, pre-release, release candidate, and patch versions. Returns TRUE or FALSE according to a user-provided predicate specification.

cet_version_cmp()

Low-level “spaceship operator” comparison between two versions, returning -1, 0, or 1.

parse_version_string()

Parse and process a version string or list.

to_cmake_version()

Convert a version string or list into a CMake-compliant version string.

to_dot_version()

Convert a version string or list into a .-delimited version string.

to_version_string()

Convert a version string or list into a .-delimited version string with --separated non-numeric extra component.

cetbuildtools

See also

to_ups_version(), check_prod_version().

cet_compare_versions
cet_compare_versions(<result-var> <version> <pred> <ref-version>)

Compare <version> with <ref-version> semantically according to predicate <pred>, respecting any trailing non-numeric version components <extra>, and placing the answer in <result-var>.

Details

<pred> is valid if there exists a CMake if() predicate VERSION_<pred>.

Comparison order for (<version>-?)?(<extra-text>(-?<extra-num>)?)?:

  • <version>-?alpha(-?[0-9]+)? <

  • <version>-?beta(-?[0-9]+)? <

  • <version>-?gamma(-?[0-9]+)? <

  • <version>-?(rc|pre)(-?[0-9]+)? <

  • <version>-? <

  • <version>-?(patch-?[0-9]*|p-?[0-9]+) <

  • <version>-?.+ <

  • <extra>

Non-numeric component prefixes such as alpha, beta, etc. are case-insensitive, and equivalent prefixes (Alpha-1 and a01, say, or pre and rc) will compare equal.

A version string—after the stripping of a single leading v if present—beginning with a separator or non-numeric character will always compare greater than a similarly stripped version string beginning with a numeric component, and equal to every other such version string regardless of any numeric suffix.

A non-numeric component with no numeric suffix will compare equal to an equivalent non-numeric component with a numeric suffix comparing equal to 0 numerically.

Numeric version components—including any numeric suffix to a trailing non-numeric component—will always be compared numerically i.e. without regard to leading zeros.

cet_version_cmp
cet_compare_versions(<result-var> <version> <ref-version>)

Low-level “spaceship operator” comparison between <version> and <ref-version>, returning -1, 0 or 1 in <result-var> based on whether <version> is semantically less than, equal to or greater than <ref-version>.

cf cet_compare_versions().

parse_version_string

Version parsing and transformation.

parse_version_string([VERSION] <version> [<options>] <var> [<var> ...])
parse_version_string(SEP <output-sep> [VERSION] <version>  [<options>] <var>)

Common Options

INPUT_PREAMBLE <pre>

<pre> will be removed from the beginning of <version> prior to parsing (if present). Default “v.”

[VERSION] <version>

The version to be parsed and/or transformed. <version> may be:

  1. A version string of the form:

    [<pre>][<major>[<sep><minor>[<sep><patch>[<sep><tweak>]]]]
[<extra-sep>][<extra>]

  2. A semi-colon-separated list of version components.

  3. The name of a CMake variable containing either of the above.

Signatures

parse_version_string(VERSION <version> ...)
parse_version_string(VERSION <version> [<options>] <var> [<var> ...])

Parse a version string into its component parts to be returned in <var>.

Details

If there is one <var> it will contain a list of all parsed components (<major>, <minor>, <patch>, <tweak> and <extra>); for multiple, the components will be mapped to each <var> with un-placed components being discarded.

<sep> may be -, _, or .

Per CMake convention: <major>, <minor>, <patch>, and <tweak> must be non-negative integers (with optional leading zeros), so <extra> starts from the first non-separator, non-numeric character after any numeric version components have been identified.

parse_version_string(SEP <output-sep> [VERSION] <version> ...)
parse_version_string(SEP <output-sep> [VERSION] <version> [<options>] <var>)

Transform <version> into an <output-sep>-delimited version string, returned in <var>.

Options

EXTRA_SEP <output-extra-sep>

<extra>—if present—will be separated from the rest of the version string by <output-extra-sep>.

NO_EXTRA

<extra> will be omitted from <var>; mutually exclusive with EXTRA_SEP.

PREAMBLE <output-preamble>

<output-preamble> will be prepended to <var>.

Details

Vacuous intermediate components will be represented by 0 in <var>.

to_cmake_version
to_cmake_version(<version> <var> ...)

Equivalent to:

parse_version_string(<version> SEP . NO_EXTRA ...)
to_dot_version
to_dot_version(<version> <var> ...)

Equivalent to:

parse_version_string(<version> SEP . <var> ...)
to_version_string
to_version_string(<version> <var> ...)

Equivalent to:

parse_version_string(<version> SEP . EXTRA_SEP - <var>...)