Version¶

Usage

use Version;

or

import Version;

Support for reasoning about version numbers.

This module contains features that support reasoning about version numbers. The versionValue type supports compile-time reasoning about version numbers in general, and Chapel version numbers specifically, while the version type supports run-time reasoning about version numbers.

In more detail, the module features:

chplVersion: the version number of the copy of chpl used to compile the program.
versionValue: a type that can be used to represent a semantic version number plus an optional commit value. This type supports compile-time reasoning about version numbers.
version: a type that can be used to represent a semantic version number plus an optional commit value. This type supports run-time reasoning about version numbers.

Version numbers in versionValue are represented using param values to permit code specialization by being able to reason about versions at compile-time.

The versionValue type supports:

being printed out or cast to a param string
compile-time comparisons via ==, !=, <, <=, >, and >. Generally speaking, “less than” corresponds to “is an earlier version than.” For example:
```
if chplVersion < new versionValue(1,23) then
  compilerWarning("This package doesn't support 'chpl' prior to 1.23.0");
```

Version numbers in version are represented using var values to permit constructing and assigning version number values at run-time.

The version type supports:

being printed out or cast to a string
run-time comparisons via ==, !=, <, <=, >, and >. Generally speaking, “less than” corresponds to “is an earlier version than.”

The type versionValue is useful for modifying compilation behavior, such as requiring a minimum version of the Chapel compiler. The type version is useful for reasoning about version numbers that are not known at compile-time, such as values read from a text file.

Comparisons between two versionValue, two version, or a versionValue and a version are supported. Equality/inequality operations check whether or not the two values have identical major, minor, update, and commit values.

Ordered comparisons are based on the ordering of the semantic versions of the two values, as defined by their major, minor, and update components. Note that if the two values have identical semantic versions, any cases that rely on an ordering of the commits will generate an error if the values have differing, non-empty commit values due to the challenge of ordering commits. An empty commit value is considered to come after (be greater than) a non-empty value, as the former is considered an official release and the latter a pre-release.

For example:

// any of the following variable declarations can be replaced with
// `const vN = new versionValue(...)` instead of using the version type
// and the comparison results would remain the same

var v1 = new version(1, 2, 3);
var v2 = new version(1, 2, 4);
var v3 = new version(1, 2, 4, "abc");
var v4 = new version(1, 2, 4, "def");

writeln(v1 < v2); // prints "true"
writeln(v2 < v3); // prints "false" as v3 and v4 are considered pre-releases of v2
writeln(v3 < v4); // error: cannot compare commits of different versions

var v5 = new version(1, 2, 4, "abc");
writeln(v3 == v5); // prints "true"
writeln(v3 != v5); // prints "false"

const chplVersion¶

The version of chpl used to compile this program. For an official Chapel release, this will have an empty commit value, while for a pre-release, it will indicate the Git SHA.

Note that, for historical reasons, Chapel 1.x.y/2.x.y corresponds to version 0.x.y/1.x.y in traditional semantic versioning.

type sourceVersion = versionValue¶: Warning

sourceVersion is deprecated, please use versionValue instead.

This record represents a software version that is modeled after a semantic version. It uses param values to represent its components in order to support compile-time comparison of version numbers which in turn permits code to specialize to specific versions of Chapel. When printed or converted to a string, it is represented as major.minor.update (commit). Note that ordered comparisons between two sourceVersion values that only differ in their commit values are not supported due to the challenges involved in ordering commit values. However, when a value with an empty update value is compared to one whose update is non-empty, the latter is considered to be earlier than (less than) the former, due to the interpretation that it represents a pre-release of the official release.

proc createVersion(param major: int, param minor: int, param update: int = 0, param commit: string = "") : sourceVersion(?)¶: Warning

createVersion is deprecated, please use ‘new versionValue()’ instead.

A helper function that creates a new sourceVersion from its arguments. :arg major: The major version number :type major: int :arg minor: The minor version number :type minor: int :arg update: The optional update version number (defaults to 0) :type update: int :arg commit: The optional commit ID (defaults to “”) :type commit: string :returns: A new version value of type sourceVersion.

record versionValue : writeSerializable¶

This record represents a software version that is modeled after a semantic version, though not 100% true to the semver spec. The main deviation from the spec is that versionValue doesn’t support pre-release identifiers and the version and optional build/commit value are separated with a space rather than with +. See semver.org for details on the spec.

The versionValue uses param values to represent its components in order to support compile-time comparison of version numbers which in turn permits code to specialize to specific versions of Chapel. When printed or converted to a string, it is represented as major.minor.update (commit).

param major : int¶: The major version number. For version 2.0.1, this would be 2.

param minor : int¶: The minor version number. For version 2.0.1, this would be 0.

param update : int¶: The update version number. For version 2.0.1, this would be 1.

param commit : string = ""¶: The commit ID of the version (e.g., a Git SHA)

record version : writeSerializable¶

This record represents a software version similar to the versionValue. It uses var values to represent its components in order to support run-time building and comparison of version numbers. When printed or converted to a string, it is represented as major.minor.update (commit). Unlike versionValue, a version can be created and modified at runtime.

var major : int¶: The major version number. For version 2.0.1, this would be 2. Defaults to -1

var minor : int¶: The minor version number. For version 2.0.1, this would be 0. Defaults to -1

var update : int¶: The update version number. For version 2.0.1, this would be 1. Defaults to 0

var commit : string = ""¶: The commit ID of the version (e.g., a Git SHA) Defaults to ""

class VersionComparisonError : Error¶

Error class thrown when two versions are compared that cannot be compared.

For example, two versions differing only in commit IDs cannot be compared.