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 ofchpl
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
stringcompile-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 emptycommit
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 version0.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 asmajor.minor.update (commit)
. Note that ordered comparisons between twosourceVersion
values that only differ in theircommit
values are not supported due to the challenges involved in ordering commit values. However, when a value with an emptyupdate
value is compared to one whoseupdate
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
usesparam
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 asmajor.minor.update (commit)
.- param major: int¶
The major version number. For version
2.0.1
, this would be2
.
- param minor: int¶
The minor version number. For version
2.0.1
, this would be0
.
- param update: int¶
The update version number. For version
2.0.1
, this would be1
.
- 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 usesvar
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 asmajor.minor.update (commit)
. UnlikeversionValue
, aversion
can be created and modified at runtime.- var major: int¶
The major version number. For version
2.0.1
, this would be2
. Defaults to-1
- var minor: int¶
The minor version number. For version
2.0.1
, this would be0
. Defaults to-1
- var update: int¶
The update version number. For version
2.0.1
, this would be1
. Defaults to0
- 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.